File listing discrepancy for Drupal Private Files

This article only covers Acquia’s Kubernetes version of Acquia Cloud infrastructure, previous referred to as Cloud Next.

Issue

You are not able to access the Private Files by your browser or after ssh into your environment, you do not find the expected files.

For the first situation, you are able to see the files listed in Drupal's Private Files directory, but, when accessing by your browser, the same files shows a "not found error".

In the second situation, you identified a mismatch of files in the directories for managing the privates files. The Acquia Cloud platform is configured with two directories, in the /mnt/data directory, for managing private files. Normally, the directory /mnt/data/[UUID]-real-shared/files-private points as a symlink to /mnt/data/[UUID]-shared/files-private.

The issue would look like the example below where the file, readme.md, is listed in /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared/files-private which does not exist in /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-real-shared/files-private.

customerapp.prod@sshd-5c8554db86-sjz8x:/mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared/files-private$ ls -al
total 12
drwx--S---. 2 customerapp.prod customerapp      6144 Nov 13 06:37 .
drwxr-xr-x. 8 root      cloudadmin 6144 Aug  5 13:12 ..
-rw-r--r--. 1 customerapp.prod customerapp         0 Nov 13 06:37 readme.md
customerapp.prod@sshd-5c8554db86-sjz8x:/mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared/files-private$ cd /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-real-shared/files-private/
customerapp.prod@sshd-5c8554db86-sjz8x/mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-real-shared/files-private$ ls -al
total 8
drwx------.  2 customerapp.prod customerapp 6144 May  4  2022 .
drwxr-xr-x. 12 customerapp.prod customerapp 6144 Feb 15  2024 ..

Resolution

The article, Setting the private file directory on Acquia Cloud, instructs Acquia Cloud users to set up their Drupal Private Files directory location as /mnt/files/[APPLICATION].[ENV]/sites/[SITEDIR]/files-private.

This path is set up, via symlinks, to point to the real path, on the platform, /mnt/data/[UUID]-shared/files-private. This is where any private files for your site need to be located.

• Confirm that your application Private File's directory is configured as described in Setting the private file directory on Acquia Cloud.
  • You can use the command drush -l [SITEDIR] status --field=private
  • The expected output is /mnt/files/[APPLICATION].[ENV]/sites/[SITEDIR]/files-private
• Check the path, /mnt/gfs/[APPLICATION].[ENV]/private-files, points as a symlink to sites/default/files-private.
• Check the path, /mnt/gfs/[APPLICATION].[ENV]/files-private, points as a symlink to ../UUID-shared/files-private.
• Check the path, /mnt/data/UUID-real-shared/files-private, points as a symlink to ../UUID-shared/files-private.
• Check the path, /mnt/data/UUID-shared/files-private, is a directory and is not a symlink.
• If the paths are not set up correctly, create a Support ticket.

Example commands showing a correct configuration:

## Check Drupal Private Files configuration:
customerapp.prod@sshd-5c8554db86-sjz8x:/var/www/html/docroot$ drush -l default st --field=private
/mnt/files/customerapp.prod/sites/default/files-private

## Check the path, /mnt/gfs/ENVIRONMENT_NAME/private-files
## Check the path, /mnt/gfs/ENVIRONMENT_NAME/files-private
customerapp.prod@sshd-5c8554db86-sjz8x:/mnt/gfs/customerapp.prod$ ls -al files-private private-files
lrwxrwxrwx. 1 root root 60 Dec 12  2022 files-private -> ../e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared/files-private
lrwxrwxrwx. 1 root root 27 Dec 12  2022 private-files -> sites/default/files-private

## Check the path, /mnt/data/UUID-shared/files-private
customerapp.prod@sshd-5c8554db86-sjz8x:/mnt/gfs/customerapp.prod$ ls -ld /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared/files-private
drwx--S---. 2 customerapp.prod customerapp 6144 Jun 21 22:01 /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared/files-private

## Check the path, /mnt/data/UUID-real-shared/files-private
customerapp.prod@sshd-5c8554db86-sjz8x:/mnt/gfs/customerapp.prod$ ls -al /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-real-shared/files-private
lrwxrwxrwx. 1 root root 60 Dec 12  2022 /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-real-shared/files-private -> ../e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared/files-private

For further details on the directory structure of your site on the Acquia Platform read the File permissions and symlinks while using Cloud Platform article.

Cause

There can be situations where the environment has not been set up correctly for the private files path.

Generally, what can happen is that the files-private path, in the /mnt/data/[UUID]-real-shared/ does not get assigned to a symlink to /mnt/data/[UUID]-shared/files-private. This path, /mnt/data/[UUID]-shared/files-private, is the correct path on Acquia Cloud that contains the Drupal Private Files. If there is no symlink from the /mnt/data/UUID-real-shared/ directory, then files in this directory will not be served as the Private Files.

The following terms are used to substitute customer values in the provided examples, in this article.

[UUID]

Environments on the platform store files in directories under the /mnt/data directory.

An example directory listing will look similar to:

customerapp.prod@sshd-5c8554db86-sjz8x:/mnt/data$ ls -al
total 28
drwxr-xr-x.  7 root           root      6144 Mar 16  2023 .
drwxr-xr-x.  7 root           root      4096 Nov  5 05:26 ..
drwxr-xr-x. 26 customerapp.prod customerapp 6144 Nov  5 03:04 e384f9cc-7b1c-4783-bf71-1bf9505a52e9-drupal-files
drwxr-xr-x.  7 customerapp.prod customerapp 6144 Nov  5 06:09 e384f9cc-7b1c-4783-bf71-1bf9505a52e9-home
drwxr-xr-x.  4 customerapp.prod customerapp 6144 Apr 16  2024 e384f9cc-7b1c-4783-bf71-1bf9505a52e9-real-shared
drwxr-xr-x. 10 root           root      6144 Jun 21 14:54 e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared
drwxrwxrwt.  2 root           root      6144 Mar 16  2023 tmp

As shown in the example, the names of these directories will always start with a UUID.

For /mnt/data/e384f9cc-7b1c-4783-bf71-1bf9505a52e9-shared, the [UUID] is e384f9cc-7b1c-4783-bf71-1bf9505a52e9. So the general format will be /mnt/data/[UUID]-shared.  

[APPLICATION].[ENV]

The term, [APPLICATION].[ENV], is being used as a substitute for the application environment name.

• [APPLICATION] represents the name of the customer's application, for example, customerapp.
• [ENV] represents the environment name, for example, test.

For example [APPLICATION].[ENV], would be customerapp.test.

[SITEDIR]

Resources

• Cloud Platform Overview
• Setting the private file directory on Acquia Cloud
• File permissions and symlinks while using Cloud Platform
• Contact Acquia Support