Jump to content

Platform:Drupal/Tracing Drupal Storage

From Costa Sano KB

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: 

Drupal file
    ↓
Linux filesystem
    ↓
Linux block device
    ↓
Hyper-V virtual disk
    ↓
VHDX file
    ↓
Windows storage volume
    ↓
physical disk

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: 

/var/www/drupal/web/sites/default/files/example.pdf

Drupal does not refer to: 

/dev/sda

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: 

/var/www/drupal/web/sites/default/files
        ↓
XFS filesystem
        ↓
UUID=06d91c93-c2cb-4185-884b-13b02e47f5ac

The filesystem UUID is the stable Linux identity of the filesystem.

The device name /dev/sda should not be treated as the permanent identity.

Linux device names can change.

The UUID is what is used in /etc/fstab.

3. stat — examine the file

For an individual Drupal file: 

stat /var/www/drupal/web/sites/default/files/example.pdf

stat reports information about the file itself, including:

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

stat is therefore the starting point when investigating a particular file.

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

4. df — identify the filesystem hosting the file

To determine which filesystem contains a particular file: 

df -h /var/www/drupal/web/sites/default/files/example.pdf

Typical result: 

Filesystem      Size  Used Avail Use% Mounted on
/dev/sda        254G  ...  ...   ...  /var/www/drupal/web/sites/default/files

This tells us: 

example.pdf
    ↓
filesystem mounted at
/var/www/drupal/web/sites/default/files
    ↓
/dev/sda

df therefore answers:

Which filesystem provides the storage for this path?

The same command can be used on the directory itself: 

df -h /var/www/drupal/web/sites/default/files

5. findmnt — show the mount relationship

Use: 

findmnt -T /var/www/drupal/web/sites/default/files/example.pdf

or: 

findmnt /var/www/drupal/web/sites/default/files

Typical result: 

TARGET                              SOURCE   FSTYPE
/var/www/drupal/web/sites/default/files
                                    /dev/sda xfs

This makes the relationship explicit: 

/dev/sda
    ↓
XFS filesystem
    ↓
/var/www/drupal/web/sites/default/files

The -T option is particularly useful because it asks:

Which mounted filesystem contains this path?

6. lsblk — inspect Linux block devices

Use: 

lsblk -f

This shows Linux block devices, filesystems, UUIDs and mount points.

The media disk appears approximately as: 

NAME FSTYPE UUID                                 MOUNTPOINTS
sda  xfs    06d91c93-c2cb-4185-884b-13b02e47f5ac /var/www/drupal/web/sites/default/files
sdb
├─...

This connects: 

/dev/sda
    ↓
XFS
    ↓
UUID
    ↓
Drupal files mount point

lsblk is therefore primarily a block-device view, whereas findmnt is primarily a mount relationship view.

7. blkid — identify the filesystem by UUID

Use: 

sudo blkid /dev/sda

For the Costa Sano media disk the result is: 

/dev/sda: UUID="06d91c93-c2cb-4185-884b-13b02e47f5ac" BLOCK_SIZE="4096" TYPE="xfs"

The UUID is important because /etc/fstab uses it to identify the filesystem.

The permanent configuration is: 

UUID=06d91c93-c2cb-4185-884b-13b02e47f5ac /var/www/drupal/web/sites/default/files xfs defaults 0 0

Therefore Linux does not depend on the disk being called /dev/sda 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

stat /var/www/drupal/web/sites/default/files/example.pdf

Step 2 — filesystem

df -h /var/www/drupal/web/sites/default/files/example.pdf

Step 3 — mount relationship

findmnt -T /var/www/drupal/web/sites/default/files/example.pdf

Step 4 — block devices

lsblk -f

Step 5 — filesystem identity

sudo blkid /dev/sda

The result is conceptually: 

Drupal file
    ↓
/var/www/drupal/web/sites/default/files/example.pdf
    ↓
/dev/sda
    ↓
XFS
    ↓
UUID=06d91c93-c2cb-4185-884b-13b02e47f5ac

9. Crossing the virtualization boundary

Up to this point we are inside the AlmaLinux VM.

The Linux operating system knows: 

/dev/sda

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: 

Linux /dev/sda
        ↓
Hyper-V virtual disk
        ↓
VHDX

10. Hyper-V disk configuration

On the Windows Server Hyper-V host, the Drupal VM has: 

