package: mlnx-tools

title: ib2ib_setup(8)

text:
# ib2ib_setup(8)

## NAME
ib2ib_setup - Generate files required for preparing the network to work with IB Router

## SYNOPSIS
ib2ib_setup [-dDEVICE][-sSUBNET_NUMBER][-nNETWORK_SUBNET]

ib2ib_setup [-fIPSFILES]ips_file...

## DESCRIPTION
This program invokes ibnetdiscover to scan the network to extract the data about host port names, LIDs and GUIDs, and uses arping to scan the subnet for IPs. It then writes out the information into 3 separate files: ip2gid.db, guid2lid and hosts.

ip2gid.db:

This file holds the IP to GID mapping used by ibacm service running on each machine in the cluster.

guid2lid:

This file holds the mapping of GUID to LID. It should be copied into the SM cache directory. At the moment it is only supported by host based OpenSM or UFM appliance (switch based OpenSM does not support it).

hosts:

This file holds mapping of host name to IP and should be placed in /etc/hosts and pointed by nsswitch.conf (lathernatively use a DNS).

## OPTIONS
-d

"device name". For example: -d ib0. The interface through which the subnet is scanned for IP to GUID mapping using arping.

-n

"Networks/mask to scan". For example: -n 12.1.1.1/24,24.1.1.1/24 (note:different subnet separated by comma). The flag -n is provided a set of IPs to be scanned on the subnet (i.e. A.B.C.D/24) or use the -f with text file holding an IP on each line.

-s

"Subnet number" - unique number for local subnet. (on each subnet you should give different number.)

-h

"help" Print a brief help message and exits.

-f

"filename" Specifies a file that holds IPs list. If provided avoids the scan of IPs and overrides the -n option.

## EXAMPLES
ib2ib2_setup with -a (subnet to scan):

ib2ib_setup -d ib0 -a 61.130.1.1/24,61.130.2.1/24 -s 3

ib2ib_Setup with -f (read IPs from file):

ib2ib_setup -d ib0 -f my_ips_list.txt -s 3

## SEE ALSO
ibnetdiscover(8)

branch: sisyphus


mlnxofedctl

title: mlnxofedctl(8)

text:
# mlnxofedctl(8)

## NAME
mlnxofedctl - load and unload mlnx-ofed kernel modules

## SYNOPSIS
mlnxofedctl [-a|--altmods]<command>

## DESCRIPTION
mlnxofedctl is basically a wrapper around /etc/init.d/openibd or /etc/init.d/mlnx_en.d (in mlnx_en). That "init.d" script is being used as a script and should not.

Currently it supports all the commands supported by openibd, but may grow some extra functionality in the future.

## OPTIONS
-a --altmods

Load modules from /host/lib/modules instead of from /lib/modules . Runs the whole command in a separate mounts namespace.

### Supported commands
start

Load modules. In some cases it calls 'restart' on its own because it senses that a wrong version of the modules is loaded.

force-start

The start operation also checks that the modules are ones that are provided in the mlnx-ofed-kernel / mlnx-ofa_kernel / mlnx_en modules package (rpm or deb). If not, it will refuse to load modules to make sure that inbox modules will not be used. force-start ignores this sanity check and allows using modules that were not part of the MLNX_OFED / mlnx-en packages. This is also useful if you want to use kernel modules you built manually.

stop

Unload modules. Note that this unloads not only current modules but also various modules that were previously part of mlnx-ofa_kernel (such as mlnx4_core and rdma_rxe) to simplify upgrades.

restart

stop and start.

force-stop, force-restart

force-stop is the same as stop. force-restart is stop and force-start.

status

Shows that the modules are loaded. This is handy because there's no real process whose presence can provide the "state" for systemd. Generally it is a good idea to use 'restart' in many cases.

## SEE ALSO
There should be some other documentation.


updatedb

package: mlocate

title: updatedb(8)

summary: update a database for mlocate

text:
# updatedb(8)

## NAME
updatedb - update a database for mlocate

## SYNOPSIS
updatedb [OPTION]...

## DESCRIPTION
updatedb creates or updates a database used by locate(1). If the database already exists, its data is reused to avoid rereading directories that have not changed.

updatedb is usually run daily by cron(8) to update the default database.

## EXIT STATUS
updatedb returns with exit status 0 on success, 1 on error.

## OPTIONS
The PRUNE_BIND_MOUNTS, PRUNEFS, PRUNENAMES and PRUNEPATHS variables, which are modified by some of the options, are documented in detail in updatedb.conf(5).

-f, --add-prunefs FS

Add entries in white-space-separated list FS to PRUNEFS.

-n, --add-prunenames NAMES

Add entries in white-space-separated list NAMES to PRUNENAMES.

-e, --add-prunepaths PATHS

Add entries in white-space-separated list PATHS to PRUNEPATHS.

-U, --database-root PATH

Store only results of scanning the file system subtree rooted at PATH to the generated database. The whole file system is scanned by default. locate(1) outputs entries as absolute path names which don't contain symbolic links, regardless of the form of PATH.

--debug-pruning

Write debugging information about pruning decisions to standard error output.

-h, --help

Write a summary of the available options to standard output and exit successfully.

-o, --output FILE

Write the database to FILE instead of using the default database.

--prune-bind-mounts FLAG

Set PRUNE_BIND_MOUNTS to FLAG, overriding the configuration file.

--prunefs FS

Set PRUNEFS to FS, overriding the configuration file.

--prunenames NAMES

Set PRUNENAMES to NAMES, overriding the configuration file.

--prunepaths PATHS

Set PRUNEPATHS to PATHS, overriding the configuration file.

-l, --require-visibility FLAG

Set the “require file visibility before reporting it” flag in the generated database to FLAG. If FLAG is 0 or no, or if the database file is readable by "others" or it is not owned by slocate, locate(1) outputs the database entries even if the user running locate(1) could not have read the directory necessary to find out the file described by the database entry.

If FLAG is 1 or yes (the default), locate(1) checks the permissions of parent directories of each entry before reporting it to the invoking user. To make the file existence truly hidden from other users, the database group is set to slocate and the database permissions prohibit reading the database by users using other means than locate(1), which is set-gid slocate.

Note that the visibility flag is checked only if the database is owned by slocate and it is not readable by "others".

-v, --verbose

Output path names of files to standard output, as soon as they are found.

-V, --version

Write information about the version and license of locate on standard output and exit successfully.

## EXAMPLES
To create a private mlocate database as an user other than root, run

updatedb -l 0 -o db_file -U source_directory

Note that all users that can read db_file can get the complete list of files in the subtree of source_directory.

## FILES
/etc/updatedb.conf

A configuration file. See updatedb.conf(5).

/var/lib/mlocate/mlocate.db

The database updated by default.

## SECURITY
Databases built with --require-visibility no allow users to find names of files and directories of other users, which they would not otherwise be able to do.

## NOTES
The accompanying locate(1) utility was designed to be compatible to slocate and attempts to be compatible to GNU locate where possible. This is not the case for updatedb.

## AUTHOR
Miloslav Trmac <mitr@redhat.com>

## SEE ALSO
locate(1), mlocate.db(5), updatedb.conf(5)


mfschunkdbdump

package: moosefs-chunkserver

title: mfschunkdbdump(8)

text:
# mfschunkdbdump(8)

## NAME
mfschunkdbdump - dumps data stored by a chunkserver in a chunkdb file

## SYNOPSIS
mfschunkdbdump chunkdb_filename

## DESCRIPTION
mfschunkdbdump dumps data, stored by a chunkserver in a chunkdb file, into human-readable (txt) format.

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfschunkserver(8)


mfschunkserver

title: mfschunkserver(8)

text:
# mfschunkserver(8)

## NAME
mfschunkserver - start, restart or stop MooseFS chunkserver process

## SYNOPSIS
mfschunkserver [-c CFGFILE] [-f] [-d] [-u] [-n] [-t LOCKTIMEOUT] [ACTION]

mfschunkserver -v

mfschunkserver -h

## DESCRIPTION
mfschunkserver is the data server of MooseFS.

## OPTIONS
-v

print version information and exit

-h

print usage information and exit

-c CFGFILE

specify alternative path of configuration file (default is mfschunkserver.cfg in system configuration directory)

-f

run in foreground, don't daemonize

-d

run with dangerous options (names: DANGEROUS_*)

-u

log undefined configuration values (when default is assumed)

-n

do not attempt to increase limit of core dump size

-t LOCKTIMEOUT

how long to wait for lockfile (in seconds; default is 60 seconds)

ACTION

tells chunkserver to perform one of the following actions:

start

Start chunkserver process if the process is not already running, otherwise display error message.

stop

Stop chunkserver process if the process is running, otherwise display error message.

restart

(default action) If the chunkserver process is running, restart it, if it's not running, start it.

reload

Send a signal to chunkserver process to reload config files.

info

Send a signal to chunkserver process to dump debug information file in working directory.

test

Displays "mfschunkserver pid: PID" if the chunkserver is running (and return 0) or "mfschunkserver is not running" otherwise (and return 1).

kill

Send termination signal to chunkserver process.

restore

Not implemented.

## FILES
mfschunkserver.cfg

configuration file for MooseFS chunkserver process; refer to mfschunkserver.cfg(5) manual for details

mfshdd.cfg

list of directories (mountpoints) used for MooseFS storage; refer to mfshdd.cfg(5) manual for details

.mfschunkserver.lock

