Documentation

Settings

This guide briefly describes each of the settings you can change from within WP Offload Media’s settings page to control Media Library offloading.

For a description of the Assets Pull addon’s settings, please refer to its Settings doc.

WP Offload Media’s settings page can be accessed from the “Settings” => “Offload Media” menu option in a standard WordPress install, and from the same option within the Network Admin area of a multisite network install.

URL Preview

The settings page shows a preview of the URL format that will be used when a Media Library item’s URL is rewritten to use the offloaded version.

This is not a real URL and can not be used to test WP Offload Media. In fact, it is specially encoded for display and should not be copied and pasted as it will not work like a real URL should.

The preview URL updates as each setting is changed.

Storage

This section of the settings page controls where the Media Library is offloaded to, including which storage provider, bucket, and the path that files (objects) will use.

Provider

This displays the name of the chosen cloud storage provider. If you wish to change to another storage provider, there is a “Change” link next to the current provider’s name.

For more details on setting up your storage provider, please take a look at the Quick Start Guide.

There is also important information about changing storage provider in our How to Change Storage Provider doc.

Bucket

Here you can see the currently selected bucket and the region it is in.

If you are using Amazon S3, then the status of the bucket’s Block All Public Access will also be shown as either enabled or disabled.

At present the only storage provider that supports Block All Public Access is Amazon S3, and you must use Amazon CloudFront as the delivery provider if Block All Public Access is enabled.

Next to the bucket’s name is a “Change” link that can be used to enter, browse for, or create a different bucket to offload Media Library items to. If you change the bucket, then WP Offload Media will offer to copy the existing offloads to the newly selected bucket and update metadata in the WordPress database as needed (not available in the Lite version).

Copy Files to Bucket

As soon as a file has completed uploading to the Media Library, it will be copied to your cloud storage bucket as well. This setting does not copy attachments to the bucket that were uploaded to the Media Library before WP Offload Media was installed and configured. You need to use the Offload Tool (not available in the Lite version) to accomplish that.

Copy Files to Bucket is turned on by default, turning it off will stop WP Offload Media from automatically offloading newly uploaded Media Library items, but will not stop already offloaded items from being re-offloaded when edited or optimized by another plugin etc.

Path

Set a path for attachments to be offloaded to in the bucket. This is helpful if you are using the same bucket to store files for different sites. This does not affect the local path of the file on the server.

If you change the path setting, then WP Offload Media will offer to move the existing offloads to the new storage path and ensure its records are kept up-to-date (not available in the Lite version).

Year/Month

Organize the uploads in year and month folders in the bucket. For example, /2016/02/my-file.jpg.

The year and month used for each offload will match the year and month that the Media Library item was added to WordPress.

If you have existing offloads and are turning on the Year/Month setting, then WP Offload Media will offer to move the existing offloads to the new storage path and ensure its records are kept up-to-date (not available in the Lite version).

If you have existing offloads and are turning off the Year/Month setting, then WP Offload Media will show a warning that explains why it will not offer to move existing offloads to the new storage path (not applicable to the Lite version).

Object Versioning

Ensures that files are offloaded to the bucket with a unique path. This is a cache-busting technique especially helpful when using CloudFront and other CDNs to make sure the latest version of a file is served.

If you have existing offloads and are turning on the Object Versioning setting, then WP Offload Media will offer to move the existing offloads to the new storage path and ensure its records are kept up-to-date (not available in the Lite version).

If you have existing offloads and are turning off the Object Versioning setting, then WP Offload Media will show a warning that explains why it will not offer to move existing offloads to the new storage path (not applicable to the Lite version).

Delivery

This section of the settings page controls how the offloaded Media Library items are delivered to site visitors, including which delivery provider, whether a custom domain is to be used, and whether HTTPS should always be used. Depending on the chosen delivery provider, other settings may be available related to generating signed expiring URLs for private media.

Provider

This displays the name of the chosen delivery provider. If you wish to change to another storage provider, there is a “Change” link next to the current provider’s name.

By default the storage provider is used for delivery too, e.g. “Amazon S3”. We strongly recommend using a Content Delivery Network (CDN) instead to not only speed up delivery of media to your site visitors, but also improve SEO.

Rewrite Media URLs

Rewrites local URLs to be served from the configured delivery provider.

When this setting is turned off, the site’s content will return to using local media URLs. If the Remove Files From Server setting has been in use, please ensure your media files have been copied back to the server to avoid broken media links in your content.

Custom Domain (CNAME)

By default, rewritten media URLs use the raw bucket URL format of the storage provider, e.g. https://bucketname.s3.amazonaws.com.... If you have chosen another delivery provider such as CloudFront or another CDN, you can enter the domain supplied by the delivery provider or a subdomain of your domain that is pointing at the delivery provider.

This setting is only available when a delivery provider other than the storage provider has been chosen.

Private Media

If using a Custom Domain (CNAME) has been enabled, and when using Amazon CloudFront as the delivery provider, you can also enable the generation of signed expiring URLs for that domain when a Media Library item is “private”.

