mbuffer(1)                      console utility                     mbuffer(1)

NAME
       mbuffer - measuring buffer

SYNTAX
       mbuffer [options]

DESCRIPTION
       mbuffer buffers I/O operations and displays the throughput rate. It is
       multi-threaded, supports network connections, multiple output targets,
       and many more options than the standard buffer command.

OPTIONS
       -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).

       -d     Use block-size of device for output (needed for some devices,
              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).

       -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).

       -i <filename>
              Use filename as input instead of the standard input (needs to be
              given for multi volume support). If filename is -, input is read
              from standard input.

       -o <filename>
              Use filename as output instead of the standard output (needs to
              be given for multi volume support, will enable use of sendfile
              if available). If filename is -, output is written to standard
              output. The option -o can be passed multiple times to specify
              multiple outputs.

       --append
              Open next output file given via option -o in append mode.

       --truncate
              Truncate next output file given via option -o when opening it.

       -I <port>
              Use network port port as input instead of the standard input. If
              given a hostname and a port in the form hostname:port, only the
              given host is allowed to connect.

       -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.

       -n <num>
              num volumes in input device (requires use of option -i for input
              device specification, 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).

       -T <file>
              As -t but use file as buffer.

       -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).

       -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.

       -f     Overwrite output file if it exists already.

       -a <time>
              The device used is an autoloader which takes time seconds to
              load a new tape.

       -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.

       -v <level>
              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.

       -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.

       -e     Stop processing on any kind of error.

       -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 this instance. 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.

       -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.

       -4     Force IPv4 mode for the following network I/O options on command
              line.

       -6     Force IPv6 mode for the following network I/O options on command
              line.

       -0     Choose IPv4/IPv6 mode on demand.

       --no-direct
              Omit use of O_DIRECT - e.g. to enable compression on btrfs.

       --tcpbuffer
              Size for TCP buffer in bytes. Size can be set with a trailing
              character (b and B for Byte, k for kByte, M for MByte, or G for
              Gigabyte).

       --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.

       --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.

       --direct
              Use direct I/O for temporary file buffer.

       -h, --help
              Output help information and exit.

       -V, --version
              Output version information and exit.

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.


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.
       MBUFFER_VOL volume id info (set for autoloader command).
       MBUFFER_NUMIN number of bytes read (set for autoloader command).
       MBUFFER_NUMOUT number of bytes written (set for autoloader command).


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 returns 0 upon success. Any kind of failure will yield a non-
       zero exit code.

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).

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)

Thomas Maier-Komor                 R20240107                        mbuffer(1)