lock file of running MooseFS chunkserver process (created in data directory)

chunkserverid.mfs

chunkserver ID, assigned by MooseFS master during first connection (created in data directory)

csstats.mfs

chunkserver charts stats (created in data directory)

.mfschunkserver_info.txt

chunkserver info file, created by sending the process INFO signal, with work parameters that can be used for debugging/support purposes (created in data directory)

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8), mfsmount(8), mfschunkserver.cfg(5), mfshdd.cfg(5)


mfschunktool

title: mfschunktool(8)

text:
# mfschunktool(8)

## NAME
mfschunktool - checks chunk integrity offline

## SYNOPSIS
mfschunktool [-f] [-r] [-n] [-e] [-x] [-m damaged_dir] chunk_file|mfs_hdd_path ...

## DESCRIPTION
mfschunktool checks chunk integrity using stored CRC checksums in chunk's header. It can also 'repair' chunk (fix stored checksums). This tool may be useful to check last written chunks after possible data corruption (power down etc.) If the supplied parameter is a file, the tool will check this file. If the supplied parameter is a directory, the tool will traverse this directory recursively and try to check all files that seem to be chunks (they are named like chunk files or, if -n option is used, also have headers like chunk files, even when the name is wrong).

Notice! This tool should never be used while the chunk server process is active! If the tool is used on a chunk disk (aka path in mfshdd.cfg file) it will check if the chunk server is working and refuse to operate. But if it's used on a single file or subdirectory, such check is not possible and it's the responsibility of the user to make sure the tool is not used on "working" chunks, as it could lead to data loss.

## OPTIONS
-f

turn on fast mode (in this mode only last block is tested - usually this is enough to find corrupted chunks)

-r

