Settings
This guide briefly describes each of the settings you can change from within WP Offload Media’s settings page to control Media offloading.
For a description of the Assets Pull 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.
Storage Settings
This section of the settings page controls where the media is offloaded to, including which storage provider, bucket, and the path that files (objects) will use.
Storage Provider
The heading section displays the icon and name of the chosen cloud storage provider. If you wish to change to another storage provider, there is an Edit button 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
Also in the heading section, under the Storage Provider’s name, you can see the currently selected bucket and the region it is in.
The bucket name is an external link to the bucket and configured path prefix in the storage provider’s console.
The Edit button to the right of the Storage Provider’s name can also be used to enter, browse for, or create a different bucket to offload media items to.
If Amazon S3 is being used as the Storage Provider, the Edit button may also be used to change the Block All Public Access and Object Ownership statuses for the chosen bucket.
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).
Offload Media
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.
The Offload Media setting 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.
If at any point the Offload Media setting is turned off, WP Offload Media will offer to offload any media that has yet to be offloaded if you later turn it on again (not available in the Lite version).
Remove Local Media
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 Local Media 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 and are turning off the Remove Local Media setting, then WP Offload Media will offer to download existing offloads from the bucket if they are not found on the server where WordPress originally put them (not available in the Lite version).
At any time, if you have existing offloads, regardless of whether you have turned on the Remove Local Media 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).
Add Prefix to Bucket 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 Add Prefix to Bucket 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).
Add Year & Month to Bucket Path
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 Add Year & Month to Bucket 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).
If you have existing offloads and are turning off the Add Year & Month to Bucket Path 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).
Add Object Version to Bucket Path
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 Add Object Version to Bucket 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).
If you have existing offloads and are turning off the Add Object Version to Bucket Path 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 Settings
This section of the settings page controls how the offloaded media 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.
Delivery Provider
The section header displays the icon and name of the chosen delivery provider. If you wish to change to another delivery provider, there is an Edit button next to the current provider’s name.
Under the name of the delivery provider there is an external link to the provider’s console.
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.
Deliver Offloaded Media
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 Local Media 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.
Use Custom Domain Name (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.
Serve Private Media from CloudFront
If the Use Custom Domain Name (CNAME) setting 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 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 Name (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.
Public Key ID
If Serve Private Media from CloudFront 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 ID for the Public Key uploaded to CloudFront.
Private Key File Path
If Serve Private Media from CloudFront 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 Private Key File for the 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/example_cvxQzy5jkh7heg2NXG_private.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 Bucket Path
If Serve Private Media from CloudFront 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 item is offloaded, its full path in the bucket will consist of the Private Bucket Path set here plus the public storage path determined from the Add Prefix to Bucket Path, Add Year & Month to Bucket Path and Add Object Version to Bucket Path settings, along with the file’s name.
For example, if the current settings are:
Add Prefix to Bucket Path: media/
Add Year & Month to Bucket Path: On
Add Object Version to Bucket Path: On
Private Bucket Path: private/
The public storage path in the bucket for a file might be as follows:
media/2022/09/12345678/hello.mp3
If that Media Library item was made private, then it would be moved to:
private/media/2022/09/12345678/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 Bucket 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/2022/09/12345678/worksheet.jpg
private/media/2022/09/12345678/worksheet-1024x768.jpg
media/2022/09/12345678/worksheet-300x300.jpg
media/2022/09/12345678/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 Bucket 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 Serve Private Media from CloudFront 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 Bucket 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 Bucket Path. For this reason we recommend only using directory path patterns in the CloudFront Behavior, e.g. private/*.
If a Private Bucket 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
Controls 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.
URL Preview
At the bottom of the settings page you will find the URL Preview panel that shows the structure and example data for how offloaded media URLs will look to site visitors.
The preview URL updates as each setting is changed.
Using Constants
All of the above settings can be defined in your wp-config.php file.