Title: Access-Controlled Files Author: WordPress VIP Documentation Published: August 18, 2021 Last modified: February 26, 2026 --- 1. [Security Controls](https://docs.wpvip.com/security-controls/) 2. Access-Controlled Files # Access-Controlled Files The Access-Controlled Files feature restricts access to a site’s files stored in [the VIP File System](https://docs.wpvip.com/vip-file-system/). Two modes of Access- Controlled Files are supported: * **[Restrict access to unpublished files](https://docs.wpvip.com/security-controls/access-controlled-files?output_format=md#Restrict-access-to-unpublished-files)** * **[Restrict access to all files](https://docs.wpvip.com/security-controls/access-controlled-files?output_format=md#Restrict-access-to-all-files)** **Prerequisites** To enable a mode for Access-Controlled Files with VIP-CLI commands, [VIP-CLI must already be installed](https://docs.wpvip.com/vip-cli/installing-vip-cli/) on the local machine and updated to [the most current version](https://www.npmjs.com/package/@automattic/vip/v/latest). ## Limitations * Only one mode can be enabled on a single WordPress environment at a single time. * The Access-Controlled Files feature has no effect on static files (e.g., CSS, JS) committed to an application’s GitHub repository. * The Access-Controlled Files feature will not work as expected if [IP geolocation](https://docs.wpvip.com/infrastructure/ip-geolocation/) is used to determine which requests should be allowed access. * A VIP Local Development Environment will be unable to [proxy media files](https://docs.wpvip.com/vip-local-development-environment/add-media-content/#h-proxy-media-files) from a WordPress multisite environment that has the Access-Controlled Files feature activated. ## Activate Access-Controlled Files **The Access-Controlled Files feature must be activated for an environment by the VIP Support team**. [Create a request with WPVIP Support](https://wordpressvip.zendesk.com/) and indicate in the request which environment(s) should have the Access-Controlled Files feature activated. By default, activating the Access-Controlled Files feature on a production environment will cause the feature to also be activated on all non-production environments in that application. * Until a mode has been explicitly enabled on the production environment by the customer via code or with VIP-CLI, the **Restrict access to all files** mode will be enabled on all non-production environments by default. * When a mode _is_ enabled on the production environment, that same mode will automatically be enabled on all non-production environments. * The mode enabled on any single environment can be overridden by enabling a different mode via code or VIP-CLI. **Note** **Enabling a mode on a single environment that differs from an application’s other environments is discouraged.** Inconsistent settings between environments can negatively affect the ability to troubleshoot unexpected behavior during development and testing. ## Deactivate Access-Controlled Files Only a member of the VIP Support team can fully deactivate the Access-Controlled Files feature for an environment. [Create a WPVIP Support request](https://wordpressvip.zendesk.com/) and include the name of the environment and its application in the request to deactivate Access- Controlled Files. **Caution** **If Access-Controlled Files is active on a production environment, it is not recommended to deactivate the feature on any of its associated non-production environments.** The VIP File System’s [shared media files feature](https://docs.wpvip.com/vip-file-system/shared-media-files/) automatically provides a non-production environment with access to media associated with the production environment. It is possible for requests for the production media files through the non-production environment to be successful if Access-Controlled Files is disabled on the non-production environment. ## Enable “Restrict access to unpublished files” mode When the **Restrict access to unpublished files** mode is enabled, files attached to draft content can only be downloaded or viewed if the request comes from a logged- in WordPress user who is authorized to view the content the file is attached to. All other requests for those files will be served a `404 Not Found` HTTP status response. **Restrict access to unpublished files** mode is useful if sensitive content is regularly posted and limited access to the media attached to that content is desired. * **This mode will only apply to [files uploaded directly via the post editor](https://wordpress.org/support/article/using-image-and-file-attachments/#attachment-to-a-post).** That creates a parent-child relationship between the post and file, which is then used to determine access and permissions. * This mode will _not_ apply to files uploaded directly to the WordPress Media Library, even if the file is later inserted into the post from the Media Library or a link to the file is copy-pasted directly into the post. * Code * VIP-CLI To code-enable **Restrict access to unpublished files** mode on a WordPress single site—or for all sites on a WordPress multisite—add the code shown in the example below to a file in the [`/client-mu-plugins` directory](https://docs.wpvip.com/wordpress-skeleton/client-mu-plugins-directory/). /client-mu-plugins/example-file.php ```lang-php // Restrict access to unpublished files mode add_filter( 'pre_option_vip_files_acl_restrict_unpublished_enabled', function( $value ) { return 1; } ); ``` To code-enable **Restrict access to unpublished files** mode per-network site on a WordPress multisite, include conditional logic to selectively enable the mode for one or more specific sites using [`get_current_blog_id()`](https://developer.wordpress.org/reference/functions/get_current_blog_id/). **Note** The VIP-CLI examples below include a `@.` placeholder that must be updated with the relevant [application name and environment type](https://docs.wpvip.com/target-environments-for-vip-cli/) values before running the commands. To enable **Restrict access to unpublished files** mode with [VIP-CLI](https://docs.wpvip.com/vip-cli/), the `vip_files_acl_restrict_unpublished_enabled` option must be added and set to a value of `1`. For example: ```wp-block-preformatted vip @. -- wp option add vip_files_acl_restrict_unpublished_enabled 1 ``` Once the `vip_files_acl_restrict_unpublished_enabled` option exists, **Restrict access to unpublished files** mode can be disabled by updating the value to `0` and re-enabled by updating the value to `1`. For example, to disable: ```wp-block-preformatted vip @. -- wp option update vip_files_acl_restrict_unpublished_enabled 0 ``` #### Enable for a network site Selectively enable **Restrict access to unpublished files** mode for a network site on a [WordPress multisite](https://docs.wpvip.com/wordpress-multisite/) by running the command with the `--url=` flag and replacing `` with the site’s URL. ```wp-block-preformatted vip @. -- wp option add vip_files_acl_restrict_unpublished_enabled 1 --url= ``` ## Enable “Restrict access to all files” mode When **Restrict access to all files** mode is enabled, all files in the site can only be downloaded or viewed by logged-in WordPress [users with capability to “read”](https://wordpress.org/support/article/roles-and-capabilities/#read) the published content on the site. All other requests for those files will be served a `404 Not Found` HTTP status response. This mode is useful for intranets and private sites. * Code * VIP-CLI To code-enable **Restrict access to all files** mode on a WordPress single site— or for all sites on a WordPress multisite—add the code shown in the example below to a file in the [`/client-mu-plugins` directory](https://docs.wpvip.com/wordpress-skeleton/client-mu-plugins-directory/). /client-mu-plugins/example-file.php ```lang-php // Restrict access to all files mode add_filter( 'pre_option_vip_files_acl_restrict_all_enabled', function( $value ) { return 1; } ); ``` To code-enable **Restrict access to all files** mode per-network site on a WordPress multisite, include conditional logic to selectively enable the mode for one or more specific sites using [`get_current_blog_id()`](https://developer.wordpress.org/reference/functions/get_current_blog_id/). **Note** The VIP-CLI examples below include a `@.` placeholder that must be updated with the relevant [application name and environment type](https://docs.wpvip.com/target-environments-for-vip-cli/) values before running the commands. To enable **Restrict access to all files** mode with [VIP-CLI](https://docs.wpvip.com/vip-cli/), the `vip_files_acl_restrict_all_enabled` option must be added and set to a value of `1`. For example: ```wp-block-preformatted vip @. -- wp option update vip_files_acl_restrict_all_enabled 1 ``` Once the `vip_files_acl_restrict_all_enabled` option exists, **Restrict access to all files** mode can be disabled by updating the value to `0` and re-enabled by updating the value to `1`. For example, to disable: ```wp-block-preformatted vip @. -- wp option update vip_files_acl_restrict_all_enabled 0 ``` #### Enable for a network site Selectively enable **Restrict access to all files** mode for a network site on a [WordPress multisite](https://docs.wpvip.com/wordpress-multisite/) by running the command with the `--url=` flag and replacing `` with the site’s URL. ```wp-block-preformatted vip @. -- wp option add vip_files_acl_restrict_all_enabled 1 --url= ``` ## Considerations Cached responses for file URLs might already exist on the edge cache prior to the activation of the Access-Controlled Files feature and mode enablement. [Cached content for file URLs must be purged from the edge cache](https://docs.wpvip.com/caching/page-cache/purge-urls/) in order for those requests to receive the expected `404` response. ### Performance Impact Enabling this feature can increase response times for files uploaded to the WordPress Media Library. Serving a file while this feature is active may involve a request to the WordPress application to determine per-user permissions, adding to the overall response time. * For **Access-controlled **files and media, all requests can be around 10-15% slower. * For **public** files and media, the first (uncached) request is expected to be around 10-15% slower. All future requests are cached and should not be impacted. ### Potential conflict for self-referencing files It might be necessary to import a WordPress XML file to an environment that has the same domain as the site from which the XML file was exported. This will result in an import that is “self-referencing”, meaning that it both exports _from_ and imports _into_ the same domain. An import of this kind can happen when adding media library references to a site’s media library following a [media import](https://docs.wpvip.com/vip-file-system/import-media-files/). If Access-Controlled Files is enabled, the [WordPress importer](https://wordpress.org/support/article/importing-content/#wordpress) will be unable to access the media path for a given media asset. The WordPress importer is only able to add media references to a media library if the media path is publicly accessible. To prevent this issue, set `VIP_FILES_ACL_ENABLED` to `false` in `/vip-config/vip- config.php` for the duration of the XML import. The constant can be set back to ` true` after the import has been completed. Last updated: February 26, 2026