turn on repair mode (if checksums on given chunk don't match then they will be overwritten by checksums calculated using actual data)

-n

turn on name fixing mode (if the chunk file name is not correct but there is proper file header, the tool will rename given file using data stored in the header)

-e

turn on empty block crc check for 1.0 version chunks (force checking crc values for non existing blocks - may fail in case of chunks that were truncated)

-x

turn on reporting successful check (print 'OK' message when everything is correct)

-m damaged_dir

move damaged chunks to a specified directory damaged_dir; see NOTES

## NOTES
The option to move damaged chunks to a specified directory is most useful when whole directories (disks) with chunks are scanned, and can be employed in different ways, depending on what other options are used at the same time.

If -r option is used together with -m option, then only chunks that are unrepairable will be moved. This is a fast approach to chunk repairing, that repairs and cleans the chunk directory (disk) in one go.

If only option -m is used, then all damaged chunks will be moved to a specified directory. The user can then use the mfschunktool again in this directory, this time with the -r option, to repair all chunks that can be repaired, but only introduce the repaired chunks back into the system if there is no other copy available from another chunkserver (a copy that did not need a repair operation in the first place). This is a more time consuming, but safer approach to repairing multiple chunks, e.g. after a power failure.

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfschunkserver(8)


mfscsstatsdump

title: mfscsstatsdump(8)

text:
# mfscsstatsdump(8)

## NAME
mfscsstatsdump - dump usage data from chunkserver stats file in csv or png format

## SYNOPSIS
mfscsstatsdump -f fields [-i stats_file] [-r range][-s separator] [-p png_filename [-x chart_width] [-y chart_height]] [-hHd]

## DESCRIPTION
mfscsstatsdump dumps usage data from chunkserver stats file. These are the same data sets that are used to make GUI charts. Output can be either in text format (csv) or in graphical format (png). That means -p, -x and -y options are mutually exclusive with -h, -H and -d options.

MooseFS chunkserver saves the stats file in the DATA_PATH directory - see mfschunkserver.cfg(5)

### OUTPUT
Text output - text (csv) file where first column is a timestamp (or date if -d option was specified), the following column are what was specified with the -f options, formatted according to used options (none, -s and -h or -H)

Graphical output - one png file with a chart is created for every field specified with the -f option, according to the naming scheme declared with the -p option. Size may be adjusted with -x and -y options.

## OPTIONS
-f

field names separated by ',' (see FIELDS section); at least one field is mandatory; if an asterisk (*) is used, all fields are dumped

-i

name of mfs binary stats file (default: default_data_path/csstats.mfs)

-r

range type: 0 - short range (minute) 1 - medium range (6 minutes) 2 - long range (30 minutes) 3 - very long range (day)

-s

specify column separator (default: tabulator)

-p

optional PNG filename (field name will be added before .png; YYYY -> YYYY_FIELD.png, YYYY.png -> YYYY_FIELD.png)

-x

PNG chart width (default: 1600)

-y

PNG chart height (should be divisible by 20 - if not then it will be adjusted; default:320)

-h

"human-readable" numbers using base 2 prefixes (IEC 60027)

-H

"human-readable" numbers using base 10 prefixes (SI)

-d

show timestamps in YYYY-MM-DD HH:MM format

### FIELDS
ucpu

User cpu usage

scpu

System cpu usage

cpu

Total cpu usage (in csv sum of scpu and ucpu, in png shows both in different colors)

masterin

Data received from master

masterout

Data sent to master

csrepin

Data received by replicator

csrepout

Data sent by replicator

csservin

Data received by csserv

csservout

Data sent by csserv

bwin

Data bandwidth in (in csv sum of csrepin and csservin, in png shows both in different colors)

bwout

Data bandwidth out (in csv sum of csrepout and csservout, in png shows both in different colors)

hdrbytesr

Bytes read (headers)

hdrbytesw

Bytes written (headers)

hdrllopr

Low level reads (headers)

hdrllopw

Low level writes (headers)

databytesr

Bytes read (data)

databytesw

Bytes written (data)

datallopr

Low level reads (data)

datallopw

Low level writes (data)

hddread

HDD read (in csv sum of hdrbytesr and databytesr, in png shows both in different colors)

hddwrite

HDD write (in csv sum of hdrbytesw and databytesw, in png shows both in different colors)

hddopsr

HDD low level read (in csv sum of hdrllopr and datallopr, in png shows both in different colors)

hddopsw

HDD low level write (in csv sum of hdrllopw and datallopw, in png shows both in different colors)

hlopr

High level reads

hlopw

High level writes

rtime

Read time

wtime

Write time

repl

Replicate chunk ops

create

Create chunk ops

delete

Delete chunk ops

version

Set version ops

duplicate

Duplicate ops

truncate

Truncate ops

duptrunc

Duptrunc (duplicate+truncate) ops

test

Test chunk ops

load

Server load

memoryrss

Resident memory usage

memoryvirt

Virtual memory usage

mem

Total memory usage (in csv is the same as memoryvirt, in png shows both memoryrss and memoryvirt using two colors)

movels

Low speed move ops

movehs

High speed move ops

move

Low speed + high speed move ops (in png shows movels and movehas using two colors)

change

Chunk changes in metadata (sum of version + duplicate + truncate + duptrunc + split)

split

Split ops

usedspace

Used HDD space in bytes (mark for removal excluded)

totalspace

Total HDD space in bytes (mark for removal excluded)

space

Total HDD space (in csv same as totalspace, in png shows both usedspace and totalspace using two colors)

chunkcount

Number of stored chunks (mark for removal excluded)

tdusedspace

Used HDD space in bytes on disks marked for removal

tdtotalspace

Total HDD space in bytes on disks marked for removal

tdchunkcount

Number of chunks stored on disks marked for removal

copychunks

Number of chunks stored in copy format (all disks)

ec4chunks

Number of chunk parts stored in EC4 format (all disks)

ec8chunks

Number of chunk parts stored in EC8 format (all disks)

chunks

Sum of copychunks + ec4chunks + ec8chunks (in png shows all three in different colors)

hddok

Number of valid folders (hard drives)

hddmfr

Number of folders (hard drives) that are marked for removal

hdddmg

Number of folders (hard drives) that are marked as damaged

hddcnt

Number of folders (hard drives) regardless of status, aka sum of hddok + hddmfr + hdddmg (in png shows all three in different colors)

udiff

Difference in usage percent between the most and least used disk

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfschunkserver(8), mfsstatsdump(8)


mfsbdev

package: moosefs-client

title: mfsbdev(8)

text:
# mfsbdev(8)

## NAME
mfsbdev - MooseFS block device daemon/management tool

## SYNOPSIS
mfsbdev start [-H masterhost] [-P masterport] [-B masterbind] [-S masterpath] [-p masterpassword | -x passwordfile] [-l linksocket] [-i init_mappings_file] [-o options]

mfsbdev stop [-l linksocket]

mfsbdev map [-l linksocket] -f mfsfile [-d nbddevice] [-n linkname] [-s bdevsize] [-b blocksize | -5 | -1 | -2 | -4] [-r] [-i]

mfsbdev unmap [-l linksocket] ( -f mfsfile | -d nbddevice | -n linkname )

mfsbdev list [-l linksocket] [-t m|u|i]

mfsbdev resize [-l linksocket] ( -f mfsfile | -d nbddevice | -n linkname ) [-s bdevsize]

## DESCRIPTION
This tool is used to manage block devices. This tool works in Linux ONLY. Kernel module nbd must be loaded for this tool to work properly.

### COMMANDS
start - starts the daemon; the daemon only listens on a socket at this point; all the other commands use the socket to communicate with the daemon; if no socket is specified via -l option, the default is used: /dev/mfs/nbdsock

stop - stops the daemon

map - maps a file on mfs to be used as a block device

unmap - removes a mapping

list - lists current mappings

resize - changes the size of a block device (requires kernel version 4.18 or higher)

## OPTIONS
-H - master host; default is 'mfsmaster'

-P - master port; default is '9421'

-S - master path (subfolder in MFS that will be used as a root for all block device mappings); default is '/'

-p - master password; mutually exclusive with -x option; if neither -p nor -x are supplied, the tool tries to connect without a password

-x - path to a file containing master password; mutually exclusive with -p option; if neither -p nor -x are supplied, the tool tries to connect without a password

-l - path to communication socket; default is /dev/mfs/nbdsock

-f - path to mfs file used to map block device;

-d - path to network block device ('/dev/nbdX'); by default (if this parameter is not supplied) first available device is used with the map command

-n - name of symbolic link created in '/dev/mfs', pointing at the network block device created by the map command; default is a combination of master hostname, port and mfs file name

-s - size of the block device, both SI and IEC suffixes can be used; default is the size of the file the block device is mapped to

-b - block size in bytes

-5 - use block size 512 bytes (eq to -b 512)

-1 - use block size 1024 bytes (eq to -b 1024)

-2 - use block size 2048 bytes (eq to -b 2048)

-4 - use block size 4096 bytes (eq to -b 4096)

-r - maps block device as readonly (allows multiple mappings of the same file)

-i (map) - ignore locks; one file may be mapped to more than one block device, each map operation will try to obtain the appropriate lock (shared for ro, exclusive for rw) but will succeed even if the lock is not obtained

-t - forces the list command to display information in a format ready to use with map (m parameter) or unmap (u parameter) command or with MooseFS mfsbdev.cfg file format (i parameter)

-i (start) - use config file supplied in parameter to start initial block devices; for formatting of the config see mfsbdev.cfg(5)

-o - additional params, mfsmount-style, many params can be defined, separated by comma:

mfswritecachesize=N

specify write cache size in MiB (in range: 16..2048 - default: 128)

mfsreadaheadsize=N

define size of all read ahead buffers in MiB (in range: 16..2048 - default: 128)

mfsreadaheadleng=N

define amount of bytes to be additionally read (in range: 128KiB..2MiB - default: 2097152 = 2MiB)

mfsreadaheadtrigger=N

define amount of bytes read sequentially that turns on read ahead (default: 20971520)

mfserroronlostchunk

when all known chunkservers are connected to the master and the required chunk is missing then immediately finish I/O and return an error

mfserroronnospace

when all known chunkservers are connected to the master and there is no free space then immediately finish I/O and return an error

mfsioretries=N

specify number of retries before I/O error is returned (default: 30)

mfstimeout=N

define maximum timeout in seconds before I/O error is returned (default: 0 - which means no timeout)

mfslogretry=N

define minimal retry counter on which system will start log I/O messages (default: 5)

mfsmaster=HOST

connect with MooseFS master on HOST (default is mfsmaster) - equivalent to -H

mfsport=PORT

connect with MooseFS master on PORT (default is 9421) - equivalent to -P

mfsbind=IP

local address to use for connecting with master instead of default one - equivalent to -B

mfssubfolder=PATH

mount specified MooseFS directory (default is /, i.e. whole filesystem) - equivalent to -S

mfspassword=PASSWORD

authenticate to MooseFS master with PASSWORD

mfspreflabels=LABELEXPR

specify preferred labels for choosing chunkservers during I/O

mfsnbdtimeout=N

define maximum timeout in seconds before kernel gives up (default: 1800)

## FILES
mfsbdev.cfg

configuration file for MooseFS block device daemon; refer to mfsbdev.cfg(5) manual for details

## EXAMPLES
mfsbdev start - start nbd daemon with default options (masterhost = mfsmaster, masterport = 9421, linksocket = /dev/mfs/nbdsock, authentication without password)

mfsbdev start -H mfsmaster.my.domain -P 9521 -x /etc/mfs/mastersecret - start nbd daemon that will connect to master mfsmaster.my.domain on port 9521 using password read from file /etc/mfs/mastersecret

mfsbdev stop -l /tmp/mynbdinstance - stop nbd daemon using for communication unix socket /tmp/mynbdinstance

mfsbdev map -f devices/mybdev1.bin -s 2Ti -n mytestvm - add mapping to daemon using for communication default socket (/dev/mfs/nbdsock). Device will be assigned automatically, file devices/mybdev1.bin will be mapped to this device, link '/dev/mfs/mytestvm' to this device will be created and block device will have size of 2TiB.

mfsbdev unmap -n mytestvm - remove mapping that has link named mytestvm (uses link /dev/mfs/mytestvm).

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmount(8), mfsbdev.cfg(5)


mfsmount

title: mfsmount(8)

summary: mount MooseFS

text:
# mfsmount(8)

## NAME
mfsmount - mount MooseFS

## SYNOPSIS
mfsmount [HOST[:PORT]:[PATH]] [options] mountpoint

mfsmount -h|--help

mfsmount -V|--version

Since 3.0.75 (Linux only):

mount -t moosefs [options] [HOST[:PORT]:[PATH]] mountpoint

## DESCRIPTION
Mount MooseFS.

## OPTIONS

### GENERAL OPTIONS
-h, --help

display help and exit

-V

display version information and exit

### FUSE OPTIONS
-d, -o debug

enable debug mode (implies -f)

-f

foreground operation

-s

disable multi-threaded operation

### MOOSEFS OPTIONS
-c CFGFILE, -o mfscfgfile=CFGFILE

loads file with additional mount options

-m, --meta, -o mfsmeta

mount MFSMETA companion filesystem instead of primary MooseFS

-n

omit default mount options (-o allow_other)

-p

prompt for password (interactive version of -o mfspassword=PASS)

-H HOST, -o mfsmaster=HOST

connect with MooseFS master on HOST (default is mfsmaster)

-P PORT, -o mfsport=PORT

connect with MooseFS master on PORT (default is 9421)

-B IP, -o mfsbind=IP

local address to use for connecting with master instead of default one

-L IP, -o mfsproxy=IP

define listen ip address of local master proxy for communication with tools (default: 127.0.0.1)

-S PATH, -o mfssubfolder=PATH

mount specified MooseFS directory (default is /, i.e. whole filesystem)

-o mfspassword=PASSWORD

authenticate to MooseFS master with PASSWORD

-o mfspassfile=FILENAME

authenticate to MooseFS master with password stored in first line of file pointed by FILENAME

-o mfsmd5pass=MD5

authenticate to MooseFS master using directly given MD5 (only if mfspassword option is not specified)

-o mfsdonotrememberpassword

do not remember password in memory - more secure, but when session is lost then new session is created without password

-o mfsdebug

print some MooseFS-specific debugging information

-o mfsmemlock

try to lock memory (all allocated memory will be mapped to physical RAM - which also means no swapping)

-o allowoomkiller

do not disable out of memory killer (Linux only)

-o mfslimitarenas=N

if N>0 then limit glibc malloc arenas (Linux only - default: 4)

-o mfsflattrash

use flat trash structure in meta (option added for compatibility reasons - since version 3.0.64 trash is split into 4096 subfolders which reduces problems with big trashes)

-o mfsdelayedinit

connection with master is done in background - with this option mount can be run without network (good for being run from fstab / init scripts etc.)

-o mfsmkdircopysgid=N

sgid bit should be copied during mkdir operation (default depends on operating system)

-o mfssugidclearmode=SMODE

set sugid clear mode (see SUGID CLEAR MODES; default depends on operating system)

-o mfscachemode=CMODE

set cache mode (see DATA CACHE MODES; default is AUTO)

-o mfscachefiles

(deprecated) preserve file data in cache (equivalent to '-o mfscachemode=YES')

-o mfsreaddirplusminto=SEC

set minimal entry/attributes cache timeout for readdirplus in seconds (default: 0.0001)

-o mfsattrcacheto=SEC

set attributes cache timeout in seconds (default: 1.0)

-o mfsxattrcacheto=SEC

set extended attributes (xattr) cache timeout in seconds (default: 30.0)

-o mfsentrycacheto=SEC

set file entry cache timeout in seconds (default: 0.0, i.e. no cache)

-o mfsdirentrycacheto=SEC

set directory entry cache timeout in seconds (default: 1.0)

-o mfsnegentrycacheto=SEC

set negative entry cache timeout in seconds (default: 0.0)

-o mfssymlinkcacheto=SEC

set symbolic link cache timeout in seconds (default: 300.0)

-o mfsgroupscacheto=SEC

set supplementary groups cache timeout in seconds (default: 300.0); setting this value to 0 disables supplementary groups support

-o mfsrlimitnofile=N

try to change limit of simultaneously opened file descriptors on startup (default: 100000)

-o mfsnice=LEVEL

try to change nice level to specified value on startup (default: -19)

-o mfswritecachesize=N

specify write cache size in MiB (in range: 16..2048 - default: 256)

-o mfsreadaheadsize=N

define size of all read ahead buffers in MiB (in range: 16..2048 - default: 256)

-o mfsreadaheadleng=N

define amount of bytes to be additionally read (in range: 128KiB..2MiB - default: 1048576)

-o mfsreadaheadtrigger=N

define amount of bytes read sequentially that turns on read ahead (default: 10 * mfsreadaheadleng)

-o mfserroronlostchunk

when all known chunkservers are connected to the master and the required chunk is missing then immediately finish I/O and return an error

-o mfserroronnospace

when all known chunkservers are connected to the master and there is no free space then immediately finish I/O and return an error

-o mfsioretries=N

specify number of retries before I/O error is returned (default: 30)

-o mfstimeout=N

define maximum timeout in seconds before I/O error is returned (default: 0 - which means no timeout)

-o mfslogretry=N

define minimal retry counter on which system will start log I/O messages (default: 5)

-o mfsfsyncmintime=SEC

force fsync before last file close when file was opened/created at least SEC seconds earlier (default: 0.0 - always do fsync before close)

-o mfspreflabels=LABELEXPR

specify preferred labels for choosing chunkservers during I/O

-o mfsnoxattrs

turn off xattr support

-o mfsnoposixlocks

turn off support for global posix locks (lockf + ioctl) - locks will work locally

-o mfsnobsdlocks

turn off support for global BSD locks (flock) - locks will work locally

### MOUNT OPTIONS
General mount options (see mount(8) manual):

-o rw|-o ro

Mount file-system in read-write (default) or read-only mode respectively.

-o suid|-o nosuid

Enable or disable suid/sgid attributes to work.

-o dev|-o nodev

Enable or disable character or block special device files interpretation.

-o exec|-o noexec

Allow or disallow execution of binaries.

## FILES
mfsmount.cfg

configuration file for MooseFS mount daemon; refer to mfsmount.cfg(5) manual for details

## NOTES

### SUGID CLEAR MODE
During attribute change file systems sometimes clear flags suid and/or sgid. Behavior is different on different file systems. MFS tries to mimic behavior of most popular file system on given operating systems.

NEVER

MFS will not change suid and sgid bit on chown

ALWAYS

clear suid and sgid on every chown - safest operation

OSX

standard behavior in OS X and Solaris (chown made by unprivileged user clear suid and sgid)

BSD

standard behavior in *BSD systems (like in OSX, but only when something is really changed)

EXT

standard behavior in most file systems on Linux (directories not changed, others: suid cleared always, sgid only when group exec bit is set)

XFS

standard behavior in XFS on Linux (like EXT but directories are changed by unprivileged users)

### DATA CACHE MODES
There are four cache modes: DIRECT, NO, YES and AUTO. Default option is AUTO and you shuldn't change it unless you really know what you are doing. In AUTO mode data cache is managed automatically by mfsmaster.

DIRECT

forces direct io (bypasses cache)

NO,NONE or NEVER

never allow files data to be kept in cache (safest but can reduce efficiency)

YES or ALWAYS

always allow files data to be kept in cache (dangerous)

AUTO

file cache is managed by mfsmaster automatically (should be very safe and efficient)

### LABEL EXPRESSIONS
LABELEXPR grammar:

LABELEXPR

-> S ; LABELEXPR | S

S

-> S + M | M

M

-> M L | L

L

-> a .. z | A .. Z | ( S ) | [ S ]

Subexpressions should be placed in priority order. Up to nine subexpressions (priorities) can be specified.

### FSTAB
On most Unix systems mfsmount can be invoked automatically from /etc/fstab. Be aware that rw or ro option has to be specified in options. Also on many systems there should be option which informs the system that this mountpoint should be mounted after starting networking services (options such as _netdev or late).

Linux:

mfsmount mountpoint fuse options 0 0

*BSD:

mfsmount_magic mountpoint moosefs options,mountprog=/usr/local/bin/mfsmount 0 0

Since version 3.0.75 alternative form can be used:

Linux:

HOST[:PORT]:[PATH] mountpoint moosefs options 0 0

*BSD:

HOST[:PORT]:[PATH] mountpoint moosefs options,mountprog=/usr/local/bin/mfsmount 0 0

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8), mfstools(1), mfsmount.cfg(5), mount(8)


