Storage and File Systems

Synopsis #

OpenBSD provides a consistent and secure framework for managing disks, partitions, file systems, and advanced storage options such as encryption and software RAID. This chapter describes how to detect new disks, initialize them with an appropriate partitioning scheme (MBR or GPT), define disklabel partitions, create and mount file systems, and ensure proper boot-time configuration with /etc/fstab. It also covers removable media, file system checks, and the use of disk monitoring tools.

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 always represents the entire disk and is required by the system. It must never be formatted, mounted, or manually modified.

Disklabel partitions are created and modified with:

# 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 #

Disks must be initialized with either an MBR or GPT partitioning scheme before disklabel partitions can be defined. OpenBSD uses MBR by default on BIOS-based systems and GPT on UEFI-based systems.

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) :

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

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

# 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:

# fdisk -gy sd1

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

# fdisk -gy -b 1048576 sd1
  # Create the EFI System Partition and an OpenBSD partition
# fdisk sd1
  # Inspect the resulting partition table
# 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:

# 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:

# newfs /dev/rsd1a

The raw character device (rsd1a) must be used.

Mounting the File System #

Create the mount point and attach the file system:

# mkdir -p /mnt/storage
# 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.

# mount
  # Confirm the device and whether it is mounted
# umount /mnt/storage
  # Unmount the non-root target before checking it
# fsck -p /dev/rsd1a
  # Perform safe preen repairs on the raw device

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:

# 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:

# disklabel sd1

Look for a line such as:

  b:  8388608  1953600  swap

Enabling Swap at Runtime #

To activate the swap partition immediately:

# swapctl -a /dev/sd1b

To view active swap devices:

# swapctl -l

Configuring Persistent Swap in /etc/fstab #

To enable swap space automatically at boot, add an entry to /etc/fstab. The mount point field is always set to none, and the file system type should be swap or the preferred synonym sw.

/dev/sd1b none swap sw 0 0

The sw keyword is preferred in OpenBSD but both forms are supported.

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:

# 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
# disklabel sd2

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

# mkdir -p /mnt/usb
# 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:

# 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:

# vnconfig vnd0 install79.iso
# 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:

# umount /mnt/iso
# 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:

# mkdir -p /mnt/memory
# 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:

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

To unmount and detach:

# umount /mnt
# 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. Create the necessary quota files in the file system root:

   # touch /home/quota.user
   # chmod 600 /home/quota.user
   # edquota -u alice
   

3. Enable quotas on the file system:

   # quotaon /home
   

To check current usage:

# quota -u alice
# 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 #

OpenBSD does not include native support for S.M.A.R.T. (Self-Monitoring, Analysis and Reporting Technology) in the base system. However, limited S.M.A.R.T. functionality is available through the smartmontools package, which provides the smartctl(8) utility and the smartd(8) monitoring daemon.

This functionality is useful for monitoring disk health and predicting potential 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:

# pkg_add smartmontools

This provides access to the smartctl and smartd utilities.

Inspecting Disk Health with smartctl #

To query a supported disk:

# 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:

# 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 -M exec /usr/local/libexec/smartmontools/smartd-runner

This monitors /dev/sd0c with all default checks (-a) and sends alerts to the root user by executing the default handler script.

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:

# rcctl enable smartd
# rcctl start smartd

Step 3: Simulate and Test #

To simulate a check or trigger a test manually:

# smartctl -t short /dev/sd0c

Logs will appear in /var/log/daemon. Alerts will be 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. functionality on OpenBSD depends on hardware compatibility and driver support. 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.