mbuffer(1)

📦
this version · 11 versions
, in epel 9, opensuse-leap 16.0

💖 mbuffer(1) — the measuring buffer, bestie ✨

okay so first things first: this is the manual page for mbuffer, a console utility. That's the whole vibe. She's a buffer, she measures things, she's iconic. Let's get into it 🫶

✨ NAME ✨

mbuffer — measuring buffer. that's it, that's her. no cap 💅

🎀 SYNTAX 🎀

mbuffer [options]

literally just that. options go in, throughput comes out 🌸

🦋 DESCRIPTION 🦋

mbuffer buffers I/O operations and displays the throughput rate. She's multi-threaded (yes ma'am, threads), she supports network connections, multiple output targets, and honestly so many more options than the standard buffer command that it's not even a competition 🏆

💅 OPTIONS 💅

  • -i <filename> — use filename as input instead of the standard input (and yes, it needs to be given for multi volume support, don't skip it). If filename is -, input is read from standard input. classic.
  • -I <port> — use network port port as input instead of the standard input. If you give it a hostname and a port in the form hostname:port, the first interface with the IP of hostname will be used.
  • -o <filename> — use filename as output instead of the standard output (needs to be given for multi volume support, and it will enable use of sendfile if available, slay). If filename is -, output is written to standard output. And bestie, -o can be passed multiple times to specify multiple outputs 👑
  • -O <hostname:port> — write output to hostname:port instead of the standard output (will enable use of sendfile if available). This option can be used multiple times to send data to multiple machines. it's giving distribution era 🌈
  • -b <num> — use num blocks for buffer (default is determined on startup).
  • -s <size> — use blocks of size bytes for buffer (default is determined on startup).
  • -m <size> — use a total of size bytes for buffer (default 2% of available memory). size can be set with a trailing character: b and B for Byte, k for kByte, M for MByte, G for Gigabyte, and with % for a percentage of total physical memory 🍓
  • -L — lock buffer in memory. this option is not available for file-based buffers and requires mbuffer to be set-UID root (use with care, bestie, like actually please be careful 🙈).
  • -n <num> — num volumes in input device (requires use of option -i for input device specification, and pass 0 as argument if mbuffer should prompt for every new volume).
  • -t — use a memory-mapped temporary file as buffer (use with huge buffers, she can handle it).
  • -T <file> — as -t but use file instead.
  • -d — use block-size of device for output (needed for some devices, but lowkey slows output down).
  • -D <size> — assume an output volume of size bytes (default infinite) after which a volume change will be initiated. Small values are useful for the timely testing of multi-volume runs; accurate values if your device doesn't properly signal end of media. Size can be set with a trailing character (b and B for Byte, k for kByte, M for MByte, or G for Gigabyte). note: no % here, don't get cute 💀
  • -P <num> — start writing after the buffer has been filled to num% (default 0 — start at once).
  • -p <num> — start reading after the buffer has dropped below fill-ratio of num% (default 100 — start at once).
  • -l <file> — log messages to file instead of standard error output.
  • -u <num> — pause num microseconds after each write. might increase performance on some drives with very low performance (< 1 MB/sec). trust the process 🧚
  • -r <rate> — set the maximum read rate to rate. rate can be given in either Bytes, kBytes, MBytes, or GBytes per second. To do so, use an appropriate suffix (i.e. k,M,G). This option is useful if you have a tape that is capable of transferring data faster than the host can handle it. In this case you can use this option to limit the transfer rate and keep the tape running. Be aware that this is both good for your tape drive, and enhances overall performance, by avoiding tape screwing. 🔥
  • -R <rate> — same as above only for setting the transfer limit for the writer.
  • -A <cmd> — the device used is an autoloader which uses cmd to load the next volume. Pass </bin/false> as an autoload command to suppress the warning message that appears when run without controlling terminal (e.g. via cron). Like this the autoload will fail and mbuffer will terminate with an error message when reaching the end of the tape.
  • -a <time> — the device used is an autoloader which takes time seconds to load a new tape.
  • -f — overwrite output file if it exists already.
  • -c — write with synchronous data integrity support. This option forces all writes to complete before continuing. This enables errors to be reported earlier and more precisely, but might decrease performance. Especially systems with high level of data integrity support suffer a huge performance hit. Others might seem to be unaffected, but just neglect support for full synchronous data integrity. read that twice, bestie 😭
  • -v <num> — set verbose level to num. Valid values are 0..6 (0 = none, 1 = errors, 2 = warnings, 4 = information messages, 5 = debugging messages, 6 = I/O debugging). Higher values include lower values messages.
  • -q — quiet — do not display the status on the standard error output.
  • -Q — quiet — do not log the status in the log file.
  • --append — open next output file given via option -o in append mode.
  • --truncate — truncate next output file given via option -o when opening it.
  • --tapeaware — keep writing to the very end of the tape. LTO drives tell the OS as they approach the end of the tape, which Linux passes on to userspace by returning a 'no space left' error on every second write operation. Normally the first of these errors is treated as the end of the tape and the next volume will be called for, however with this option, writes will continue until two in a row fail with 'no space left', indicating the real end of the tape. This will allow a little extra data to fit on each tape. squeezing every last drop, we love to see it 💜
  • --tcptimeo <time> — set the TCP timeout threshold. The default value is 10s. Arguments without dimension are interpreted as usec. Argument dimensions can be us, ms, s or sec, m or min, h.
  • -6 — force IPv6 mode for the following network I/O options on command line.
  • -4 — force IPv4 mode for the following network I/O options on command line.
  • -0 — choose IPv4/IPv6 mode on demand.
  • -h, --help — output help information and exit.
  • -H, --md5 — generate a MD5 hash of transferred data.
  • --hash <alg> — use algorithm alg, if alg is 'list' possible algorithms are listed.
  • --pid — print PID of current process. This option can help you to figure out which instance of mbuffer to kill, if multiple are running and one is hanging due to a network issue. Printing of the PID can also be triggered by adding "printpid = 1" to your .mbuffer.rc file. very main character of you to check 🎀
  • -V, --version — output version information and exit.
  • -W <timeout> — activates a watchdog that gets triggered every timeout seconds and checks whether I/O activity has stalled. If either channel has stalled for a complete period, the watchdog writes an error message and terminates mbuffer via SIGINT. Be aware that the watchdog is unaware of tape-change activities. So choose the watchdog timeout greater that the worst-case tape-change time. The watchdog is activated with parsing option -W or after parsing all options. To avoid that the watchdog will trigger during network initialization, put the option -W after -I and -O. 🐕 ward energy

🌸 DEFAULT VALUES 🌸

The default values for most options can be set as key = value pairs in one or more configuration files. See the sample mbuffer.rc files for available options and their default values. Configuration files are read in following sequence listed below:

  • /etc/mbuffer.rc
  • $PREFIX/etc/mbuffer.rc
  • $HOME/.mbuffer.rc
  • $MBUFFERRC

The default values given in the files above are overriden by options passed on the command-line. command line stays winning, periodt 👑

🌈 ENVIRONMENT VARIABLES 🌈

If TMPDIR is set, mbuffer allocates storage for file-based buffers in this directory. If TMPDIR is unset, /var/tmp will be used.

MBUFFERRC can be used to set a custom mbuffer.rc config file.

🦋 FILES 🦋

  • $PREFIX/bin/mbuffer
  • /var/tmp/mbuffer-*
  • ~/.mbuffer.rc

⭐ EXAMPLES ⭐

To run this program with the default options just type:

mbuffer

Using mbuffer to do a backup with tar to the default tape device. Options for this example: memory-mapped temporary file with a size of 10 Megabytes, start after 80% of the buffer have been filled.

tar cf - mydirectory | gzip | mbuffer -t -m 10M -P 80 -f -o $TAPE

Using mbuffer with 3 tapes for input and extracting the contents in the current work directory:

mbuffer -n 3 -i $TAPE | gzip -dc | tar xf -

Using mbuffer to write to multiple tape volumes:

tar cf - /usr | mbuffer -f -o $TAPE

Write to multiple tapes and erase every tape before writing:

tar cf - /usr | mbuffer -A "echo next tape; read a < /dev/tty; mt erase
$TAPE" -f -o $TAPE

Making a backup via network:

tape server: mbuffer -I 8000 -f -o $TAPE

backup client: tar zcf - /home | mbuffer -O tapeserver:8000

Distributing a directory tree to multiple machines:

master: tar cf - /tree_to_clone | mbuffer -O clone0:8000 -O clone1:8000

clones: mbuffer -I master:8000 | tar xf -

💀 EXITCODE 💀

mbuffer return 0 upon success. Any kind of failure will yield a non-zero exit code. (yes the original says "return", we're keeping it, it's her grammar and we respect it 🫶)

👑 AUTHORS 👑

Thomas Maier-Komor <thomas@maier-komor.de>

💖 DONATIONS 💖

If you like this software, and use it for production purposes in your company, please consider making a donation to support this work. You can donate directly via PayPal to the author's e-mail address (thomas@maier-komor.de). support the dev, bestie, it's the least we can do 🎀

🧚 HOMEPAGE 🧚

http://www.maier-komor.de/mbuffer.html

🔥 LICENSE 🔥

This software is published under GNU General Public License V3. See file LICENSE for details.

🍓 SEE ALSO 🍓

buffer(1)

okay that's the whole page!! also the tiny fine print at the bottom had the author Thomas Maier-Komor, version R20231216, and mbuffer(1) on it — so consider that your cute little sign-off: written by Thomas Maier-Komor, dropped as version R20231216, filed under mbuffer(1). love that for us 💜✨

📦 where this page comes from