mfsgui

package: moosefs-gui

title: mfsgui(8)

text:
# mfsgui(8)

## NAME
mfsgui - start, restart or stop MooseFS GUI server

## SYNOPSIS
mfsgui [-c CFGFILE] [-f] [-d] [-u] [-n] [-t LOCKTIMEOUT] [ACTION]

mfsgui -v

mfsgui -h

## DESCRIPTION
mfsgui is the MooseFS GUI server. It consist of a HTTP server and scripts that make up the GUI interface to MooseFS. The user can access the GUI via any web browser, using the IP (or appropriate domain name) and port defined in mfsgui.cfg.

## OPTIONS
-v

print version information and exit

-h

print usage information and exit

-c CFGFILE

specify alternative path of configuration file (default is mfsgui.cfg in system configuration directory)

-f

run in foreground, don't daemonize

-d

run with dangerous options (names: DANGEROUS_*)

-u

log undefined configuration values (when default is assumed)

-n

do not attempt to increase limit of core dump size

-t LOCKTIMEOUT

how long to wait for lockfile (in seconds; default is 60 seconds)

ACTION

tells MooseFS GUI server to perform one of the following actions:

start

Start MooseFS GUI server process if the process is not already running, otherwise display error message.

stop

Stop MooseFS GUI server process if the process is running, otherwise display error message.

restart

(default action) If the MooseFS GUI server process is running, restart it, if it's not running, start it.

reload

Send a signal to MooseFS GUI server process to reload config files.

info

Send a signal to MooseFS GUI server process to dump debug information file in working directory.

test

Displays "mfsgui pid: PID" if the MooseFS GUI server is running (and return 0) or "mfsgui is not running" otherwise (and return 1).

kill

Send termination signal to MooseFS GUI server process.

restore

Not implemented.

## FILES
mfsgui.cfg

configuration file for MooseFS GUI server process; refer to mfsgui.cfg(5) manual for details

.mfsgui.lock

lock file of running MooseFS GUI server process (created in data directory)

scripts

various python, javascript, and other (static) files used to serve the GUI interface via HTTP; these files are installed in whatever directory is the default at installation time for ROOT_DIR in mfsgui.cfg

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8), mfsgui.cfg(5)


mfsmaster

package: moosefs-master

title: mfsmaster(8)

text:
# mfsmaster(8)

## NAME
mfsmaster - start, restart or stop MooseFS master process

## SYNOPSIS
mfsmaster [-c CFGFILE] [-f] [-d] [-u] [-n] [-i] [-a] [-e] [-x[x]] [-t LOCKTIMEOUT] [ACTION]

mfsmaster -v

mfsmaster -h

## DESCRIPTION
mfsmaster is the master program of MooseFS.

## OPTIONS
-v

print version information and exit

-h

print usage information and exit

-c CFGFILE

specify alternative path of configuration file (default is mfsmaster.cfg in system configuration directory)

-f

run in foreground, don't daemonize

-d

run with dangerous options (names: DANGEROUS_*)

-u

log undefined configuration values (when default is assumed)

-n

do not attempt to increase limit of core dump size

-i

ignore some metadata structure errors

-a

automatically restore metadata from change logs

-e

(pro only) start without metadata (used to start additional masters)

-x

produce more verbose output

-xx

even more verbose output

-t LOCKTIMEOUT

how long to wait for lockfile (in seconds; default is 1800 seconds)

ACTION

tells master to perform one of the following actions:

start

Start master process if the process is not already running, otherwise display error message.

stop

Stop master process if the process is running, otherwise display error message.

restart

(default action) If the master process is running, restart it, if it's not running, start it.

reload

Send a signal to master process to reload config files.

info

Send a signal to master process to dump debug information file in working directory.

test

Displays "mfsmaster pid: PID" if the master is running (and return 0) or "mfsmaster is not running" otherwise (and return 1).

kill

Send termination signal to master process.

restore

Restore current metadata file using backup metadata and changelog files (if possible, i.e. if correct files exist), write it to working directory and exit.

## FILES
mfsmaster.cfg

configuration file for MooseFS master process; refer to mfsmaster.cfg(5) manual for details

mfsexports.cfg

MooseFS access control file; refer to mfsexports.cfg(5) manual for details

mfstopology.cfg

Network topology definitions; refer to mfstopology.cfg(5) manual for details

mfsipmap.cfg

Chunkservers IP mapping definitions; refer to mfsipmap.cfg(5) manual for details

.mfsmaster.lock

lock file of running MooseFS master process (created in data directory)

.bgwriter.lock

lock file of running MooseFS master subprocess for storing metadata (created in data directory)

metadata.mfs, metadata.mfs.back

MooseFS filesystem metadata image (created in data directory)

metadata.crc

CRC of metadata.mfs file (created in data directory)

metadata.mfs.empty

An empty metadata file, to be used when starting up a fresh MooseFS instance (created in data directory)

changelog.*.mfs

MooseFS filesystem metadata change logs (created in data directory)

stats.mfs

master charts stats (created in data directory)

.mfsmaster_info.txt

master info file, created by sending the process INFO signal, with work parameters that can be used for debugging/support purposes (created in data directory)

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfschunkserver(8), mfsmount(8), mfsmaster.cfg(5), mfsexports.cfg(5), mfstopology.cfg(5)


mfsmetadirinfo

title: mfsmetadirinfo(8)

text:
# mfsmetadirinfo(8)

## NAME
mfsmetadirinfo - uses MooseFS metadata to calculate precise directory information (similar to mfsdirinfo)

## SYNOPSIS
mfsmetadirinfo [-f J|C|C x] [-o outputfile] [-a sum_name] metadata_file PATH [PATH...]

