Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
mbuffer(1)			console	utility			    mbuffer(1)

       mbuffer - measuring buffer

       mbuffer [options]

       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.

       -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

       -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

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

       -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

       -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 de-
	      crease 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

       -q     quiet - do not display the status	on the standard	error output

       -Q     quiet - do not log the status in the log file

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

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

	      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  sec-
	      ond  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

       -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

       --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 pars-
	      ing all options. To avoid	that the watchdog will trigger	during
	      network initialization, put the option -W	after -I and -O.

       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)

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


       To run this program with	the default options just type:


       Using  mbuffer  to do a backup with tar to the default tape device. Op-
       tions 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 -

       mbuffer	return	0  upon	success. Any kind of failure will yield	a non-
       zero exit code.

       Thomas Maier-Komor <>

       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


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


Thomas Maier-Komor		   20200505			    mbuffer(1)


Want to link to this manual page? Use this URL:

home | help