azure-ephemeral-disk-setup(8)

💖 NAME 💖

okay so bestie, meet azure-ephemeral-disk-setup — yes it's a whole mouthful, iykyk — and it's the azure-ephemeral-disk-setup(8) page we're doing today 🫶. What it does: detect, validate, format, and mount Azure ephemeral local disks (NVMe or SCSI) with optional RAID aggregation. Periodt. ✨

---

✨ SYNOPSIS ✨

azure-ephemeral-disk-setup

That's it. No flags, no args, she just goes. 💅

---

🌸 DESCRIPTION 🌸

azure-ephemeral-disk-setup is a systemd-managed one-shot initialization service for Microsoft Azure virtual machines, and its whole job is prepping your ephemeral (temporary) disks so they're actually usable. It handles both NVMe and SCSI ephemeral disks, and it can aggregate multiple NVMe devices into a RAID-0 array using mdadm. Like, iconic behavior honestly. 🔥

The service is opt-in, and you configure it through /etc/azure-ephemeral-disk-setup.conf. It runs early in the boot process and is designed to be idempotent, safe, and compatible with existing tools like cloud-init and WALinuxAgent. No drama, no stepping on anyone's toes. 💜

Logs go to stderr, and if you're running the systemd service you can vibe-check them via journalctl:

journalctl -u azure-ephemeral-disk-setup.service

---

🎀 CONFIGURATION 🎀

Config gets loaded from, in order of ~preference~:

• /etc/azure-ephemeral-disk-setup.conf (the preferred one, the main character 👑)
• Environment variables (the fallback, the understudy)

Here's the full roster of supported environment variables, no cap:

• AZURE_EPHEMERAL_DISK_SETUP_AGGREGATION — supported values: mdadm, none, auto.
  • mdadm: require mdadm and use it for aggregation if multiple disks are found, exiting with error if mdadm is not installed (regardless of number of disks)
  • auto: use mdadm for aggregation only if installed, otherwise fall back to use a single disk
  • none: never aggregate disks, only use one
  • Default: auto
• AZURE_EPHEMERAL_DISK_SETUP_FS_TYPE — supported values: ext4, xfs. Default: ext4 (universally available; xfs requires xfsprogs).
• AZURE_EPHEMERAL_DISK_SETUP_MDADM_CHUNK — supported values: any valid mdadm chunk size. Default: 512K (the mdadm default).
• AZURE_EPHEMERAL_DISK_SETUP_MDADM_NAME — supported values: any valid mdadm name. Default: azure-ephemeral-md.
• AZURE_EPHEMERAL_DISK_SETUP_MOUNT_POINT — supported values: any valid mount point path. Default: /mnt (matches the cloud-init default mount point).
• AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE — supported values: true, false. Default: false (minimizes risk of conflict with cloud-init and WALinuxAgent).
• AZURE_EPHEMERAL_DISK_SETUP_SYSTEMD_UNIT_TIMEOUT_SECS — supported values: positive integer (>=1). Default: 60.
• AZURE_EPHEMERAL_DISK_SETUP_UDEVADM_SETTLE_TIMEOUT_SECS — supported values: positive integation (>=1). Default: 60.

---

🌈 OPERATION 🌈

Here's the whole little routine, step by step, bestie:

1. Load and Validate Configuration
   • Configuration is read via filtered source /etc/azure-ephemeral-disk-setup.conf, allowing only safe environment-style assignments.
   • If invalid values are detected, the service exits with error.
   • Required tools (mkfs.${AZURE_EPHEMERAL_DISK_SETUP_FS_TYPE}, mdadm) must be available.
2. Check for Existing Mounts If the mount point is already configured:
   • with a matching /etc/fstab line containing the comment comment=azure-ephemeral-disk-setup, the service will wait for mount to complete.
     • if mount succeeds, service exits with success.
     • if mount does not complete, this service will check if the ephemeral disks have been reallocated and reconfigure them via the standard detection/validation process below.
   • by cloud-init and source is /dev/disk/cloud/azure_resource-part1:
     • if AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=false, the service exits with success, allowing cloud-init to manage the disk.
     • if AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true, the service exits with error as the entry is either stale or conflicting.
   • by other tools/services/configuration, the service exits with error.
3. Detect and Validate Disks NVMe disks are detected via model names:
   • Microsoft NVMe Direct Disk
   • Microsoft NVMe Direct Disk v2

The SCSI resource disk is detected and validated if AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true and no ephemeral NVMe disks are detected.

See the SAFETY AND VALIDATION section for more on how disks get validated to ensure no data is lost. 🛡️

4. Disk Setup Each candidate disk is checked to ensure:
   • It is a block device
   • It is not mounted
   • It is not partitioned (unless NTFS resource disk)
   • It has no existing filesystem (unless NTFS resource disk)

If any disk fails these checks, the service aborts with a detailed error.

5. Aggregation with RAID-0 For VMs With Multiple local NVMe Disks If more than one NVMe disk is found and aggregation is enabled with mdadm:

mdadm --create "/dev/md/${AZURE_EPHEMERAL_DISK_SETUP_MDADM_NAME}_0" \
  --level=0 \
  --raid-devices=N \
  --metadata=1.2 \
  --chunk="$AZURE_EPHEMERAL_DISK_SETUP_MDADM_CHUNK" \
  --name="$AZURE_EPHEMERAL_DISK_SETUP_MDADM_NAME" \
  ${DISKS[@]}

Configuration is not written to /etc/mdadm/mdadm.conf in favor of kernel auto-detection.