## DESCRIPTION
mfsmetadirinfo is a tool that can be used to calculate precise directory information such as number of inodes, number of chunks, total length of all files, size, real size etc. Output can be generated as plain text, CSV or JSON. Data for calculations is read from indicated metadata.mfs mfs master metadata file and is calculated for directory(ies) specified by PATH parameter(s) - relative in mfs instance. Default output is human-readable plain text, JSON or CSV can be selected using options.

Options:

-f

switch output format to JSON (J) or CSV (C); for CSV, if only C is specified, default separator will be used (comma), if second character is specified, this character will be used as the separator in CSV data

-o

write output to outputfile instead of stdout

-a

optional parameter that indicates the tool should calculate the information for all supplied paths together (a sum), this calculation is indicated by sum_name in output data

metadata_file

path to metadata.mfs file

### OUTPUT FIELDS
For each PATH and, if defined, for sum_name, following information will be indicated:

inodes

number of all unique inodes (file system objects)

files

number of all unique files

dirs

number of all unique directories

chunks

number of all unique chunks

kchunks

number of all unique chunks using KEEP policy

achunks

number of all unique chunks using ARCH policy

length

total length of all unique files

size

total size of all unique chunks

rsize

total real size of all unique chunks (number of copies taken into account)

ksize

hypothetical real size of all unique chunks if all were using KEEP policy

asize

hypothetical real size of all unique chunks if all were using ARCH policy

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8), mfsmetadump(8), mfsdirinfo(1)


mfsmetadump

title: mfsmetadump(8)

text:
# mfsmetadump(8)

## NAME
mfsmetadump - dump MooseFS metadata info in human readable format

## SYNOPSIS
mfsmetadump [-d] [-s section_name] metadata_file

## DESCRIPTION
mfsmetadump dumps MooseFS metadata info in human readable format. Output consists of several sections with different types of information. Every section consist of header data - rows starting with hash (#) sign - and content data (may be empty).

## OPTIONS
-d - replace all non-printable characters (codes < 32 and > 126) with '.' (it was default behaviour in version < 3.0.110).

-s - dump only specified section of the file. Possible sections:

```
	HEAD - header info
	SESS - client sessions
	LABS - labels (not used)
	SCLA - storage classes
	PATT - pattern overrides
	NODE - tree nodes (i-nodes)
	EDGE - tree edges (file names)
	FREE - free nodes (deleted i-nodes)
	QUOT - quota definitions
	XATR - xattr data
	PACL - posix acl data
	OPEN - open files
	FLCK - flock data
	PLCK - posix locks (lockf,ioctl) data
	CSDB - active chunkservers
	CHNK - chunks
```

metadata_file

path to metadata.mfs file

## NOTES
Each metadata section - with the exception of the HEAD section - consist of a constant set of HEADER fields and a variable set of this section specific fields. HEAD section contains only section specific fields. The HEADER fields and all the section fields are listed below:

### SECTION HEADER
section header

section header (section type + version)

length

length of section

section type

name of section

version

hexadecimal representation of section version

### FILE HEADER SECTION (HEAD)
header

MooseFS version

version

metadata file version

fileid

metadata file id

### SESSIONS SECTION (SESS)
nextsessionid

first free session id

statscount

number of stats remembered in each session

SESSION

line describing a single session

```
s	session id
e	exports checksum
p	IP address
r	root inode number
f	session flags
u	umask
g	min and max goal (redundancy level)
t	min and max trash retention
m	maproot uid,gid and mapall uid,gid
x	disabled operations
d	disconnection time (optional)
c	current hour stats data
l	last hour stats data
i	session name (usually local mount point)
```

### STORAGE CLASS SECTION (SCLA), formerly LABELS SECTION (LABS)
LABELDESC

line with label description (existed only in LABS)

```
l	label letter
n	label description
```

SCLASS

(formerly LABELSET) line with storage class used in system

```
#	storage class id
x	admin only
m	mode
d	arch delay
c	create labels
k	keep labels
a	archive labels
n	name
```

SCLASSMAIN

(used in version 4.0+ instead of SCLASS) line with common parameters of storage class

```
#	storage class id
x	admin only
m	create mode
a	arch mode
d	arch delay
t	min trash retention
n	name
```

SCLASSEXPR

(used in version 4.0+ instead of SCLASS) line with label expression

```
#	storage class id
t	type ([C]reate,[K]eep,[A]rchive or [T]rash)
e	expression
```

### PATTERNS SECTION (PATT)
PATTERN

line with pattern definition

```
v	priority
#	storage class id
t	trash retention
e	flags (extra mfs attributes)
u	uid
g	gid
p	pattern
```

### NODES SECTION (NODE)
maxinode

maximum inode number used by system

hashelements

number of inodes in hash tabble

NODE

line with node (inode) description

```
k	node type (-,D,S,F,B,C,L,T,R)
	-	file
	D	directory
	S	socket
	F	fifo
	B	block device
	C	character device
	L	symbolic link
	T	trash file
	R	sustained file (removed open file)
i	inode number
#	storage class id
e	flags (extra mfs attributes)
w	windows attributes
m	mode
u	uid
g	gid
a,m,c	atime, mtime, ctime
t	trash retention
d	rdevhi,rdevlo (only block and character devices)
p	path (only symbolic links)
l	file length (only files)
c	chunk list (only files)
r	sessions that have this file open (only files)
```

### EDGES SECTION (EDGE)
nextedgeid

next available edge id (descending)

EDGE

line with edge description

```
p	parent inode number
c	child inode number
i	edge id
n	edge name
```

### FREE NODES SECTION (FREE)
free nodes

number of free (reusable) nodes

FREEID

line with free inode description

```
i	inode number
f	deletion timestamp
```

### QUOTA SECTION (QUOT)
quota nodes

number of nodes with quota

QUOTA

line with quota description

```
i	inode number
g	grace period
e	exceeded
f	flags
s	soft quota exceeded timestamp
si	soft inode quota
hi	hard inode quota
sl	soft length quota
hl	hard length quota
ss	soft size quota
hs	hard size quota
sr	soft real size quota
hr	hard real size quota
```

### XATTR SECTION (XATR)
XATTR

line with xattr description

```
i	inode number
n	xattr name
v	xattr value
```

### POSIX ACL SECTION (PACL)
POSIXACL

line with acl description

```
i	inode number
t	acl type
u	user (file owner) permissions
g	group permissions
o	other permissions
m	permission mask
n	named permissions - list of objects:
u(U):P	permissions P for user with uid U
g(G):P	permissions P for group with gid G
```

### OPEN FILES SECTION (OPEN)
OPENFILE

line with open file description

```
s	session id
i	inode number
```

### FLOCK LOCK SECTION (FLCK)
FLOCK

line with flock-lock description

```
i	inode number
s	session id
o	lock owner (FUSE lock owner)
t	lock type ('R' - shared lock, 'W' - exclusive lock)
```

### POSIX LOCK SECTION (PLCK)
POSIXLOCK

line with posix-lock description

```
i	inode number
s	session id
o	lock owner (FUSE lock owner)
p	local process id (owner pid)
r	lock range in format <START,END)
t	lock type ('R' - shared lock, 'W' - exclusive lock)
```

### CHUNKSERVERS SECTION (CSDB)
chunk servers

number of chunkservers

CHUNCKSERVER

line with chunk server description

```
i	server ip
p	server port
#	server id
m	maintenance mode
t	maintenance timeout timestamp
```

### CHUNKS SECTION (CHNK)
nextchunkid

first available chunk number

CHUNK

line with chunk description

```
i	chunk number
v	chunk version
t	timestamp, if in the future, means lock timestamp, if in the past, last modification timestamp
a	archive flag
(s,#)	list of entries, s is storage class id, # is number of files in this storage class containing this chunk
c	calculated storage class id (effectively used class id, if a chunk has more than one)
```

NOTICE! If a chunk's timestamp equals 0, it means the chunk was created by MooseFS version older than 4.45.0 and has not been locked or modified since.

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8)


mfsmetarestore

title: mfsmetarestore(8)

text:
# mfsmetarestore(8)

## NAME
mfsmetarestore - doesn't exist in this version of MooseFS

## DESCRIPTION
This tool was removed as of version 1.7. To achieve the same effect, simply start your mfsmaster with "-a" option.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8)


mfsmetasearch

title: mfsmetasearch(8)

text:
# mfsmetasearch(8)

## NAME
mfsmetasearch - uses MooseFS metadata to find specific files

## SYNOPSIS
mfsmetasearch [-f J|C|C x] [-o output_file] [-e expr | -c chunkid_file] metadata_file

## DESCRIPTION
mfsmetasearch is a tool that finds files and other objects in MooseFS's metadata that either match the provided expression (if -e option is used) or contain one or more of the chunk numbers listed in hexadecimal format in the provided file (if -c option is used).

## OPTIONS
-f

switch the default TXT output format to JSON (J) or CSV (C); for CSV, if only C is specified, default separator will be used (comma), if second character is specified, this character will be used as the separator in CSV data

-o

write output to output_file instead of stdout

-e

expression expr that a file or object must match to be listed in output

-c

file chunkid_file containing chunk ids, only files containing one of these chunks will be listed in output; chunks ids must be listed in hexadecimal format, only last 56 bits of read values will be considered chunk ids, meaning bits denoting EC parts don't have to be stripped in this case

metadata_file

path to metadata.mfs file

