Platform:Drupal/Tracing Drupal Storage

2026-09-20T18:21:46Z

Mngr: Created page with "= Tracing Drupal Storage — From File to Physical Disk = == Purpose == This document explains how to trace a Drupal file through the different storage layers of the Costa Sano infrastructure: <code>Drupal file ↓ Linux filesystem ↓ Linux block device ↓ Hyper-V virtual disk ↓ VHDX file ↓ Windows storage volume ↓ physical disk</code> The important concept is that '''each layer hides the implementation details of the layer b..."

= Tracing Drupal Storage — From File to Physical Disk =

== Purpose ==
This document explains how to trace a Drupal file through the different storage layers of the Costa Sano infrastructure:
<code>Drupal file
↓
Linux filesystem
↓
Linux block device
↓
Hyper-V virtual disk
↓
VHDX file
↓
Windows storage volume
↓
physical disk</code>
The important concept is that '''each layer hides the implementation details of the layer below it'''.

Drupal does not need to know which physical disk contains a file.
----

= 1. The logical view seen by Drupal =
Drupal works with a normal filesystem path such as:
<code>/var/www/drupal/web/sites/default/files/example.pdf</code>
Drupal does not refer to:
<code>/dev/sda</code>
and does not know that the storage is a Hyper-V VHDX.

The Drupal application simply asks the operating system to read or write a file at the given path.
----

= 2. Linux filesystem layer =
In the current Costa Sano configuration, the Drupal media directory is mounted on a separate XFS filesystem.

The relationship is:
<code>/var/www/drupal/web/sites/default/files
↓
XFS filesystem
↓
UUID=06d91c93-c2cb-4185-884b-13b02e47f5ac</code>
The filesystem UUID is the stable Linux identity of the filesystem.

The device name <code>/dev/sda</code> should '''not''' be treated as the permanent identity.

Linux device names can change.

The UUID is what is used in <code>/etc/fstab</code>.
----

= 3. <code>stat</code> — examine the file =
For an individual Drupal file:
<code>stat /var/www/drupal/web/sites/default/files/example.pdf</code>
<code>stat</code> reports information about the file itself, including:

* size;
* owner;
* group;
* permissions;
* timestamps;
* inode information.

<code>stat</code> is therefore the starting point when investigating a particular file.

It does not normally tell us directly which physical device hosts the file.
----

= 4. <code>df</code> — identify the filesystem hosting the file =
To determine which filesystem contains a particular file:
<code>df -h /var/www/drupal/web/sites/default/files/example.pdf</code>
Typical result:
<code>Filesystem Size Used Avail Use% Mounted on
/dev/sda 254G ... ... ... /var/www/drupal/web/sites/default/files</code>
This tells us:
<code>example.pdf
↓
filesystem mounted at
/var/www/drupal/web/sites/default/files
↓
/dev/sda</code>
<code>df</code> therefore answers:<blockquote>'''Which filesystem provides the storage for this path?'''</blockquote>The same command can be used on the directory itself:
<code>df -h /var/www/drupal/web/sites/default/files</code>
----

= 5. <code>findmnt</code> — show the mount relationship =
Use:
<code>findmnt -T /var/www/drupal/web/sites/default/files/example.pdf</code>
or:
<code>findmnt /var/www/drupal/web/sites/default/files</code>
Typical result:
<code>TARGET SOURCE FSTYPE
/var/www/drupal/web/sites/default/files
/dev/sda xfs</code>
This makes the relationship explicit:
<code>/dev/sda
↓
XFS filesystem
↓
/var/www/drupal/web/sites/default/files</code>
The <code>-T</code> option is particularly useful because it asks:<blockquote>Which mounted filesystem contains this path?</blockquote>
----

= 6. <code>lsblk</code> — inspect Linux block devices =
Use:
<code>lsblk -f</code>
This shows Linux block devices, filesystems, UUIDs and mount points.

The media disk appears approximately as:
<code>NAME FSTYPE UUID MOUNTPOINTS
sda xfs 06d91c93-c2cb-4185-884b-13b02e47f5ac /var/www/drupal/web/sites/default/files
sdb
├─...</code>
This connects:
<code>/dev/sda
↓
XFS
↓
UUID
↓
Drupal files mount point</code>
<code>lsblk</code> is therefore primarily a '''block-device view''', whereas <code>findmnt</code> is primarily a '''mount relationship view'''.
----

= 7. <code>blkid</code> — identify the filesystem by UUID =
Use:
<code>sudo blkid /dev/sda</code>
For the Costa Sano media disk the result is:
<code>/dev/sda: UUID="06d91c93-c2cb-4185-884b-13b02e47f5ac" BLOCK_SIZE="4096" TYPE="xfs"</code>
The UUID is important because <code>/etc/fstab</code> uses it to identify the filesystem.