IDE Controller 0
├── Device 0 → original 127 GB VHDX
└── Device 1 → new 254 GB VHDX

The new media disk is the second virtual disk attached to the controller.

An important lesson from the migration is:

Hyper-V's disk numbering and Linux's /dev/sdX naming are different naming systems.

Therefore: 

Hyper-V Device 1

does not imply: 

/dev/sdb

Linux assigned /dev/sda 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: 

Get-VMHardDiskDrive -VMName "YOUR-DRUPAL-VM"

This shows information including:

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

Conceptually the result is: 

VMName     ControllerType  ControllerLocation  Path
Drupal     IDE             0                  D:\...\Drupal-System.vhdx
Drupal     IDE             1                  D:\...\Drupal-Media.vhdx

The exact path depends on the Hyper-V configuration.

This establishes the relationship: 

Linux /dev/sda
        ↓
Hyper-V IDE 0 / Device 1
        ↓
Drupal-Media.vhdx

12. Get-VHD — inspect the VHDX

PowerShell can inspect the virtual disk itself: 

Get-VHD -Path "D:\...\Drupal-Media.vhdx"

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: 

D:\Hyper-V\Virtual Hard Disks\Drupal-Media.vhdx

The VHDX is therefore stored on the Windows D: volume.

PowerShell: 

Get-Volume -DriveLetter D

This identifies the Windows volume.

Conceptually: 

Drupal-Media.vhdx
        ↓
D:
        ↓
Windows NTFS volume

14. Identify the physical disk behind the Windows volume

To identify the partition containing D:: 

Get-Partition -DriveLetter D

This provides the Windows disk number.

For example: 

DiskNumber       : 2
PartitionNumber  : 1
DriveLetter      : D

Then inspect that disk: 

Get-Disk -Number 2

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: 

Get-PhysicalDisk

15. Complete storage chain

The complete Costa Sano media storage chain is therefore: 

┌─────────────────────────────────────────────┐
│ 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                  │
└─────────────────────────────────────────────┘

16. The abstraction principle

The important architectural lesson is that each layer provides a stable logical interface to the layer above it.

Drupal sees: 

/var/www/drupal/web/sites/default/files

Linux sees: 

XFS filesystem
UUID=06d91c93...

Linux's block layer sees: 

/dev/sda

Hyper-V sees: 

254 GB VHDX

Windows sees: 

D:\...\Drupal-Media.vhdx

The physical storage subsystem sees: 

physical disk

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: 

Drupal
   ↓
/var/www/drupal/web/sites/default/files
   ↓
original filesystem

After the migration: 

Drupal
   ↓
/var/www/drupal/web/sites/default/files
   ↓
new XFS filesystem
   ↓
254 GB VHDX

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: 

C:\
D:\
E:\

Linux instead presents a unified filesystem namespace: 

/
├── boot
├── home
├── var
│   └── www
│       └── drupal
│           └── web
│               └── sites
│                   └── default
│                       ├── files
│                       └── files.old

Different filesystems can be mounted at different points in this single hierarchy.

Therefore these two directories can appear next to each other: 

files/
files.old/

while actually residing on different filesystems.

In the current Costa Sano migration: 

files/
    ↓
254 GB VHDX

files.old/
    ↓
original Drupal/system filesystem

The user sees one directory tree.

Linux manages the storage boundaries underneath it.

19. Practical investigation recipe

When asking:

"Where is this Drupal file actually stored?"

start with the file: 

stat /path/to/file

Then: 

df -h /path/to/file

Then: 

findmnt -T /path/to/file

Then: 

lsblk -f

Then identify the filesystem UUID: 

sudo blkid /dev/sda

On the Hyper-V host, continue with: 

Get-VMHardDiskDrive -VMName "YOUR-DRUPAL-VM"

then: 

Get-VHD -Path "path-to-the-vhdx"

then identify the Windows volume: 

Get-Volume -DriveLetter D

then the physical disk: 

Get-Partition -DriveLetter D
Get-Disk -Number <disk-number>

This allows the complete path to be traced from: 

Drupal file
    ↓
Linux filesystem
    ↓
Linux block device
    ↓
Hyper-V virtual disk
    ↓
VHDX file
    ↓
Windows volume
    ↓
physical disk

20. Mental model

A useful way to remember the whole mechanism is:

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.

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.

Retrieved from "https://kb.costasano.club/index.php?title=Platform:Drupal/Tracing_Drupal_Storage&oldid=1402"