mfsbdev(8)

💅 mfsbdev — MooseFS block device daemon/management tool

Okay bestie, buckle up. This is mfsbdev from the MooseFS fam (it's the mfsbdev(8) page, section 8, system admin tools, iykyk), and it's literally the tool you use to ✨manage block devices✨. She's giving main character energy but with a very specific little caveat, so listen up:

Linux ONLY. Not Linux-adjacent, not "probably works on BSD", not "try it on your Mac". Linux. And the kernel module nbd must be loaded or this whole thing just does not work. No cap. 💀

---

✨ 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 🦋

So basically this tool manages block devices. That's the whole vibe. But — and I need you to hear me on this — it works on Linux ONLY, and the kernel module nbd must be loaded for it to work properly. That's the price of admission, bestie. 🎀

👑 COMMANDS 👑

• start — starts the daemon. And here's the tea: at this point the daemon is literally just sitting there listening on a socket. That's it. All the other commands use that socket to talk to the daemon. If you don't pass -l to pick a socket, the default one gets used: /dev/mfs/nbdsock.
• stop — stops the daemon. Bye girl. 👋
• map — maps a file on mfs so it can be used as a block device.
• unmap — removes a mapping.
• list — lists the current mappings.
• resize — changes the size of a block device. 🫶 Psst: requires kernel version 4.18 or higher.

---

💖 OPTIONS 💖

• -H — master host; default is 'mfsmaster'.
• -P — master port; default is '9421'.
• -S — master path (a subfolder in MFS that gets used as the root for all the block device mappings); default is '/'.
• -p — master password; mutually exclusive with the -x option; and if you supply neither -p nor -x, the tool tries to connect without a password.
• -x — path to a file containing the master password; mutually exclusive with the -p option; if neither -p nor -x are supplied, the tool tries to connect without a password.
• -l — path to the communication socket; default is /dev/mfs/nbdsock.
• -f — path to the mfs file used to map the block device.
• -d — path to the network block device ('/dev/nbdX'); by default (so, if you don't supply this parameter), the first available device is used with the map command.
• -n — name of the 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 the block device as readonly (and this 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. She's persistent fr fr.
• -t — forces the list command to display information in a format that's ready to use with the map command (the m parameter) or the unmap command (the u parameter) or with the MooseFS mfsbdev.cfg file format (the i parameter).
• -i (start) — use the config file supplied in the parameter to start initial block devices; for the formatting of the config, see mfsbdev.cfg(5).
• -o — additional params, mfsmount-style. Many params can be defined, separated by comma:

🌸 the -o sub-params 🌸

• 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 an I/O error is returned (default: 30).
• mfstimeout=N — define maximum timeout in seconds before an I/O error is returned (default: 0 - which means no timeout).
• mfslogretry=N — define minimal retry counter on which the system will start logging 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 the master instead of the 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 the kernel gives up (default: 1800).

---

🎀 FILES 🎀

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

---

🌈 EXAMPLES 🌈

Starting the nbd daemon with all the default options (masterhost = mfsmaster, masterport = 9421, linksocket = /dev/mfs/nbdsock, authentication without password):

mfsbdev start

Connecting somewhere specific with a password file: this one starts an nbd daemon that will connect to master mfsmaster.my.domain on port 9521 using the password read from file /etc/mfs/mastersecret:

mfsbdev start -H mfsmaster.my.domain -P 9521 -x /etc/mfs/mastersecret

Stopping a daemon that's using a custom socket: this stops the nbd daemon using unix socket /tmp/mynbdinstance for communication:

mfsbdev stop -l /tmp/mynbdinstance

Adding a mapping: adds a mapping to the daemon using the default socket (/dev/mfs/nbdsock) for communication. 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 the block device will have size of 2TiB:

mfsbdev map -f devices/mybdev1.bin -s 2Ti -n mytestvm

Removing a mapping by name: removes the mapping that has a link named mytestvm (it uses link /dev/mfs/mytestvm):

mfsbdev unmap -n mytestvm

---

🙈 REPORTING BUGS 🙈

Found a bug? Don't be shy, tell the devs: <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)

---

And that's the whole page bestie!! 💖 This was MooseFS version 4.59.2-1, dated May 2026 — go forth and map some block devices, you absolute icon 🫶✨