First mount and verification

This procedure mounts a newly deployed cluster for the first time. It proves that the whole path works: the client reaches the Master Server, data is written to Chunkservers, and the cluster reports that it is healthy. Run it on one client host, after every server process is up (Starting and stopping) and the client package is installed (Install clients).

Mount the file system

mfsmount needs the Master Server address and a directory to mount on:

mkdir -p /mnt/mfs
mfsmount -H mfsmaster.example.com /mnt/mfs

Without -H, the client connects to the host named mfsmaster. The port defaults to 9421, the Master Server's client port (network ports). -P PORT changes that port. So if a DNS name mfsmaster resolves to the Master Server, the bare mfsmount /mnt/mfs works. The full set of options is listed under mount options and in mfsmount(8).

On FreeBSD, the mount also needs the fusefs kernel module to be loaded. Loading the module is part of installing the client there.

If the mount does not come up, or comes up and then hangs, start from the symptom in Troubleshooting.

A mount's cost per operation and the cap on its throughput are properties of the client machine, not of this procedure. What the FUSE layer costs and The per-mount throughput ceiling cover both.

Confirm the mount is up

df -hT /mnt/mfs

The filesystem column shows the name that the mount registered under. The name is the subtype that the client registers with FUSE, followed by the address and port of the Master Server that the client talks to: mfs#mfsmaster.example.com:9421. The type column reads fuse on Linux and fusefs on FreeBSD. The size columns already show the space of the cluster, not the space of the local disk.

The mount also reports information about itself. .params in the root of the mount, read as root, lists the options in force and the session that the Master Server granted. The file also lists the resolved address that the mount is currently working with. The mfs* tools find the Master Server the same way, through the binary .masterinfo metafile. Because of this metafile, the tools work in any directory of the mount. Both files are special files that mfsmount serves itself.

Write a file and read it back

echo "MooseFS first write" > /mnt/mfs/first-write.txt
cat /mnt/mfs/first-write.txt

When cat returns the line, this proves the full round trip. The Master Server created the file and allocated a chunk. A Chunkserver stored the data. The read returned through the same path.

Trace the file to its chunks

mfsfileinfo asks the Master Server where every copy of every chunk of the file is stored:

mfsfileinfo /mnt/mfs/first-write.txt

/mnt/mfs/first-write.txt:
	chunk 0: 0000000000000801_00000001 / (id:2049 ver:1) ; mtime:1787227200 (2026-08-20 14:00:00)
		copy 1: 192.0.2.11:9422 ; status:VALID
		copy 2: 192.0.2.12:9422 ; status:VALID

A small file has one chunk. Each copy line names the Chunkserver that holds a copy, by address and port, and gives the status of the copy. Every copy of a healthy file is VALID. The copies are stored on different Chunkservers. On a newly deployed cluster, a new file gets the default Storage Class, named 2CP, which keeps two copies. Two copy lines are therefore the expected result. If the number of copies stays below that, or any copy has a status other than VALID, the data path to some Chunkserver does not work.

mfscheckfile summarizes the same information per file. It counts the chunks of the file, grouped by their Redundancy Level:

mfscheckfile /mnt/mfs/first-write.txt

/mnt/mfs/first-write.txt:
2 full copies (redundancy level: 1):          1

The file has one chunk with two full copies, so no data is lost if one Chunkserver is lost. Both tools are documented in mfsdiagtools(1).

Check the cluster as a whole

One file tests one path. As the last step, confirm that everything you deployed registered with the Master Server. In the GUI, at http://mfsmaster.example.com:9425, the Status tab draws the cluster with a health summary. The Chunkservers tab lists every Chunkserver that has connected. The Disks tab lists the disks of each Chunkserver, with the status and last error of each disk. Every Chunkserver and every disk that you deployed has to be on those lists, with no errors reported.

The same data is available in the terminal through mfscli. This tool comes with the CLI package rather than the client one (the package name carries the edition):

mfscli -H mfsmaster.example.com -SIN

-SIN prints the full master info: the cluster summary, the Master Servers, the chunk matrix, the self-check loops, and memory usage. The Metaloggers get a section of their own once one is connected. On a PRO instance, the output also includes the license PRO (PRO Edition only), and the locations once locations are configured. -SCS lists the connected Chunkservers and -SHD their disks. On a healthy newly deployed cluster, the chunk matrix counts no missing chunks. Every Chunkserver that you deployed also appears in -SCS. The switches are documented in mfscli(1).

Make the mount permanent

On Linux, an /etc/fstab entry mounts the file system at boot. The packages install mount.moosefs, which the mount command runs for the moosefs type:

mfsmaster.example.com:9421:/    /mnt/mfs    moosefs    rw,mfsdelayedinit,_netdev    0 0

The first field is HOST[:PORT]:[PATH], where PATH is the MooseFS directory to mount, / for the whole file system. rw (or ro) is required. _netdev delays the mount until the network is up, on systems that use this option. mfsdelayedinit lets mfsmount start without the network and connect in the background. On the BSDs, the same entry also needs mountprog=/usr/local/bin/mfsmount and late among the options. late is required there. FreeBSD ignores _netdev and mounts the rest of /etc/fstab before the network is up. A MooseFS entry that fails at that stage stops the boot and leaves the machine in single user mode. With late, the entry is mounted after the network is up, and mfsdelayedinit keeps the entry from waiting for the Master Server. The forms for both families are in mfsmount(8).

Options shared by every mount on a host can go to mfsmount.cfg instead. That file presets mount options and a default mount point. With these presets, a bare mfsmount with no arguments mounts the right file system from the right Master Server.

When every reading agrees, the cluster is in service

What the run has shown, section by section:

1. The mount: mfsmount returned without an error and the directory is served.
2. The mount reports itself: df -hT names the Master Server and its port after the subtype prefix. The type reads fuse on Linux and fusefs on FreeBSD. The size is the size of the cluster, not of the local disk.
3. The round trip: the line written to the file is read back from it.
4. The chunk: mfsfileinfo prints two copies, both VALID, on two different Chunkservers. mfscheckfile counts the chunk under two full copies.
5. The cluster: every Chunkserver and every disk you deployed is listed, none of them reports an error, and the chunk matrix counts no missing chunks.
6. The mount at boot: if the mount has to survive a reboot, the /etc/fstab entry is in place.

A reading that disagrees is a symptom. Troubleshooting sorts the symptoms by what you observe. When all the readings agree, the cluster is deployed. Monitoring covers what to watch from now on. Operations covers the tasks of running the cluster.