Use the AWS SDK for Java to download content from an Amazon S3 bucket for Wowza Streaming Engine Media Cache

Learn how to use the AWS SDK for Java to retrieve content from an Amazon S3 Media Cache source. Media Cache is a caching mechanism included with Wowza Streaming Engine™ media server software that increases the scalability of video-on-demand (VOD) streaming.

Note: The AWS SDK for Java is available in Wowza Streaming Engine 4.8.8.01 and later.

About Amazon S3 Media Cache sources

---

Wowza Streaming Engine provides built-in functionality to retrieve content from the Amazon S3 object storage service. This built-in feature leverages static credentials to authenticate requests. When static credentials are specified, they take precedence over any other authentication methods that are configured.

As an alternative, you can also use the AWS SDK for Java and Amazon S3 authentication to bypass the need to directly provide your AWS access key ID and secret key to Wowza Streaming Engine. With these alternative approaches, you must add the useAWSSDK property to the MediaCache.xml and enable the AWS SDK for Java. For more, see:

• Use a named profile — Used if static credentials aren't set and when a profile name and/or profile credentials path are configured.
• Use default credentials — Used if static credentials or a named profile aren't configured.
• Use an ARN role — Used when an ARN role is defined and in conjunction with the other credentialing methods that include the appropriate configuration values.

Enable the AWS SDK for Java

---

If you're not using static credentials to authenticate your Amazon S3 requests, use these steps to update your MediaCache.xml file and enable the AWS SDK for Java.

1. Navigate to [install-dir]/conf/ and open MediaCache.xml in a text editor.
2. Add the useAWSSDK property to the <MediaCacheSources>/<MediaCacheSource>/<Properties> container element. Be sure to get the correct <MediaCacheSource> container element.
    

   <Property>
     <Name>useAWSSDK</Name>
     <Value>true</Value>
     <Type>Boolean</Type>
   </Property>
   

3. Restart Wowza Streaming Engine to apply the changes.

Configure AWS authentication

---

To retrieve content from a non-public Amazon S3 bucket, you must provide AWS credentials to the SDK. Wowza Streaming Engine supports the credential retrieval methods in this section. For more information, see Supplying and Retrieving AWS Credentials in the AWS SDK for Java version 2.x Developer Guide.

Use static credentials

Wowza Streaming Engine defaults to using static credentials if the access key ID and secret key are specified for the source. This method provides AWS credentials directly to Wowza Streaming Engine.

Credentials can be configured when adding an Amazon S3 source in Wowza Streaming Engine Manager, or by adding them to the <MediaCacheSources>/<MediaCacheSource>/<Properties> container element in MediaCache.xml.

Note: To switch to another credential retrieval method, you must remove these values from the <MediaCacheSources>/<MediaCacheSource>/<Properties> container element in MediaCache.xml.

To configure your access key ID and secret key in MediaCache.xml, add the awsAccessKeyId and awsSecretAccessKey properties to the <MediaCacheSources>/<MediaCacheSource>/<Properties> container element.

<Property>
  <Name>awsAccessKeyId</Name>
  <Value>[access key ID]</Value>
  <Type>String</Type>
</Property>
<Property>
  <Name>awsSecretAccessKey</Name>
  <Value>[secret key]</Value>
  <Type>String</Type>
</Property>

When using an ARN role, the access key ID and secret key must also be added as properties. For more, see Use an ARN role.

Use a named profile

If you're using a named profile, make sure to first enable the AWS SDK for Java. The named profile approach retrieves credentials from a credentials profile created using the AWS CLI. To specify the profile name, add the awsProfileName property to the <MediaCacheSources>/<MediaCacheSource>/<Properties> container element.

<Property>
  <Name>awsProfileName</Name>
  <Value>[profile name]</Value>
  <Type>String</Type>
</Property>

In certain cases, you may also need to specify the path to the credentials file. This is most commonly required on Windows and Linux machines when the .aws/ folder is in a location that doesn't match the User account where the service is running. To specify the path, add the awsProfilesCredentialsFilePath property to the <MediaCacheSources>/<MediaCacheSource>/<Properties> container element.

<Property>
  <Name>awsProfilesCredentialsFilePath</Name>
  <Value>C:\Users\user123\.aws\credentials</Value>
  <Type>String</Type>
</Property>

Use default credentials

If you're using default credentials, make sure to first enable the AWS SDK for Java. Default credentials serve as the default when static credentials or a named profile aren't configured.

This method uses the DefaultCredentialsProvider class from the AWS SDK for authentication to sequentially check and retrieve credentials based on a predefined sequence. For more about retrieval order, see the Default credentials provider chain. The AWS credentials provider chain looks for credentials in this order:

1. Java system properties aws.accessKeyId and aws.secretAccessKey.
2. Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
3. Web identity token credentials from system properties or environment variables.
4. Credential profiles file at the default ~/.aws/credentials location shared by all AWS SDKs and the AWS CLI.
5. Credentials delivered through the Amazon EC2 container service if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access the variable.
6. Instance profile credentials delivered through the Amazon EC2 metadata service.

Use ARN roles

If you're using ARN roles, make sure to first enable the AWS SDK for Java. ARN roles retrieve a set of temporary credentials that include an access key ID, a secret access key, and a security token. To use this method, add the following properties to the <MediaCacheSources>/<MediaCacheSource>/<Properties> container element.

Note: For more information on ARN Roles, see AssumeRole in the AWS documentation.

<Property>
  <Name>awsRoleSessionName</Name>
  <Value>[session name]</Value>
  <Type>String</Type>
</Property>
<Property>
  <Name>awsRoleARN</Name>
  <Value>[resource name]</Value>
  <Type>String</Type>
</Property>
<Property>
  <Name>awsAssumeRoleDuration</Name>
  <Value>3600</Value>
  <Type>String</Type>
</Property>
<Property>
  <Name>awsAccessKeyId</Name>
  <Value>[access key ID]</Value>
  <Type>String</Type>
</Property>
<Property>
  <Name>awsSecretAccessKey</Name>
  <Value>[secret key]</Value>
  <Type>String</Type>
</Property>

Tune the HTTP client

---

You can use the following properties to optimize the HTTP client’s performance. For information about how to set up these Custom properties in Wowza Streaming Engine, see Configure source properties for Wowza Streaming Engine Media Cache.

More resources

---

• Scale with Wowza Streaming Engine Media Cache
• Scale video-on-demand streaming with Wowza Streaming Engine Media Cache