### EXPRESSIONS
The expression can consist of a number of symbols, values and operators. A symbol is a property of a file, a value is the value of that property for a particular file and operators build the entire expression to indicate if a certain property should match, be different etc.

Symbols and values:

```
inode		inode number (value: numeric)
type			inode type (constants list: file,directory,symlink,fifo,blockdev,chardev,socket,trash,sustained)
eattr		extra attributes bit mask (bit constants list: noowner,noattrcache,noentrycache,nodatacache,snapshot,undeletable,appendonly,immutable)
sclass		number of storage class (value: numeric; class numbers can be checked via GUI or CLI)
uid			user id (value: numeric)
gid			group id (value: numeric)
mode			access mode bit mask (bit constants list: sticky,sgid,suid,ur,uw,ux,gr,gw,gx,or,ow,ox)
umode		access mode for uid bit mask (bit constants list: read,write,execute)
gmode		access mode for gid bit mask (bit constants list: read,write,execute)
omode		access mode for others bit mask (bit constants list: read,write,execute)
atime		access time (value: numeric - unix timestamp in seconds)
mtime		modify time (value: numeric - unix timestamp in seconds)
ctime		change time (value: numeric - unix timestamp in seconds)
tretention	trash retention in hours (value: numeric)
length		file length (value: numeric; zero for other objects)
major		major id (value: numeric; for blockdev and chardev only)
minor		minor id (value: numeric; for blockdev and chardev only)
chunkid		chunk's numerical id (value: numeric; expression will be tested for all file chunks and accepted if one of them is true)
```

Accepted operators (C-style): - + * / % >> << < <= > >= == != ~ & ^ | ! && ^^ || ?:

## EXAMPLES
mfsmetasearch -e 'length<4096' /var/lib/mfs/metadata.mfs.back

this will show all files shorter than 4096 bytes (having size smaller than 4096 bytes) and all objects other than files

mfsmetasearch -e 'type==file && length<4096' /var/lib/mfs/metadata.mfs.back

this will show all files shorter than 4096 bytes (having size smaller than 4096 bytes)

mfsmetasearch -e 'umode&execute && gmode&execute && !(omode&execute)' /var/lib/mfs/metadata.mfs.back

this will show all inodes that have the execute bit set for both user and group, but not others

mfsmetasearch -e 'chunkid==101020 || chunkid==0xFF77AA || chunkid==01234 || chunkid==0b1010101' /var/lib/mfs/metadata.mfs.back

this will show all files that contain chunk with decimal id 101020 or chunk with hex id FF77AA or chunk with octal id 1234 or chunk with binary id 1010101

mfsmetasearch -e 'sclass==11' /var/lib/mfs/metadata.mfs.back

this will show all objects that have storage class set to the class with number 11

mfsmetasearch -c /tmp/mychunkids.txt /var/lib/mfs/metadata.mfs.back

this will show all files, that contain one of the chunks listed in text file /tmp/mychunkids.txt

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8), mfsmetadump(8)


mfsstatsdump

title: mfsstatsdump(8)

text:
# mfsstatsdump(8)

## NAME
mfsstatsdump - dump usage data from master stats file in csv or png format

## SYNOPSIS
mfsstatsdump -f fields [-i stats_file] [-r range] [-s separator] [-p png_filename [-x chart_width] [-y chart_height]] [-hHd]

## DESCRIPTION
mfsstatsdump dumps usage data from master stats file. These are the same data sets that are used to make GUI charts. Output can be either in text format (csv) or in graphical format (png). That means -p, -x and -y options are mutually exclusive with -h, -H and -d options.

MooseFS master server saves the stats file in the DATA_PATH directory - see mfsmaster.cfg(5)

### OUTPUT
Text output - text (csv) file where first column is a timestamp (or date if -d option was specified), the following column are what was specified with the -f options, formatted according to used options (none, -s and -h or -H)

Graphical output - one png file with a chart is created for every field specified with the -f option, according to the naming scheme declared with the -p option. Size may be adjusted with -x and -y options.

## OPTIONS
-f

field names separated by ',' (see FIELDS section); at least one field is mandatory; if an asterisk (*) is used, all fields are dumped

-i

name of mfs binary stats file (default: default_data_path/stats.mfs)

-r

range type: 0 - short range (minute) 1 - medium range (6 minutes) 2 - long range (30 minutes) 3 - very long range (day)

-s

specify column separator (default: tabulator)

-p

optional PNG filename (field name will be added before .png; YYYY -> YYYY_FIELD.png, YYYY.png -> YYYY_FIELD.png)

-x

PNG chart width (default: 1600)

-y

PNG chart height (should be divisible by 20 - if not then it will be adjusted; default:320)

-h

"human-readable" numbers using base 2 prefixes (IEC 60027)

-H

"human-readable" numbers using base 10 prefixes (SI)

-d

show timestamps in YYYY-MM-DD HH:MM format

### FIELDS
ucpu

User cpu usage

scpu

System cpu usage

cpu

Total cpu usage (in csv sum of scpu and ucpu, in png shows both in different colors)

delete

Number of chunk deletions

replicate

Number of chunk replications

statfs

Number of statfs operations

getattr

Number of getattr operations

setattr

Number of setattr operations

lookup

Number of lookup operations

mkdir

Number of mkdir operations

rmdir

Number of rmdir operations

symlink

Number of symlink operations

readlink

Number of readlink operations

mknod

Number of mknod operations

unlink

Number of unlink operations

rename

Number of rename operations

link

Number of link operations

readdir

Number of readdir operations

open

Number of open operations

read

Number of read operations

write

Number of write operations

prcvd

Received packets

psent

Sent packets

brcvd

Received bytes

bsent

Sent bytes

memoryrss

Resident memory usage

memoryvirt

Virtual memory usage

mem

Total memory usage (in csv is the same as memoryvirt, in png shows both memoryrss and memoryvirt using two colors)

usedspace

Used raw disk space

totalspace

Total raw disk space

space

Total raw disk space (in csv the same as totalspace, in png shows both usedspace and totalspace using two colors)

readchunk

Number of chunk_read operations

writechunk

Number of chunk_write operations

create

Number of chunk creation attempts

change

Number of chunk internal operation attempts

delete_ok

Number of successful chunk deletions

delete_err

Number of unsuccessful chunk deletions

delete_stat

Sum of successful and unsuccessful chunk deletions (in png shows both delete_ok and delete_err using two colors)

replicate_ok

Number of successful chunk replications

replicate_err

Number of unsuccessful chunk replications

replicate_stat

Sum of successful and unsuccessful chunk replications (in png shows both replicate_ok and replicate_err using two colors)

create_ok

Number of successful chunk creations

create_err

Number of unsuccessful chunk creations

create_stat

Sum of successful and unsuccessful chunk creations (in png shows both create_ok and create_err using two colors)

change_ok

Number of successful chunk internal operations

change_err

Number of unsuccessful chunk internal operations

change_stat

Sum of successful and unsuccessfulchunk internal operations (in png shows both change_ok and change_err using two colors)

split_ok

Number of successful chunk split operations

split_err

Number of unsuccessful chunk split operations

split_stat

Sum of successful and unsuccessful chunk split operations (in png shows both split_ok and split_err using two colors)

fileobjects

Number of file objects

metaobjects

Number of non-file objects (directories,symlinks,etc.)

objects

Number of all objects (in png shows both fileobjects and metaobjects using two colors)

chunksec8

Total number of chunks stored in EC8 format

chunksec4

Total number of chunks stored in EC4 format

chunkscopy

Total number of chunks stored in COPY format

chunks

Total number of chunks stored in any format (in png shows chunksec8, chunksec4 and chunkscopy using three colors)

chregdanger

Number of endangered chunks (mark for removal excluded)

chregunder

Number of undergoal chunks (mark for removal excluded)

regunder

Number of endangered and undergoal chunks (mark for removal excluded, in png shows chregdanger and chregunder using two colors)

challdanger

Number of endangered chunks (mark for removal included)

challunder

Number of undergoal chunks (mark for removal included)

allunder

Number of endangered and undergoal chunks (mark for removal included, in png shows challdanger and challunder using two colors)

bytesread

Average number of bytes read per second by all clients

byteswrite

Average number of bytes written per second by all clients

fsync

Number of fsync operations

lock

Number of lock operations

snapshot

Number of snapshot operations

truncate

Number of truncate operations

getxattr

Number of getxattr operations

setxattr

Number of setxattr operations

getfacl

Number of getfacl operations

setfacl

Number of setfacl operations

fcreate

Number of file create operations

meta

Number of extra metadata operations (sclass,trashretention,eattr etc.)

delay

(pro only) Master max delay in seconds

servers

Number of all registered chunk servers (both connected and disconnected)

dservers

Number of all disconnected chunk servers

mdservers

Number of disconnected chunk servers that are in maintenance mode

cservers

Number of all registered chunk servers (in csv equals to servers, in png shows servers, dservers and mdservers using three different colors)

udiff

Difference in space usage percent between the most and least used chunk server

## NOTES
Data sets delete and delete_stat in a properly working system should be roughly the same, but not always identical (in their CSV form), this stems from the fact that the delete set is calculated using the number of requests sent by the master, and the delete_stat set is calculated using the number of replies received from chunk servers, so local fluctuations may be observed (i.e. one minute has more sent requests - higher value in the delete set and the next minute has more answers - higher value in delete_stat set). But if one were to calculate the sum of differences between the two sets over time, this sum should never grow over a certain number.

