Use Wowza Streaming Engine startup packages to configure an Amazon EC2 instance

Updated on 10/25/2021 1:14 pm PDT

A Wowza Streaming Engine™ media server software for Amazon EC2 startup package is a compressed (zipped) folder that contains a startup manifest file (startup.xml), configuration files, and scripts. It allows you to configure a Wowza Streaming Engine instance for EC2 at launch time by passing in user data. Wowza provides pre-built startup packages that you can download from the Wowza Startup Packages webpage. You can use them as-is or you can modify them to meet your requirements. If you don't specify a startup package when you launch your instance, a default startup package is used.

If you load your own startup package when launching an instance, the default startup package won't be used. Your startup package must provide all of the application configurations that are required for streaming.

Contents

Wowza Streaming Engine startup packages
Load a startup package
Debug a startup package
Overview of startup packages

Wowza Streaming Engine startup packages

Wowza provides several pre-built startup packages that you can download from the Wowza Startup Packages webpage. You can use them "as-is" or you can modify them to meet your requirements.

If you launch a Wowza Streaming Engine for EC2 AMI without specifying a startup package, the default startup package is used. You can download and look at the default startup package: Download default_startupPackage.zip

The following application names are configured in the default startup package:

  • live
  • vod
  • vods3

If you load your own startup package when launching an instance, the default startup package won't be used. Your startup package must provide all of the application configurations that are required for streaming.

Load a startup package

When you launch a new instance in AWS Management Console, you can load a Wowza Streaming Engine startup package to launch the instance with a customized Wowza Streaming Engine configuration. Wowza provides pre-built startup packages that you can download from the Wowza Startup Packages webpage. You can download a startup package and load it "as-is" or you can modify it to meet your requirements before you load it.

There are two methods to load a startup package from the Management Console: As text (key-value pair that references the full startup package URL) or As file (include the startup package contents as User data). When using the As file method, the startup package must be no more than 16 kilobytes (KB ).

Load a startup package as text

To load a startup package As text, do the following:
  1. On the Configure Instance page in the Management Console, click Advanced Details to reveal the advanced options.
  2. In User data, select the As text option, and then enter the WZA_startupPackageURL key-value pair data for your startup package (.zip) file into the text box. Optionally, append the WZA_wowzaServerLicenseKey key-value pair data that specifies the license key(s) for the Wowza Streaming Engine software to form a comma-separated list of key-value pairs. For example: 
    WZA_startupPackageURL=[startup-package-url],WZA_wowzaServerLicenseKey=[pipe-separated-list-of-license-keys]

Load a startup package as a file

To load a startup package As file, do the following:

  1. On the Configure Instance page in the Management Console, click Advanced Details to reveal the advanced options.
  2. In User data, select the As file option.
  3. Click Browse, and then find and upload the startup package (.zip) file in the File Upload dialog box.
Notes:
  • Make sure that the Input is already base64 encoded check box is cleared.
  • The ability to add startup package user data using the As file option in the Management Console is limited to Mozilla Firefox and Google Chrome web browsers.

Debug a startup package

The best way to debug a startup package is to launch an AMI that's using it and then look in the startup log file for errors or warnings. The location of the startup log file is /usr/local/WowzaStreamingEngine/logs/wowzastreamingengine_startup.log.

The log is extensive and should have ample information to help debug startup package issues.

Overview of startup packages

The following example shows the file structure of a simple startup package:

[mywowzaconfig]
    startup.xml
    [wowza]
        [applications]
            [myapp]
        [conf]
            Server.license
            [myapp]
                Application.xml
    [tuning]
        tune.sh

To see how a startup package is constructed, download and extract the contents of the Wowza Streaming Engine default startup package: Download default_startupPackage.zip.

Basic components of a startup package

There are three commands that can appear in a startup manifest file (startup.xml).

<Install> 

The <Install> command copies the contents of a folder that's contained in the startup package to the Wowza Streaming Engine software installation folder /usr/local/WowzaStreamingEngine.

<Install>
    <Folder>[relative-directory-path]</Folder>
</Install>

<Install>/<Folder>

The <Folder> element specifies a folder in the startup package that's copied to the Wowza Streaming Engine installation folder. The folder's directory structure should be the same as the Wowza Streaming Engine installation folder. The specified directory path is relative to the startup package root.

For example, if you have a startup package with the following structure:

[startup-package]
    startup.xml
    [wowza]
        [applications]
            [myapp]
        [conf]
            Server.license
            [myapp]
                Application.xml
    [tuning]
        tune.sh

And the startup.xml file content is:

<Startup>
    <Commands>
        <Install>
            <Folder>wowza</Folder>
        </Install>
        <RunScript>
            <Script>tuning/tune.sh</Script>
        </RunScript>
    </Commands>
</Startup>

The contents of the wowza folder are copied to the /usr/local/WowzaStreamingEngine folder of the running Wowza Streaming Engine instance. In this example, the result is that the application myapp is created and it uses the wowza/conf/myapp/Application.xml configuration file.

<Download>

The <Download> command downloads content from a web server and saves it to the local instance. The <Download> command includes the following elements:

<Download>
    <URL>[URL]</URL>
    <Data>[data]</Data>
    <Header><Name>[key-name]</Name><Value>[value]</Value></Header>
    <Header><Name>[key-name]</Name><Value>[value]</Value></Header>
    <Destination>[relative-or-absolute-file-path]</Destination>
    <Action>[UNZIP, INSTALL]</Action>
