Provided by: mbuffer_20210328+ds2-1_amd64 bug

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, and offers more options than the standard buffer.

OPTIONS

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

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

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

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

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

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

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

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

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

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

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

DEFAULT VALUES

       The default values for following  options  can  be  set  as  key  =  value  pairs  in  the
       ~/.mbuffer.rc file:
       blocksize: block size (option -s)
       timeout: watchdog timeout (option -W)
       totalmem: total buffer size (option -m)
       maxreadspeed: maximum read speed (option -r)
       maxwritespeed: maximum write speed (option -R)
       startwrite: threshold for start writing (option -P)
       startread: threshold for start reading (option -p)
       pause: pause after writing a block (option -u)
       numblocks: number of blocks in buffer (option -b)
       memlock: lock buffer in memory (option -L)
       showstatus: print transfer status on console (option -q)
       logstatus: write transfer status to logfile (option -Q)
       tcpbuffer: TCP buffer size (option --tcpbuffer)

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.

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.

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)