MUXFS(1) General Commands Manual MUXFS(1)

muxfsthe Multiplexed File System

muxfs format [-a checksum_algorithm] directory ...

muxfs mount [-f] mount_point directory ...

muxfs audit directory ...

muxfs heal directory ...

muxfs sync destination source ...

muxfs version

muxfs is a mirroring, checksumming, and self-healing filesystem layer for OpenBSD. It mirrors a filesystem tree across a series of directories, and employs checksum databases to validate and restore files automatically.

In addition to the file content, metadata is checksummed, including: owner, group, mode, (external) inode number, and for regular files the file size. For directories the checksummed content includes the filenames and corresponding checksums of the files in the directory. For symbolic links the checksummed content is the path output by readlink(2).

During an audit, heal, or sync the muxfs array must not be mounted.

[-a checksum_algorithm] directory ...
Format the directories as part of a new muxfs array. The checksum_algorithm may be crc32, md5, or sha1, and defaults to md5. The directories must be empty and non-overlapping.
[-f] mount_point directory ...
Mount the directories as a redundant array at mount_point. If -f is specified then muxfs remains in the foreground.
directory ...
If the directories are out-of-sync write a warning to the standard error and exit, otherwise for each directory read and check the checksums of all filesystem nodes in the directory, and write to the standard output the paths of the filesystem nodes that do not match.
directory ...
Perform an audit and attempt to restore the filesystem nodes found to be corrupted using the corresponding copies in the other directories.
destination source ...
Restore the directory destination to match the state of the source directories.
Display the program version and exit.

muxfs exits with one of the following exit status values:

incorrect usage

Create a new muxfs array from the filesystems mounted at /mnt/a and /mnt/b using the sha1 checksum algorithm:

# muxfs format -a sha1 /mnt/a /mnt/b

Mount the muxfs array consisting of directories /mnt/a and /mnt/b to the mount-point /mnt/mp:

# muxfs mount /mnt/mp /mnt/a /mnt/b

Unmount the muxfs array:

# umount /mnt/mp

To perform an audit or heal operation the array must not be mounted.

Audit the muxfs array:

# muxfs audit /mnt/a /mnt/b

Heal the muxfs array:

# muxfs heal /mnt/a /mnt/b

Re-sync corrupted /mnt/b to state of /mnt/a after loss of power:

# muxfs sync /mnt/b /mnt/a

Create or update a backup of the array to /mnt/c, the mount-point of a filesystem on a detachable disk:

# muxfs sync /mnt/c /mnt/a /mnt/b

muxfs supports regular files, directories, and symbolic links, and does not support special files, device nodes, file locking, or hard-linking. Timestamps are not included in the checksummed metadata.

Filesystem nodes named .muxfs are reserved for use by muxfs.

muxfs relies on the uniqueness of inode numbers within each directory to perform correctly, therefore the mounting of filesystems within array directories is not supported, with the exception of the .muxfs directories.

To mitigate hard drive head thrashing the top-level .muxfs directories may be moved to solid state storage then mounted back to their original locations.

muxfs relies on writing sequentially to multiple directories to mitigate corruption during unexpected of loss of power. After such an event the administrator must sync the array from one or more of the uncorrupted directories before mounting it. Due to this it is not recommended to use muxfs with only one directory in the array.

For privacy between users syslog(3) messages are sent to the ‘user’ facility. To receive these messages an entry must be set up in syslog.conf(5). Ensure that the corresponding log file is not readable by other. The log messages include notifications of files found to be corrupted and the success or failure of file restoration attempts.

The size of the muxfs database is proportional to the value of the largest (internal) inode number encountered. To minimize this dedicate whole filesystems to the muxfs array.

Stephen D. Adams <>

July 8, 2022 OpenBSD 7.1