mbuffer(1) console utility mbuffer(1)NAMEmbuffer - measuring buffer
SYNTAXmbuffer [options]
DESCRIPTIONmbuffer 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 sys‐
tem).
-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 buf‐
fers)
-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 perfor‐
mance 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 per‐
formance, 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 termi‐
nal (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 syn‐
chronous 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 avail‐
able 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.
-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 weather 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.
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/local/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 -
EXITCODEmbuffer 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 ALSObuffer(1)Thomas Maier-Komor 20151002 mbuffer(1)