However, if there is some kind of problem (with network communication and/or chunk server process(es)) and some chunk delete requests are stalled/go missing, then delete values may be constantly higher than the delete_stat values and the sum of differences between the two sets will be steadily growing over time.

Same goes for replicate(_stat), create(_stat), change(_stat) and split(_stat) data sets.

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmount(8), moosefs(7)


mfssupervisor

title: mfssupervisor(8)

text:
# mfssupervisor(8)

## NAME
mfssupervisor - tool for controlling the work of MooseFS master process

## SYNOPSIS
mfssupervisor [-xdfrc] [-l new leader ip] [-s mode] [-B local address] [-H master host name] [-P master supervising port]

mfssupervisor -v

mfssupervisor -h

## DESCRIPTION
mfssupervisor is the supervisor program of MooseFS. It can be used to force certain actions of MooseFS master(s), like saving metadata or changing leadership. When no action (options -r, -l or -s) is defined, the tool will just display info about the master(s) current state(s).

## OPTIONS
-v

print version information and exit

-h

print usage information and exit

-x

produce more verbose output

-d

(pro only) dry run (print info, but do not change anything)

-f

(pro only) force electing not synchronized follower; see NOTES

-r

(pro only) try to resolve the master states situation; usually selects one of the followers and sets its state to ELECT if no elects or leaders are present

-l

(pro only) try to change the role of the master with given IP to leader;

-c

(pro only) run configuration consistency check; if any inconsistencies are present, they will be reported via syslog

-s

force metadata store or (pro only) metadata check on given master group (pro version requires specifying a mode, possible values: L - LEADER only, F - FOLLOWERS only, A - all servers with CRC check, C - all servers CRC check only, no metadata is stored on disk)

-B

local address to use for master connections (default: *, i.e. default local address)

-H

use given host to find your master server(s) (default: mfsmaster)

-P

use given port to connect to your master server(s) (default: 9419)

## NOTES
Options -s,-r and -l are mutually exclusive

Option -f can be used only with option -r

Option -d can be used only with option -r or -l

Option -f shouldn't be used unless it is necessary in situations when not all master servers defined in DNS are connected (i.e. after a crash when one of the master machines is offline). In an environment where all master machines are present, the leader should be picked automatically.

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8)


mfsmetalogger

package: moosefs-metalogger

title: mfsmetalogger(8)

text:
# mfsmetalogger(8)

## NAME
mfsmetalogger - start, restart or stop MooseFS metalogger process

## SYNOPSIS
mfsmetalogger [-c CFGFILE] [-f] [-d] [-u] [-n] [-t LOCKTIMEOUT] [ACTION]

mfsmetalogger -v

mfsmetalogger -h

## DESCRIPTION
mfsmetalogger is the metadata replication server of MooseFS.

## OPTIONS
-v

print version information and exit

-h

print usage information and exit

-c CFGFILE

specify alternative path of configuration file (default is mfsmetalogger.cfg in system configuration directory)

-f

run in foreground, don't daemonize

-d

run with dangerous options (names: DANGEROUS_*)

-u

log undefined configuration values (when default is assumed)

-n

do not attempt to increase limit of core dump size

-t LOCKTIMEOUT

how long to wait for lockfile (in seconds; default is 60 seconds)

ACTION

tells metalogger to perform one of the following actions:

start

Start metalogger process if the process is not already running, otherwise display error message.

stop

Stop metalogger process if the process is running, otherwise display error message.

restart

(default action) If the metalogger process is running, restart it, if it's not running, start it.

reload

Send a signal to metalogger process to reload config files.

info

Send a signal to metalogger process to dump debug information file in working directory.

test

Displays "mfsmetalogger pid: PID" if the metalogger is running (and return 0) or "mfsmetalogger is not running" otherwise (and return 1).

kill

Send termination signal to metalogger process.

restore

Not implemented.

## FILES
mfsmetalogger.cfg

configuration file for MooseFS metalogger process; refer to mfsmetalogger.cfg(5) manual for details

.mfsmetalogger.lock

lock file of running MooseFS metalogger process (created in data directory)

changelog_ml.*.mfs

MooseFS filesystem metadata change logs (backup of master change log files, created in data directory)

metadata.ml.mfs.back

Latest copy of complete metadata.mfs.back file from MooseFS master (created in data directory)

.mfsmetalogger_info.txt

metalogger info file, created by sending the process INFO signal, with work parameters that can be used for debugging/support purposes (created in data directory)

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.

## SEE ALSO
mfsmaster(8), mfsmetalogger.cfg(5)


mfsnetdump

package: moosefs-netdump

title: mfsnetdump(8)

summary: dump network traffic as mfs packets

text:
# mfsnetdump(8)

## NAME
mfsnetdump - dump network traffic as mfs packets

## SYNOPSIS
mfsnetdump [-r PCAP_FILE] [-i INTERFACE] [-p PORT_RANGE] [-f PCAP_FILTER] [-c PCOUNT] [-s MBYTES] [-e COMMANDS] [-o COMMANDS] [-x] [-y] [-n]

## DESCRIPTION
mfsnetdump is an internal diagnostic tool similar to tcpdump, but specialized for MooseFS.

## OPTIONS
-r

specify PCAP file to read packets from

-i

dump packets using given network interface

-p

show only packets from given port range (default range is 9419-9422, so by default only MFS packets are shown)

-f

define pcap filter to filter packets

-c

dump only PCOUNT packets and exit

-s

dump only first MBYTES bytes of each packet

-e

do not display given commands

-o

show only given commands

-x

do not display mfs maintenance commands (such as CSTOMA_SPACE or CLTOMA_FUSE_TIME_SYNC)

-y

do not display open/close connections packets

-n

show ANTOAN_NOP command (disabled by default)

## REPORTING BUGS
Report bugs to <bugs@moosefs.com>.

## COPYRIGHT
Copyright (C) 2026 Jakub Kruszona-Zawadzki, Saglabs SA

This file is part of MooseFS.

MooseFS is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2 (only).

MooseFS is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <https://www.gnu.org/licenses/>.


mopidyctl

package: mopidy

title: mopidyctl(8)

text:
# mopidyctl(8)

## NAME
mopidyctl - manage the Mopidy music server system service

## SYNOPSIS
mopidyctl [any mopidy(1) option]

## DESCRIPTION
The mopidyctl command runs mopidy subcommands in the same environment as the Mopidy system service is running in. That is, as the same user and with the same config as the Mopidy system service is using.

## OPTIONS
mopidyctl(8) takes the same options as mopidy(1).

## SEE ALSO
mopidy(1)

## COPYRIGHT
2014, Stein Magnus Jodal and contributors


mosquitto

package: mosquitto

title: mosquitto(8)

summary: an MQTT broker

text:
# mosquitto(8)

## NAME
mosquitto - an MQTT broker

## SYNOPSIS
mosquitto [-c config file] [-d | --daemon] [-p port number] [-v]

## DESCRIPTION
mosquitto is a broker for the MQTT protocol version 5.0/3.1.1/3.1.

## OPTIONS
-c, --config-file

Load configuration from a file. If not given, then the broker will listen on port 1883 bound to the loopback interface, and the default values as described in mosquitto.conf(5) are used.

Important

See the -p option for a description of changes in behaviour from 1.6.x to 2.0.

-d, --daemon

Run mosquitto in the background as a daemon. All other behaviour remains the same.

-p, --port

Listen on the port specified. May be specified up to 10 times to open multiple sockets listening on different ports.

Important

In version 1.6.x and earlier, the listener defined by -p (or the default port of 1883) would be bound to all interfaces and so be accessible from any network. It could also be used in combination with -c. From version 2.0 onwards, the listeners defined with -p are bound to the loopback interface only, and so can only be connected to from the local machine. If both -p is used and a listener is defined in a configuration file, then the -p options are IGNORED.

-v, --verbose

Use verbose logging. This is equivalent to setting log_type to all in the configuration file. This overrides and logging options given in the configuration file.

## CONFIGURATION
The broker can be configured using a configuration file as described in mosquitto.conf(5) and this is the main point of information for mosquitto. The files required for SSL/TLS support are described in mosquitto-tls(7).

## PLATFORM LIMITATIONS
Some versions of Windows have limitations on the number of concurrent connections due to the Windows API being used. In modern versions of Windows, e.g. Windows 10 or Windows Server 2019, this is approximately 8192 connections. In earlier versions of Windows, this limit is 2048 connections.

## MQTT SUPPORT
Mosquitto supports MQTT v5.0, v3.1.1, and v3.1.

### MQTT v5.0
Mosquitto provides full MQTT v5.0 support, but some features are not used directly. The following sections describe the new features and explain where Mosquitto does not make use of a feature.

Features

Enhanced authentication

Basic MQTT authentication uses username/password checks. Enhanced authentication allows different authentication schemes to be integrated into MQTT, and even those schemes with multiple step processes. Clients request a particular type of authentication and if the broker is configured for that scheme the authentication continues. Mosquitto supports enhanced authentication through plugins.

Error handling

Most MQTT packets now have the concept of a reason code which indicates success or failure, and what the failure was. Mosquitto provides full support for reason codes, but does not make use of the reason string feature which can be used to provide a human readable error string to explain the reason code.

Flow control

The number of "in flight" messages for QoS 1 and QoS 2 can be controlled by both the client and the broker.

Request / response

MQTT v5.0 adds a request/response pattern that allows a client to publish a message and instruct the subscribers of that message where to publish a response.