The permanent configuration is:
<code>UUID=06d91c93-c2cb-4185-884b-13b02e47f5ac /var/www/drupal/web/sites/default/files xfs defaults 0 0</code>
Therefore Linux does not depend on the disk being called <code>/dev/sda</code> after a reboot.
----

= 8. Complete Linux-side investigation =
For one particular Drupal file, the following sequence gives the complete Linux-side picture.

=== Step 1 — file ===
<code>stat /var/www/drupal/web/sites/default/files/example.pdf</code>

=== Step 2 — filesystem ===
<code>df -h /var/www/drupal/web/sites/default/files/example.pdf</code>

=== Step 3 — mount relationship ===
<code>findmnt -T /var/www/drupal/web/sites/default/files/example.pdf</code>

=== Step 4 — block devices ===
<code>lsblk -f</code>

=== Step 5 — filesystem identity ===
<code>sudo blkid /dev/sda</code>
The result is conceptually:
<code>Drupal file
↓
/var/www/drupal/web/sites/default/files/example.pdf
↓
/dev/sda
↓
XFS
↓
UUID=06d91c93-c2cb-4185-884b-13b02e47f5ac</code>
----

= 9. Crossing the virtualization boundary =
Up to this point we are inside the AlmaLinux VM.

The Linux operating system knows:
<code>/dev/sda</code>
but Linux does not know that this virtual disk is physically represented by a VHDX file on the Windows Server.

That information belongs to Hyper-V.

The next layer is therefore:
<code>Linux /dev/sda
↓
Hyper-V virtual disk
↓
VHDX</code>
----

= 10. Hyper-V disk configuration =
On the Windows Server Hyper-V host, the Drupal VM has:
<code>IDE Controller 0
├── Device 0 → original 127 GB VHDX
└── Device 1 → new 254 GB VHDX</code>
The new media disk is the second virtual disk attached to the controller.

An important lesson from the migration is:<blockquote>Hyper-V's disk numbering and Linux's <code>/dev/sdX</code> naming are different naming systems.</blockquote>Therefore:
<code>Hyper-V Device 1</code>
does not imply:
<code>/dev/sdb</code>
Linux assigned <code>/dev/sda</code> to the new 254 GB disk in this case.

Disk identification should therefore be based on reliable properties such as:

* size;
* partitions;
* filesystem;
* UUID;
* mount point.

----

= 11. PowerShell — identify the VHDX attached to the VM =
On the Windows Server Hyper-V host, PowerShell can show the virtual disks attached to the VM:
<code>Get-VMHardDiskDrive -VMName "YOUR-DRUPAL-VM"</code>
This shows information including:

* VM name;
* controller type;
* controller number;
* device location;
* VHDX path.

Conceptually the result is:
<code>VMName ControllerType ControllerLocation Path
Drupal IDE 0 D:\...\Drupal-System.vhdx
Drupal IDE 1 D:\...\Drupal-Media.vhdx</code>
The exact path depends on the Hyper-V configuration.

This establishes the relationship:
<code>Linux /dev/sda
↓
Hyper-V IDE 0 / Device 1
↓
Drupal-Media.vhdx</code>
----

= 12. <code>Get-VHD</code> — inspect the VHDX =
PowerShell can inspect the virtual disk itself:
<code>Get-VHD -Path "D:\...\Drupal-Media.vhdx"</code>
This can show information such as:

* VHDX path;
* virtual disk format;
* disk type;
* virtual size;
* physical file size;
* block size.

The important point is that Hyper-V now gives us the identity of the virtual storage object that Linux sees as its virtual disk.
----

= 13. Identify the Windows volume containing the VHDX =
Suppose the VHDX is located at:
<code>D:\Hyper-V\Virtual Hard Disks\Drupal-Media.vhdx</code>
The VHDX is therefore stored on the Windows <code>D:</code> volume.

PowerShell:
<code>Get-Volume -DriveLetter D</code>
This identifies the Windows volume.

Conceptually:
<code>Drupal-Media.vhdx
↓
D:
↓
Windows NTFS volume</code>
----

= 14. Identify the physical disk behind the Windows volume =
To identify the partition containing <code>D:</code>:
<code>Get-Partition -DriveLetter D</code>
This provides the Windows disk number.

For example:
<code>DiskNumber : 2
PartitionNumber : 1
DriveLetter : D</code>
Then inspect that disk:
<code>Get-Disk -Number 2</code>
This gives information about the physical disk, including:

* disk number;
* model;
* size;
* bus type;
* operational status;
* health.