For more information on what setting a Media Library item to “private” means and when you might want to do so, please see our How to Restrict Access to Offloaded Media doc.

By default, WP Offload Media is able to create signed expiring URLs for private media in all supported storage providers using their default raw bucket URL format.

Google Cloud Storage will also automatically generate signed expiring URLs that use the Custom Domain (CNAME) when that is set, therefore this setting does not show when using the GCP Cloud CDN delivery provider.

Currently, the only delivery provider that this setting will show for is Amazon CloudFront.

CloudFront Key Pair Access Key ID

If Private Media is enabled, then this required setting will be shown.

In order for WP Offload Media to be able to sign CloudFront URLs it requires the Access Key ID for the CloudFront Key Pair.

CloudFront Private Key File Path

If Private Media is enabled, then this required setting will be shown.

In order for WP Offload Media to be able to sign CloudFront URLs it requires the full absolute file path on the server to the downloaded Private Key File for the CloudFront Key Pair.

Please be careful to place the Private Key File in a secure folder that is not accessible to the public internet. It only needs to be accessible to the PHP process that WordPress is running under. Usually this means just placing the file one folder up from the WordPress root folder if properly secured, but this is not always the case.

For example, if WordPress is installed at (where you’ll normally find wp-config.php etc):

/sites/example.com/files/

Then the following might be an example of where the Private Key File can be placed and what should be entered into the Private Key File Path setting:

/sites/example.com/pk-APKABCDE12345FGHIJKL.pem

The placement and security of this file is very dependent on your server and site setup, please consult your web host or server admin for advice if unsure.

Private Path

If Private Media is enabled, then this required setting will be shown.

In order for WP Offload Media to be able to sign CloudFront URLs it requires a path to prefix each private object’s path with that matches the CloudFront Behavior’s Path Pattern.

When a private Media Library item is offloaded its full path in the bucket will consist of the Private Path set here plus the public storage path determined from the Path, Year/Month and Object Versioning settings, along with the file’s name.

For example, if the current settings are:

Path: media/
Year/Month: On
Object Versioning: On
Private Path: private/

The public storage path in the bucket for a file might be as follows:

media/2020/06/123456/hello.mp3

If that Media Library item was made private, then it would be moved to:

private/media/2020/06/123456/hello.mp3

For Media Library items such as images that are composed of multiple files, all, some, or none of the files could be made private. In such a case, WP Offload Media keeps track of which files are public or private that make up the Media Library item, and ensures they are appropriately prefixed with the Private Path if private, and not if public. It’s therefore entirely possible that an image has two prefixes in the bucket, such as if the full and large sizes are made private but smaller thumbnail sizes are left public…

private/media/2020/06/123456/worksheet.jpg
private/media/2020/06/123456/worksheet-1024x768.jpg
media/2020/06/123456/worksheet-300x300.jpg
media/2020/06/123456/worksheet-150x150.jpg

WP Offload Media takes care of rewriting the local media URLs to the correct CloudFront domain and path, and signing the URLs as appropriate.

If you have existing offloads and are changing the Private Path setting, then WP Offload Media will offer to move the existing private objects to the new private path and ensure its records are kept up-to-date (not available in the Lite version). This includes moving private objects back to the public storage path if Private Media is turned off.

WP Offload Media only requires the directory name, not the wildcard suffix that CloudFront requires. So, if the CloudFront Behavior’s Path Pattern is “private/*”, you would use “private/” as the Private Path.

It is not possible to use a CloudFront Behavior Path Pattern without a folder prefix, and partial file names or suffixes that may be used in the CloudFront Behavior’s Path Pattern must also be omitted from WP Offload Media’s Private Path setting. For example, if “private/secret-*.mp3” is used in the CloudFront Behavior’s Path Pattern, only “private/” should be entered for the Private Prefix.

If a Private Path without a trailing slash is entered, e.g. “private”, WP Offload Media will save it as “private/” for consistency.

It is perfectly fine to use a multi-part Private Path such as “secret/downloads/”.

Force HTTPS

Control the protocol of the cloud storage URLs. The default will be the protocol of the page the attachment is on, but you can set it to always be HTTPS.

Remove Files From Server

Removes the files from the local server once they have been offloaded to cloud storage. This can help reduce used HDD space on the site’s server. There are possible issues around compatibility with other plugins when enabling this setting, as they may rely on access to the local file.

If you have a backup system in place (as you should) that backs up your site files, media, and database, your media will no longer be backed up as it will no longer be present on the filesystem. You will need to back up the media in your bucket by other means. With Amazon S3, it’s as simple as turning on Versioning in your bucket settings.

If you have existing offloads and are turning on the Remove Files From Server setting, then WP Offload Media will offer to remove existing offloads from the server (not available in the Lite version).

If you have existing offloads, regardless of whether you have turned on the Remove Files From Server setting or not, you can use the Download all files from bucket to server tool to ensure there are local files on the server where WordPress originally put them (not available in the Lite version).

Using Constants

All of the above settings can be defined in your wp-config.php file.