Ubuntu Manpage: mbuffer - measuring buffer

Provided by: mbuffer_20171011-1ubuntu1_amd64

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

-s <size>
Use blocks of size bytes for buffer (default pagesize of system).

-m <size>
Use a total of size bytes for buffer (default 2MB) - 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

--direct
Use O_DIRECT to open file descriptors. This option is not available on all systems.
It tells the OS to bypass the page cache to improve performance when reading and
writing. On Solaris this is an auto-magic option that is enabled if it is supported
for the relevant file. Be aware that this option might lead to read/write failures,
if the buffer isn't properly aligned for direct I/O. Additionally, open might fail
with EINVAL (i.e. invalid argument) if the named file does not support O_DIRECT.

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

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

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