Storage and File Systems

Synopsis #

Use OpenBSD’s disk tools to identify disks, set up MBR or GPT layouts, define disklabel partitions, and create filesystems. Configure mounts in /etc/fstab, and use softraid for encryption or software RAID. The procedures below also cover removable media, filesystem checks, and disk-health monitoring.

Disk Device and Partition Naming #

OpenBSD uses a clear and structured device naming convention for storage hardware.

Whole Disks #

Disks are named by driver type and discovery order:

These names are used across tools such as fdisk(8), disklabel(8), and file system utilities.

Partitions #

Each disk is divided into partitions using disklabel(8). OpenBSD allows up to 16 partitions per disk, labeled a through p.

The c partition represents the entire disk. Do not change its extent or create a filesystem over a partitioned disk through it. Whole-device images, such as ISO images, can be mounted through c, as shown below.

Disklabel partitions are created and modified with:

doas disklabel -E sd0

Once partitions are defined, they can be formatted, mounted, encrypted, or used in RAID sets.

Device Nodes #

OpenBSD uses both block and character device files to interact with partitions:

Use the raw device (r prefix) for formatting and file system checks. Use the block device for mounting.

Disk Detection #

New storage devices are automatically recognized by the kernel. To check which disks are detected:

dmesg | grep ^sd

This will list devices such as sd0, sd1, etc. Each detected disk can then be examined and initialized.

Disk Initialization #

Outer partitioning is platform-specific. The following examples target amd64, where MBR is used for legacy BIOS installations and GPT for UEFI installations. Consult the platform’s INSTALL.<arch> instructions before preparing other architectures.

Choosing MBR or GPT #

The partitioning method depends on the boot firmware:

For data-only disks that are not used for booting, either scheme may be used.

MBR with fdisk #

The following examples use an empty secondary disk, sd1. Identify the target disk before proceeding; initialization replaces its partition table.

To initialize an MBR with one OpenBSD partition, use fdisk(8) :

doas fdisk -iy sd1
  # Initialize the MBR and its OpenBSD partition
doas fdisk sd1
  # Inspect the partition table and active flag

To update only the MBR bootcode while preserving the partition entries:

doas fdisk -uy -f /usr/mdec/mbr sd1

The -f option selects the bootcode file; -u updates the MBR bootcode. This command does not install the remaining bootloader stages.

GPT with fdisk #

fdisk(8) also creates GPT partition tables. For an empty data disk containing one OpenBSD partition:

doas fdisk -gy sd1

To reserve a 512 MiB EFI System Partition on a disk with 512-byte sectors, initialize the GPT with -b 1048576:

doas fdisk -gy -b 1048576 sd1
  # Create the EFI System Partition and an OpenBSD partition
doas fdisk sd1
  # Inspect the resulting partition table
doas disklabel sd1
  # Identify the disklabel mapping of the EFI System Partition

The -b value is a count of sectors, not a bootcode filename. Initializing a GPT does not install a bootable system. Use the OpenBSD installer for a complete UEFI installation, including EFI filesystem and bootloader setup.

GPT does not use the MBR active flag. OpenBSD filesystems within the OpenBSD partition are managed with disklabel(8) .

Partitioning with disklabel #

After the outer MBR or GPT scheme is in place, OpenBSD-specific partitions are created inside it using disklabel(8).

For example, a 2 GiB disk with the 512 MiB EFI partition above offers the following space for an OpenBSD filesystem. Press Enter to accept each proposed value:

# disklabel -E sd1
sd1> a a
offset: [1048640]
size: [3145631]
FS type: [4.2BSD]
sd1*> w
sd1> q

Accept the offsets and sizes proposed for the actual disk, or enter the intended layout. The start offset depends on the enclosing MBR or GPT partition; it is not always 64 sectors. The example creates partition a with type 4.2BSD.

To review the resulting label:

doas disklabel sd1

The automatically created c partition will always span the entire disk and must not be changed.

Creating and Mounting File Systems #

Once a partition is defined, it can be formatted with a file system and mounted.

Formatting with newfs #

To initialize the partition with a standard FFS file system:

doas newfs /dev/rsd1a

The raw character device (rsd1a) must be used.

Mounting the File System #

Create the mount point and attach the file system:

doas mkdir -p /mnt/storage
doas mount /dev/sd1a /mnt/storage

To confirm the file system is mounted:

df -h /mnt/storage

Configuring /etc/fstab #

To mount the file system automatically at boot, add a line to /etc/fstab:

/dev/sd1a /mnt/storage ffs rw 1 2

The six fields in each /etc/fstab line are:

Common File System Types #

Mount Options #

Example /etc/fstab entry for a secondary data volume:

/dev/sd1a /mnt/data ffs rw,nodev,nosuid 1 2

File System Consistency Checks #

An unclean file system is normally checked during boot. Before a manual check, identify the target and unmount it. A writable mounted file system must not be repaired concurrently.

doas mount
  # Confirm the device and whether it is mounted
doas umount /mnt/storage &&
    doas fsck -p /dev/rsd1a
  # Check the raw device only after successful unmounting

If fsck(8) reports serious inconsistencies, stop and plan a deliberate manual recovery from the console or recovery media. Do not substitute a generic fsck -y command, which accepts every proposed repair. The root filesystem and other filesystems that cannot be unmounted require an appropriate single-user or recovery environment.

Proper unmounting or clean shutdown helps keep file systems consistent:

doas shutdown -p now

Swap Configuration #

Swap space provides virtual memory by allowing the operating system to page memory contents to disk when physical RAM is insufficient. OpenBSD uses dedicated disklabel partitions for swap, conventionally labeled b.

Creating a Swap Partition #

During installation, a b partition for swap is usually created automatically. If needed, one can be added manually using disklabel(8):

# disklabel -E sd1
sd1> a b
offset: [next available]
size: [e.g., 4G]
FS type: [swap]
sd1*> w
sd1> q

To verify the result:

doas disklabel sd1

Look for a line such as:

  b:  8388608  1953600  swap

Enabling Swap at Runtime #

To activate the swap partition immediately:

doas swapctl -a /dev/sd1b

To view active swap devices:

doas swapctl -l

Configuring Persistent Swap in /etc/fstab #

To enable swap space automatically at boot, add an entry to /etc/fstab. Use none in the mount-point field, swap in the filesystem-type field, and sw in the options field.

/dev/sd1b none swap sw 0 0

swap and sw occupy different fields; they are not interchangeable filesystem types.

Multiple Swap Devices #

If more than one swap partition is defined, OpenBSD will distribute paging across them. Additional swap devices can be added at runtime using repeated swapctl -a calls.

Removing Swap #

To deactivate a swap partition:

doas swapctl -d /dev/sd1b

This command only removes the device from the active swap list. It does not modify the disklabel or delete the data.

Swap space is critical for systems with limited physical memory, for large builds or workloads, or to enable system hibernation (if supported on the platform).

Mounting Removable Media #

Removable media such as USB drives, ISO images, and memory-backed disks can be mounted and used like regular file systems. These devices are typically mounted manually when needed.

USB Storage Devices #

USB mass storage devices (such as flash drives) appear as sdN, just like other disks. When a USB drive is inserted, the kernel assigns it the next available device number (e.g., sd2).

To determine the correct device and partition:

dmesg | grep ^sd
doas disklabel sd2

USB drives are commonly formatted with FAT file systems. To mount a FAT-formatted USB drive:

doas mkdir -p /mnt/usb
doas mount -t msdos /dev/sd2i /mnt/usb

If the correct partition is unknown, examine the output of disklabel sd2. The appropriate partition often has type MSDOS.

To safely remove the drive:

doas umount /mnt/usb

Ensure no shell or background process is accessing the mount point before unmounting. Devices in use will cause umount to fail with “device busy.”

Removable disks should not be listed in /etc/fstab unless configured with the noauto option to prevent mounting during boot.

Mounting ISO Images #

ISO files (such as OpenBSD install images) can be mounted as read-only file systems using a virtual disk configured with vnd(4).

Attach the ISO image to a virtual disk:

doas mkdir -p /mnt/iso
doas vnconfig vnd0 install80.iso
doas mount -t cd9660 /dev/vnd0c /mnt/iso

The file system type cd9660 corresponds to the ISO 9660 standard used for CD-ROM media. The c partition of vnd0 always refers to the full image.

To unmount and detach the image:

doas umount /mnt/iso
doas vnconfig -u vnd0

Creating and Using Memory-Backed File Systems #

Use mount_mfs(8) to create and mount a memory-backed FFS file system directly:

doas mkdir -p /mnt/memory
doas mount_mfs -s 512m swap /mnt/memory

The special device name swap requests anonymous backing rather than a disk device. The contents are temporary and are lost when the file system is unmounted or the system restarts. Memory-file-system pages can consume virtual memory, so select a size that fits the host’s resource limits.

Creating ISO Image Files #

OpenBSD supports the use of image files for archival, transfer, and secure storage. These can be either plain ISO 9660 images or encrypted container files using softraid(4). Image files are typically attached using vnconfig(8) and mounted like normal file systems.

Creating a Plain ISO Image #

To create a standard ISO 9660 image from a directory:

mkhybrid -o archive.iso -R -J /path/to/data

This command generates archive.iso, a read-only ISO image containing the contents of /path/to/data.