6. Format Filesystem
   • Formats the target device (either the RAID device or a single disk) directly without partitioning
   • Uses mkfs.ext4 [-F] -L AzureEphmDsk ... or mkfs.xfs [-f] -L AzureEphmDsk ... with the force flag only if it is reformatting the SCSI resource disk
7. Persistenting Mount If /etc/fstab is writable:
   • Previous entries with comment=azure-ephemeral-disk-setup are removed
   • New entry added:

LABEL=AzureEphmDsk <mount_point> <fs_type> defaults,nofail,comment=azure-ephemeral-disk-setup 0 2

If /etc/fstab is read-only or does not exist, it will not be updated. It will be mounted by this service on every boot.

8. Mounting For persistent mounts:
   • Tries to mount using systemd (systemctl start <mount.unit>)
   • Falls back to a direct mount call if the mount unit fails to start

For non-persitent mounts, a mount call is used.

---

🦋 SAFETY AND VALIDATION 🦋

This service only formats NVMe disks that are:

• Not mounted
• Unpartitioned
• Unformatted

SCSI resource disks are only reformatted if it:

• Has a single NTFS partition labeled Temporary Storage
• Is empty except for dataloss_warning_readme.txt and System Volume Information
  • To check if the disk is empty, this service will attempt to mount the resource disk partition read-only via ntfs3, with fallback to ntfs. If both fail due to lack of driver, it is assumed safe to reformat.

Calls to mkfs and mdadm do not use --force for formatting or mdadm array creation unless reformatting a validated NTFS SCSI disk.

💀 bestie please read this part twice. It's the "we are not nuking your data by accident" section and it's carrying the whole plot.

---

⭐ EXIT STATUS ⭐

• 0 — Success 🎉
• 1 — Any error (invalid config, conflicting mount, unsafe disk, etc.) 😭

---

🍓 FSTAB STRATEGY 🍓

These are the values used when generating an /etc/fstab entry for the ephemeral disk:

• fs_spec: LABEL=AzureEphmDsk — refers to the disk label. This assumes the script has ownership of the AzureEphmDsk label.
• fs_vfstype: $AZURE_EPHEMERAL_DISK_SETUP_FS_TYPE — the filesystem type, determined by configuration (e.g., ext4 or xfs).
• fs_mntops: defaults,nofail,comment=azure-ephemeral-disk-setup
  • defaults: standard mount options
  • nofail: ensures the VM boots even if the ephemeral disk is missing or has been re-allocated
  • comment=azure-ephemeral-disk-setup: tags the entry to show it's managed by this setup
• fs_freq: 0 — disables dump backups for the filesystem.
• fs_passno: 2 — sets the order for fsck during boot. Non-root filesystems typically use 2.

---

🧚 AVOIDING CONFLICTS WITH CLOUD-INIT 🧚

If AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=false, this service will exit with success if cloud-init is managing the SCSI resource disk at the same mount point. Given the widespread usage of cloud-init for managing the SCSI resource disk, this is the default case. 💅

If AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true, cloud-init management of the resource disk must be disabled. There are two options for disabling cloud-init's management of the SCSI resource disk:

Disabling cloud-init management of SCSI resource disk via udev rules

Disable the udev rules responsible for creating the /dev/disk/cloud symlinks:

ln -sf /dev/null /etc/udev/rules.d/66-azure-ephemeral.rules

If cloud-init doesn't detect the device, it will not attempt to format/mount it.

Disabling cloud-init management of SCSI resource disk via cloud-init configuration (cloud-init >= 25.3)

Work is ongoing to introduce a flag to the Azure datasource to control behavior. See pull request (<https://github.com/canonical/cloud-init/pull/6323>).

This is expected to be available in cloud-init 25.3.

---

🙈 AVOIDING CONFLICTS WITH WALINUXAGENT 🙈

WALinuxAgent must be configured with ResourceDisk.Format=n.

If AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true, this service will exit with error if /etc/waagent.conf sets ResourceDisk.Format=y.

---

🔥 EXAMPLES 🔥

Basic usage, the classic:

sudo azure-ephemeral-disk-setup

Enable management of the SCSI resource disk:

# /etc/azure-ephemeral-disk-setup.conf
AZURE_EPHEMERAL_DISK_SETUP_SCSI_RESOURCE=true

---

🌸 FILES 🌸

• /etc/azure-ephemeral-disk-setup.conf — user configuration
• /etc/fstab — mount persistence

---

👑 SERVICE ORDERING 👑

DefaultDependencies=no to avoid typical service dependencies as we want to start early. Early bird energy. 🐦

After:

• cloud-init.service (a.k.a. cloud-init-network.service) — allows users to customize service configuration using cloud-config
• local-fs.target — ensures local filesystems are mounted (necessary if no cloud-init)

Before:

• cloud-init.target — ensures we start before cloud-init completes, which services may use to determine if the system is fully configured
• walinuxagent.service waagent.service — ensures we start prior to walinuxagent and avoid conflicts
• network-online.target — to ensure we start before networking is considered online
• sshd.service — to ensure we start before sshd starts accepting connections
• systemd-user-sessions.service — to ensure we start before user sessions are enabled
• sysinit.target — to ensure we run before most services requiring mounts (Debian/Ubuntu only)

---

💜 DEBUGGING 💜

All logs are written to stderr and accessible with:

journalctl -u azure-ephemeral-disk-setup.service

---

🌈 SEE ALSO 🌈

mdadm(8), mount(8), cloud-init(8), waagent(8)

Project Home: <https://github.com/Azure/azure-vm-utils>

---

okay that's the whole page bestie, literally every last crumb of it 🫶✨ and fr fr, this was azure-ephemeral-disk-setup version 0... from August 08, 2025 — slay, go configure your ephemeral disks, you're gonna do great 💖🎀