The physical storage devices can also be listed with:
<code>Get-PhysicalDisk</code>
----

= 15. Complete storage chain =
The complete Costa Sano media storage chain is therefore:
<code>┌─────────────────────────────────────────────┐
│ Drupal │
│ │
│ /sites/default/files/example.pdf │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ AlmaLinux 10.2 │
│ │
│ XFS filesystem │
│ UUID=06d91c93-c2cb-4185-884b-13b02e47f5ac │
│ │
│ /dev/sda │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Hyper-V │
│ │
│ IDE Controller 0 / Device 1 │
│ │
│ 254 GB Drupal-Media.vhdx │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Windows Server 2019 │
│ │
│ D:\Hyper-V\...\Drupal-Media.vhdx │
│ │
│ NTFS volume │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Physical storage │
│ │
│ SSD / HDD / storage device │
└─────────────────────────────────────────────┘</code>
----

= 16. The abstraction principle =
The important architectural lesson is that '''each layer provides a stable logical interface to the layer above it'''.

Drupal sees:
<code>/var/www/drupal/web/sites/default/files</code>
Linux sees:
<code>XFS filesystem
UUID=06d91c93...</code>
Linux's block layer sees:
<code>/dev/sda</code>
Hyper-V sees:
<code>254 GB VHDX</code>
Windows sees:
<code>D:\...\Drupal-Media.vhdx</code>
The physical storage subsystem sees:
<code>physical disk</code>
Drupal does not need to know any of the details below its filesystem path.
----

= 17. Why the migration worked without changing Drupal =
Before the migration:
<code>Drupal
↓
/var/www/drupal/web/sites/default/files
↓
original filesystem</code>
After the migration:
<code>Drupal
↓
/var/www/drupal/web/sites/default/files
↓
new XFS filesystem
↓
254 GB VHDX</code>
The Drupal path remained unchanged.

Therefore no Drupal configuration needed to be changed.

Only the filesystem underneath the path changed.

This is the reason a separate media VHDX can be introduced without making Drupal aware of the storage implementation.
----

= 18. Linux versus Windows storage abstraction =
Windows commonly exposes storage to users through drive letters:
<code>C:\
D:\
E:\</code>
Linux instead presents a unified filesystem namespace:
<code>/
├── boot
├── home
├── var
│ └── www
│ └── drupal
│ └── web
│ └── sites
│ └── default
│ ├── files
│ └── files.old</code>
Different filesystems can be mounted at different points in this single hierarchy.

Therefore these two directories can appear next to each other:
<code>files/
files.old/</code>
while actually residing on different filesystems.

In the current Costa Sano migration:
<code>files/
↓
254 GB VHDX

files.old/
↓
original Drupal/system filesystem</code>
The user sees one directory tree.

Linux manages the storage boundaries underneath it.
----

= 19. Practical investigation recipe =
When asking:<blockquote>'''"Where is this Drupal file actually stored?"'''</blockquote>start with the file:
<code>stat /path/to/file</code>
Then:
<code>df -h /path/to/file</code>
Then:
<code>findmnt -T /path/to/file</code>
Then:
<code>lsblk -f</code>
Then identify the filesystem UUID:
<code>sudo blkid /dev/sda</code>
On the Hyper-V host, continue with:
<code>Get-VMHardDiskDrive -VMName "YOUR-DRUPAL-VM"</code>
then:
<code>Get-VHD -Path "path-to-the-vhdx"</code>
then identify the Windows volume:
<code>Get-Volume -DriveLetter D</code>
then the physical disk:
<code>Get-Partition -DriveLetter D
Get-Disk -Number <disk-number></code>
This allows the complete path to be traced from:
<code>Drupal file
↓
Linux filesystem
↓
Linux block device
↓
Hyper-V virtual disk
↓
VHDX file
↓
Windows volume
↓
physical disk</code>
----

= 20. Mental model =
A useful way to remember the whole mechanism is:<blockquote>'''The application sees a pathname.'''

'''Linux maps the pathname to a filesystem.'''

'''The filesystem is identified by a UUID.'''

'''Linux connects that filesystem to a block device.'''

'''Hyper-V presents that block device as a virtual disk.'''

'''The virtual disk is implemented by a VHDX.'''

'''Windows stores that VHDX on physical storage.'''</blockquote>Each layer can change internally while preserving the interface presented to the layer above.

That abstraction is what allowed the Costa Sano media storage to move from the original Drupal filesystem to a separate 254 GB VHDX '''without changing Drupal's file paths or configuration'''.

Costa Sano KB - User contributions [en]

Platform:Drupal/Tracing Drupal Storage