Server redirection

Server redirection is the concept of telling a client to connect to a different MQTT broker, either on CONNECT or with a broker initiated DISCONNECT. Mosquitto does not currently make use of this feature.

Shared subscriptions

When multiple clients subscribe to the same shared subscription, only one client out of the group will receive each message which allows for distributing work loads.

Packet properties

MQTT v5.0 allows properties to be added to packets to control certain behaviour. Unless noted, Mosquitto support the properties listed below.

CONNECT

•Authentication data

•Authentication method

•Maximum packet size

•Receive maximum

•Request problem information - supported but not used

•Request response information - supported but not used

•Session expiry interval

•Topic alias maximum

•User property

Last will and testament

•Content type

•Correlation data

•Message expiry interval

•Payload format indicator

•Response topic

•User property

•Will delay interval

CONNACK

•Assigned client identifier

•Authentication data

•Authentication method

•Maximum packet size

•Maximum qos

•Reason string - supported but not used

•Receive maximum

•Response information - supported but not used

•Retain available

•Server keep alive

•Server reference - supported but not used

•Session expiry interval

•Shared subscription available

•Subscription identifiers available

•Topic alias maximum

•User property

•Wildcard subscription available

PUBLISH

•Content type

•Correlation data

•Message expiry interval

•Payload format indicator

•Response topic

•Subscription identifier

•Topic alias

•User property

PUBACK / PUBREC / PUBREL / PUBCOMP / SUBACK / SUBSCRIBE / SUBACK

•Reason string - supported but not used

•User property

SUBSCRIBE

•Subscription identifier

•User property

DISCONNECT

•Reason string - supported but not used

•Server reference - supported but not used

•Session expiry interval

•User property

AUTH

•Authentication method

•Authentication data

•Reason string - supported but not used

•User property

### MQTT v3.1.1
Mosquitto provides full MQTT v3.1.1 support.

### MQTT v3.1
Mosquitto provides full MQTT v3.1 support.

### MQTT v3
MQTT v3 is an obsolete version of the protocol that does not support username/password authentication and used the clean start flag in the CONNECT packet which applied only to the start of a session. An MQTT v3 client will be able to successfully connect to a Mosquitto instance that does not require authentication.

## BROKER STATUS
Clients can find information about the broker by subscribing to topics in the $SYS hierarchy as follows. Topics marked as static are only sent once per client on subscription. All other topics are updated every sys_interval seconds. If sys_interval is 0, then updates are not sent.

Note that if you are using a command line client to interact with the $SYS topics and your shell interprets $ as an environment variable, you need to place the topic in single quotes '$SYS/...' or to escape the dollar symbol: \$SYS/... otherwise the $SYS will be treated as an environment variable.

$SYS/broker/bytes/received

The total number of bytes received since the broker started.

$SYS/broker/bytes/sent

The total number of bytes sent since the broker started.

$SYS/broker/clients/connected, $SYS/broker/clients/active (deprecated)

The number of currently connected clients.

$SYS/broker/clients/expired

The number of disconnected persistent clients that have been expired and removed through the persistent_client_expiration option.

$SYS/broker/clients/disconnected, $SYS/broker/clients/inactive (deprecated)

The total number of persistent clients (with clean session disabled) that are registered at the broker but are currently disconnected.

$SYS/broker/clients/maximum

The maximum number of clients that have been connected to the broker at the same time.

$SYS/broker/clients/total

The total number of active and inactive clients currently connected and registered on the broker.

$SYS/broker/connection/#

When bridges are configured to/from the broker, common practice is to provide a status topic that indicates the state of the connection. This is provided within $SYS/broker/connection/ by default. If the value of the topic is 1 the connection is active, if 0 then it is not active. See the Bridges section below for more information on bridges.

$SYS/broker/heap/current size

The current size of the heap memory in use by mosquitto. Note that this topic may be unavailable depending on compile time options.

$SYS/broker/heap/maximum size

The largest amount of heap memory used by mosquitto. Note that this topic may be unavailable depending on compile time options.

$SYS/broker/load/connections/+

The moving average of the number of CONNECT packets received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of connections received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/bytes/received/+

The moving average of the number of bytes received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/bytes/sent/+

The moving average of the number of bytes sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of bytes sent in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/messages/received/+

The moving average of the number of all types of MQTT messages received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/messages/sent/+

The moving average of the number of all types of MQTT messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages send in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/publish/dropped/+

The moving average of the number of publish messages dropped by the broker over different time intervals. This shows the rate at which durable clients that are disconnected are losing messages. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of messages dropped in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/publish/received/+

The moving average of the number of publish messages received by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages received in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/publish/sent/+

The moving average of the number of publish messages sent by the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of publish messages sent in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/load/sockets/+

The moving average of the number of socket connections opened to the broker over different time intervals. The final "+" of the hierarchy can be 1min, 5min or 15min. The value returned represents the number of socket connections in 1 minute, averaged over 1, 5 or 15 minutes.

$SYS/broker/messages/inflight

The number of messages with QoS>0 that are awaiting acknowledgments.

$SYS/broker/messages/received

The total number of messages of any type received since the broker started.

$SYS/broker/messages/sent

The total number of messages of any type sent since the broker started.

$SYS/broker/publish/messages/dropped

The total number of publish messages that have been dropped due to inflight/queuing limits. See the max_inflight_messages and max_queued_messages options in mosquitto.conf(5) for more information.

$SYS/broker/publish/messages/received

The total number of PUBLISH messages received since the broker started.

$SYS/broker/publish/messages/sent

The total number of PUBLISH messages sent since the broker started.

$SYS/broker/retained messages/count

The total number of retained messages active on the broker.

$SYS/broker/store/messages/count, $SYS/broker/messages/stored (deprecated)

The number of messages currently held in the message store. This includes retained messages and messages queued for durable clients.

$SYS/broker/store/messages/bytes

The number of bytes currently held by message payloads in the message store. This includes retained messages and messages queued for durable clients.

$SYS/broker/subscriptions/count

The total number of subscriptions active on the broker.

$SYS/broker/version

The version of the broker. Static.

## WILDCARD TOPIC SUBSCRIPTIONS
In addition to allowing clients to subscribe to specific topics, mosquitto also allows the use of two wildcards in subscriptions. + is the wildcard used to match a single level of hierarchy. For example, for a topic of "a/b/c/d", the following example subscriptions will match:

•a/b/c/d

•+/b/c/d

•a/+/c/d

•a/+/+/d

•+/+/+/+

The following subscriptions will not match:

•a/b/c

•b/+/c/d

•+/+/+

The second wildcard is # and is used to match all subsequent levels of hierarchy. With a topic of "a/b/c/d", the following example subscriptions will match:

•a/b/c/d

•#

•a/#

•a/b/#

•a/b/c/#

•+/b/c/#

The $SYS hierarchy does not match a subscription of "#". If you want to observe the entire $SYS hierarchy, subscribe to $SYS/#.

Note that the wildcards must be only ever used on their own, so a subscription of "a/b+/c" is not valid use of a wildcard. The # wildcard must only ever be used as the final character of a subscription.

## BRIDGES
Multiple brokers can be connected together with the bridging functionality. This is useful where it is desirable to share information between locations, but where not all of the information needs to be shared. An example could be where a number of users are running a broker to help record power usage and for a number of other reasons. The power usage could be shared through bridging all of the user brokers to a common broker, allowing the power usage of all users to be collected and compared. The other information would remain local to each broker.

For information on configuring bridges, see mosquitto.conf(5).

## SIGNALS
On POSIX systems Mosquitto can receive signals and act on them as described below. To send signals, use e.g. kill -HUP <process id of mosquitto>

SIGHUP

Upon receiving the SIGHUP signal, mosquitto will attempt to reload configuration file data, assuming that the -c argument was provided when mosquitto was started. Not all configuration parameters can be reloaded without restarting. See mosquitto.conf(5) for details. If TLS certificates are in use, then mosquitto will also reload certificate on receiving a SIGHUP.

SIGUSR1

Upon receiving the SIGUSR1 signal, mosquitto will write the persistence database to disk. This signal is only acted upon if persistence is enabled.

SIGUSR2

The SIGUSR2 signal causes mosquitto to print out the current subscription tree, along with information about where retained messages exist. This is intended as a testing feature only and may be removed at any time.

## FILES
/etc/mosquitto/mosquitto.conf

Configuration file. See mosquitto.conf(5).

/var/lib/mosquitto/mosquitto.db

Persistent message data storage location if persist enabled.

/etc/hosts.allow, /etc/hosts.deny

Host access control via tcp-wrappers as described in hosts_access(5).

## BUGS
mosquitto bug information can be found at https://github.com/eclipse/mosquitto/issues

## SEE ALSO
mqtt(7), mosquitto-tls(7), mosquitto.conf(5), hosts_access(5), mosquitto_ctrl(1), mosquitto_passwd(1), mosquitto_pub(1), mosquitto_rr(1), mosquitto_sub(1), libmosquitto(3)

## THANKS
Thanks to Andy Stanford-Clark for being one of the people who came up with MQTT in the first place. Thanks to Andy and Nicholas O'Leary for providing clarifications of the protocol.

Thanks also to everybody at the Ubuntu UK Podcast and Linux Outlaws for organising OggCamp, where Andy gave a talk that inspired mosquitto.

## AUTHOR
Roger Light <roger@atchoo.org>