To mount the image:

doas vnconfig vnd0 archive.iso
doas mount -t cd9660 /dev/vnd0c /mnt

To unmount and detach:

doas umount /mnt
doas vnconfig -u vnd0

This process can be repeated on any system with the image file and vnd(4) support.

Advanced Features #

OpenBSD includes disk quotas, encrypted softraid volumes, and software RAID. Back Up and Restore an OpenBSD System covers independent backups, tested restores, and /altroot; redundancy and encryption do not provide backup copies.

Disk Quotas #

Quotas allow administrators to restrict disk usage by user or group on a per-file-system basis. Only file systems of type ffs support quotas.

To enable quotas:

1. Modify /etc/fstab to include userquota or groupquota in the options field:

   /dev/sd1a /home ffs rw,userquota 1 2
   

2. With filesystem activity stopped, initialize usage accounting and set limits:

   doas quotacheck -u /home
   doas edquota -u alice
   

3. Enable quotas on the file system:

   doas quotaon /home
   

To check current usage:

doas quota -u alice
doas repquota /home

Quotas are enforced immediately and will remain active after reboot, as long as they are defined in /etc/fstab.

Encrypted Volumes with softraid #

OpenBSD disk encryption uses the CRYPTO discipline of softraid(4) , managed with bioctl(8) . A CRYPTO volume uses one disklabel partition of type RAID and appears as a separate sd(4) disk after it is created or assembled.

CRYPTO provides confidentiality but no redundancy. The passphrase or keydisk is required to unlock the volume, and loss of that recovery material makes the data inaccessible.

Install OpenBSD with Full-Disk Encryption provides the complete clean-install procedure, destructive-device checkpoints, boot verification, keydisk alternative, and recovery requirements. The OpenBSD FAQ should be consulted before creating encrypted external or data-only volumes.

Software RAID with softraid #

The softraid(4) subsystem combines disklabel partitions of type RAID into virtual disks. bioctl(8) manages the volumes.

Current disciplines include striping, mirroring, parity, concatenation, encryption, and encrypted mirroring. Their redundancy, performance, boot support, and recovery properties differ. The virtual sd disk must be partitioned and formatted; filesystems must never be created directly on physical chunks or on a whole-disk c partition.

Configure softraid RAID1 provides the complete two-disk mirror procedure, destructive checkpoints, health monitoring, degraded-state handling, and replacement rebuild. Bootable softraid remains platform-specific and requires the matching softraid(4), installboot(8) , and INSTALL.<arch> documentation.

Monitoring and Health #

Some base-system drivers expose disk-health information through hw.sensors; for example, nvme(4) exports NVMe health sensors. The smartmontools package provides additional diagnostics through smartctl(8) and background monitoring through smartd(8).

Use these tools to monitor disk health and detect signs of failure in supported ATA and SATA drives. Support for NVMe and USB devices is limited and may depend on the controller.

Installing smartmontools #

Install the package using pkg_add:

doas pkg_add smartmontools

This provides access to the smartctl and smartd utilities.

Inspecting Disk Health with smartctl #

To query a supported disk:

doas smartctl -i /dev/sd0c

This command displays device identity and indicates whether S.M.A.R.T. support is enabled. To view all health and error attributes:

doas smartctl -a /dev/sd0c

The device name should correspond to the full disk (typically the c partition). Not all controllers expose S.M.A.R.T. data; some devices may return limited or no results.

Enabling Background Monitoring with smartd #

The smartd daemon periodically checks one or more devices and issues warnings when thresholds are exceeded.

Step 1: Configure /etc/smartd.conf #

Each line defines a device and its options. Example:

/dev/sd0c -a -m root

This monitors /dev/sd0c with all default checks (-a) and sends alerts to the root user through local mail.

To monitor multiple disks, add additional lines.

Step 2: Enable and Start the Daemon #

Enable the service at boot:

smartd_flags=""

Then start the daemon:

doas rcctl enable smartd
doas rcctl start smartd

Step 3: Simulate and Test #

To start an actual short device self-test on supported hardware:

doas smartctl -t short /dev/sd0c

Inspect the result afterward with doas smartctl -l selftest /dev/sd0c. A device self-test does not test alert delivery. Check /var/log/daemon for daemon messages. Alerts are sent via local mail, so ensure that the system’s mail delivery is functioning and that /etc/mail/aliases includes a valid entry for root.

Limitations #

S.M.A.R.T. support on OpenBSD depends on the hardware and driver. USB-attached drives and NVMe devices are often unsupported or only partially functional. Monitoring of such devices may not be reliable.

The smartmontools package is suitable for systems using directly attached SATA disks where predictive failure reporting is desired.