</Download>

Note that the only required elements are <URL> and <Destination>.

The following example demonstrates how to download http://www.mycompany.com/myfile.zip, save it to the local computer at the location /opt/myfile.zip, and then unzip the downloaded file. When completed, the extracted contents are located at /opt/myfile.zip.

For another example, let's use two .jar files (wms-plugin-modulea.jar and wms-plugin-moduleb.jar), two applications (live and vod), and the BYOL licensing option. First, create the following directory structure:

[wowzamodules]
    [applications]
        [live]
        [vod]
    [conf]
        Server.license
        [live]
            Application.xml
        [vod]
            Application.xml
    [lib]
        wms-plugin-modulea.jar
        wms-plugin-moduleb.jar

Then, place the [wowzamodules] folder into a compressed (zipped) folder named wowzamodules.zip and copy it to your company's web server. If this file was available at http://www.mycompany.com/modules/wowzamodules.zip, the <Download> command to install this package into the Wowza Streaming Engine lib folder would be:

<Download>
    <URL>http://www.mycompany.com/modules/wowzamodules.zip</URL>
    <Destination>/lib/wowzamodules.zip</Destination>
    <Action>INSTALL</Action>
</Download>

<Download>/<URL>

The <URL> element is the URL of the file to be downloaded. The download can be performed over Secure Sockets Layer (SSL) by using the URL prefix https:// instead of http://. The URL can also contain query parameters. The file is downloaded using the GET method, unless <Data> is specified.

<Download>/<Data>

The <Data> element is text data that's included as part of the HTTP request body. You can use POST data to send user name and password information to your web server so that you can protect your content.

<Download>/<Header>: <Name> and <Value>

The <Header> elements are name-value pairs that are added to the header part of the HTTP request. For example:

<Header>
    <Name>Content-type</Name>
    <Value>text/plain</Value>
</Header>

You can use <Header> data to protect your content. For example, you can use the header values to specify a user name and password using BASIC authentication:

<Header>
    <Name>Authorization</Name>
    <Value>Basic dXNlcm5hbWU6cGFzc3dvcmQ=</Value>
</Header>

<Download>/<Destination>

The <Destination> element is the path to the location where the file is saved (including the filename). This path can be relative or absolute. When calculating a relative file path, the base directory is the root directory of the startup package (the folder that contains the startup.xml file).

<Download>/<Action>

The <Action> element defines the action performed after the file is downloaded. The action can be either UNZIP or INSTALL. If the action is UNZIP, the downloaded file is unzipped using the UNZIP command. If the action is INSTALL, the downloaded file is unzipped and the folder contents are copied to the Wowza Streaming Engine installation folder /usr/local/WowzaStreamingEngine.

<RunScript>

The <RunScript> command executes a script on a running instance. For example:

<RunScript>
    <Script>[relative-or-absolute-file-path]</Script>
    <Param>[parameter]</Param>
    <Param>[parameter]</Param>
</RunScript>

<RunScript>/<Script>

The <Script> element is the path to the script file to be executed. This path can be relative or absolute. When calculating a relative file path, the base directory is the root directory of the startup package (the folder that contains the startup.xml file).

<RunScript>/<Param>

The <Param> elements are parameters that are passed to the running script. For example, the following <RunScript> command:

<RunScript>
    <Script>scripts/copyfile.sh</Script>
    <Param>filea.txt</Param>
    <Param>fileb.txt</Param>
</RunScript>

Is equivalent to executing the following command:

./scripts/copyfile.sh filea.txt fileb.txt

Before a script is executed, the startup processor initializes the following environment variables with information that describes the current instance:

AWSEC2_METADATA_INSTANCE_ID		- Amazon instance id
AWSEC2_METADATA_SECURITY_GROUPS		- Security group
AWSEC2_METADATA_LOCAL_IPV4		- Local IP address
AWSEC2_METADATA_AMI_LAUNCH_INDEX	- Launch index
AWSEC2_METADATA_PUBLIC_HOSTNAME		- Public host name
AWSEC2_METADATA_PRODUCT_CODES		- Embedded license product code
AWSEC2_METADATA_INSTANCE_TYPE		- Instance type (ex. t2-small)
AWSEC2_METADATA_HOSTNAME		- Public host name
AWSEC2_METADATA_LOCAL_HOSTNAME		- Local host name
AWSEC2_METADATA_PUBLIC_IPV4		- Public IP address
AWSEC2_METADATA_AMI_MANIFEST_PATH	- S3 manifest path
AWSEC2_METADATA_RESERVATION_ID		- Instance reservation ID
AWSEC2_METADATA_AMI_ID			- AMI ID
AWSEC2_METADATA_AVAILABILITY_ZONE	- Availability zone
AWSEC2_METADATA_PUBLIC_KEYS		- Public keys
AWSEC2_METADATA_ANCESTOR_AMI_IDS	- Ancestor AMI IDs
AWSEC2_METADATA_RAMDISK_ID		- RAM disk ID
AWSEC2_METADATA_BLOCK_DEVICE_MAPPING	- Block device mapping
AWSEC2_METADATA_KERNEL_ID		- Kernel ID
Was this article helpful?
Thank you for your feedback!
User Icon

&lt;p align=&quot;left&quot;&gt;Thank you for providing feedback to help us improve our documentati

© 2007–2024 Wowza Media Systems™, LLC. All rights reserved.   Security & Privacy PolicyLegalSystem Status