RT 5.0.7 Documentation

RT::ExternalStorage::AmazonS3

NAME
SYNOPSIS
DESCRIPTION
SETUP
CONFIGURATION
- Direct Linking
TROUBLESHOOTING
- Issues Connecting to the Amazon Bucket

NAME

RT::ExternalStorage::AmazonS3 - Store files in Amazon's S3 cloud

SYNOPSIS

    Set(%ExternalStorage,
        Type            => 'AmazonS3',
        AccessKeyId     => '...',
        SecretAccessKey => '...',
        Bucket          => '...',
    );

DESCRIPTION

This storage option places attachments in the S3 cloud file storage service. The files are de-duplicated when they are saved; as such, if the same file appears in multiple transactions, only one copy will be stored in S3.

Files in S3 must not be modified or removed; doing so may cause internal inconsistency. It is also important to ensure that the S3 account used maintains sufficient funds for your RT's storage and bandwidth needs.

SETUP

In order to use this storage type, you must grant RT access to your S3 account.

Log into Amazon S3, https://aws.amazon.com/s3/, as the account you wish to store files under.
Navigate to "Security Credentials" under your account name in the menu bar.
Open the "Access Keys" pane.
Click "Create New Access Key".

Copy the provided values for Access Key ID and Secret Access Key into your RT_SiteConfig.pm file:

    Set(%ExternalStorage,
        Type            => 'AmazonS3',
        AccessKeyId     => '...', # Put Access Key ID between quotes
        SecretAccessKey => '...', # Put Secret Access Key between quotes
        Bucket          => '...',
    );

Set up a Bucket for RT to use. You can either create and configure it in the S3 web interface, or let RT create one itself. Either way, tell RT what bucket name to use in your RT_SiteConfig.pm file:

    Set(%ExternalStorage,
        Type            => 'AmazonS3',
        AccessKeyId     => '...',
        SecretAccessKey => '...',
        Bucket          => '...', # Put bucket name between quotes
    );

CONFIGURATION

The following additional configuration options have defaults, but can be set to custom values.

Host

The S3 host endpoint to connect to.

The default from Amazon::S3 is s3.amazonaws.com.

Region

The AWS region where the S3 bucket is located.

The default from Amazon::S3 is us-east-1.

Direct Linking

This storage engine supports direct linking. This means that RT can link directly to S3 when listing attachments, showing image previews, etc. This relieves some bandwidth pressure from RT because ordinarily it would have to download each attachment from S3 to be able to serve it.

To enable direct linking you must first make all content in your bucket publicly viewable.

Beware that this could have serious implications for billing and privacy. RT cannot enforce its access controls for content on S3. This is tempered somewhat by the fact that users must be able to guess the SHA-256 digest of the file to be able to access it. But there is nothing stopping someone from tweeting a URL to a file hosted on your S3. These concerns do not arise when using an RT-mediated link to S3, since RT uses an access key to upload to and download from S3.

To make all content in an S3 bucket publicly viewable, navigate to the bucket in the S3 web UI. Select the "Properties" tab and inside "Permissions" there is a button to "Add bucket policy". Paste the following content in the provided textbox:

    {
        "Version": "2008-10-17",
        "Statement": [
            {
                "Sid": "AllowPublicRead",
                "Effect": "Allow",
                "Principal": {
                    "AWS": "*"
                },
                "Action": "s3:GetObject",
                "Resource": "arn:aws:s3:::BUCKET/*"
            }
        ]
    }

Replace BUCKET with the bucket name that is used by your RT instance.

Finally, set $ExternalStorageDirectLink to 1 in your RT_SiteConfig.pm file:

    Set($ExternalStorageDirectLink, 1);

TROUBLESHOOTING

Issues Connecting to the Amazon Bucket

Here are some things to check if you receive errors connecting to Amazon S3.

Double check all of the configuration parameters, including the bucket name. Remember to restart Apache after changing values for RT to load new settings.
If you manually created a bucket, make sure it is in your default region. Set the Region option for alternate regions.
Check the permissions on the bucket and make sure they are sufficient for the user RT is connecting as to upload and access files. If you are using the direct link option, you will need to open permissions further for users to access the attachment via the direct link.

← Back to index