1mbuffer(1)                      console utility                     mbuffer(1)
2
3
4

NAME

6       mbuffer - measuring buffer
7

SYNTAX

9       mbuffer [options]
10

DESCRIPTION

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

OPTIONS

17       -i <filename>
18              Use filename as input instead of the standard input (needs to be
19              given for multi volume support). If filename is -, input is read
20              from standard input.
21
22       -I <port>
23              Use network port port as input instead of the standard input. If
24              given a hostname and a port in the form hostname:port, the first
25              interface with the IP of hostname will be used.
26
27       -o <filename>
28              Use  filename as output instead of the standard output (needs to
29              be given for multi volume support, will enable use  of  sendfile
30              if  available).  If filename is -, output is written to standard
31              output. The option -o can be passed multiple  times  to  specify
32              multiple outputs.
33
34       -O <hostname:port>
35              Write  output  to  hostname:port  instead of the standard output
36              (will enable use of sendfile if available). This option  can  be
37              used multiple times to send data to multiple machines.
38
39       -b <num>
40              Use num blocks for buffer (default is determined on startup).
41
42       -s <size>
43              Use  blocks  of  size bytes for buffer (default is determined on
44              startup).
45
46       -m <size>
47              Use a total of size bytes for buffer (default  2%  of  available
48              memory) - size can be set with a trailing character (b and B for
49              Byte, k for kByte, M for MByte, G for Gigabyte, and with % for a
50              percentage of total physical memory).
51
52       -L     Lock  buffer  in memory - this option is not available for file-
53              based buffers and requires mbuffer to be set-UID root (use  with
54              care).
55
56       -n <num>
57              num volumes in input device (requires use of option -i for input
58              device specification, pass  0  as  argument  if  mbuffer  should
59              prompt for every new volume)
60
61       -t     use a memory-mapped temporary file as buffer (use with huge buf‐
62              fers)
63
64       -T <file>
65              as -t but use file instead
66
67       -d     use block-size of device for output (needed  for  some  devices,
68              slows output down)
69
70       -D <size>
71              assume  an  output volume of size bytes (default infinite) after
72              which a volume change will be initiated. Small values are useful
73              for  the timely testing of multi-volume runs; accurate values if
74              your device doesn't properly signal end of media.  Size  can  be
75              set  with a trailing character (b and B for Byte, k for kByte, M
76              for MByte, or G for Gigabyte)
77
78       -P <num>
79              start writing after the buffer has been filled to num%  (default
80              0 - start at once)
81
82       -p <num>
83              start  reading  after the buffer has dropped below fill-ratio of
84              num% (default 100 - start at once)
85
86       -l <file>
87              log messages to file instead of standard error output
88
89       -u <num>
90              pause num microseconds after each write - might increase perfor‐
91              mance on some drives with very low performance (< 1 MB/sec)
92
93       -r <rate>
94              Set  the  maximum read rate to rate. rate can be given in either
95              Bytes, kBytes, MBytes, or GBytes per second. To do  so,  use  an
96              appropriate  suffix  (i.e.  k,M,G). This option is useful if you
97              have a tape that is capable of transferring data faster than the
98              host  can  handle  it.  In  this case you can use this option to
99              limit the transfer rate and keep the tape running. Be aware that
100              this is both good for your tape drive, and enhances overall per‐
101              formance, by avoiding tape screwing.
102
103       -R <rate>
104              Same as above only  for  setting  the  transfer  limit  for  the
105              writer.
106
107       -A <cmd>
108              the device used is an autoloader which uses cmd to load the next
109              volume. Pass </bin/false> as an autoload command to suppress the
110              warning message that appears when run without controlling termi‐
111              nal (e.g.  via cron). Like  this  the  autoload  will  fail  and
112              mbuffer  will  terminate with an error message when reaching the
113              end of the tape.
114
115       -a <time>
116              the device used is an autoloader which  takes  time  seconds  to
117              load a new tape
118
119       -f     overwrite output file if it exists already
120
121       -c     write  with  synchronous  data  integrity  support - This option
122              forces all writes to complete before  continuing.  This  enables
123              errors  to be reported earlier and more precisely, but might de‐
124              crease performance. Especially systems with high level  of  data
125              integrity  support  suffer  a huge performance hit. Others might
126              seem to be unaffected, but just neglect support  for  full  syn‐
127              chronous data integrity.
128
129       -v <num>
130              set  verbose  level to num. Valid values are 0..6 (0 = none, 1 =
131              errors, 2 = warnings, 4 = information messages,  5  =  debugging
132              messages, 6 = I/O debugging). Higher values include lower values
133              messages.
134
135       -q     quiet - do not display the status on the standard error output
136
137       -Q     quiet - do not log the status in the log file
138
139       --append
140              Open next output file given via option -o in append mode.
141
142       --truncate
143              Truncate next output file given via option -o when opening it.
144
145       --tapeaware
146              Keep writing to the very end of the tape.  LTO drives  tell  the
147              OS  as  they approach the end of the tape, which Linux passes on
148              to userspace by returning a 'no space left' error on every  sec‐
149              ond  write  operation.   Normally  the  first of these errors is
150              treated as the end of the tape  and  the  next  volume  will  be
151              called for, however with this option, writes will continue until
152              two in a row fail with 'no space left', indicating the real  end
153              of the tape.  This will allow a little extra data to fit on each
154              tape.
155
156       --tcptimeo <time>
157              Set the TCP timeout threshold. The default value is  10s.  Argu‐
158              ments without dimension are interpreted as usec. Argument dimen‐
159              sions can be us, ms, s or sec, m or min, h.
160
161       -6     Force IPv6 mode for the following network I/O options on command
162              line.
163
164       -4     Force IPv4 mode for the following network I/O options on command
165              line.
166
167       -0     Choose IPv4/IPv6 mode on demand.
168
169       -h, --help
170              Output help information and exit.
171
172       -H, --md5
173              Generate a MD5 hash of transferred data.
174
175       --hash <alg>
176              Use algorithm alg, if alg  is  'list'  possible  algorithms  are
177              listed.
178
179       --pid  Print PID of current process. This option can help you to figure
180              out which instance of mbuffer to kill, if multiple  are  running
181              and  one  is hanging due to a network issue. Printing of the PID
182              can  also  be  triggered  by  adding  "printpid  =  1"  to  your
183              .mbuffer.rc file.
184
185       -V, --version
186              Output version information and exit.
187
188       -W <timeout>
189              Activates  a  watchdog that gets triggered every timeout seconds
190              and checks whether I/O activity has stalled. If  either  channel
191              has  stalled for a complete period, the watchdog writes an error
192              message and terminates mbuffer via SIGINT.  Be  aware  that  the
193              watchdog  is  unaware  of  tape-change activities. So choose the
194              watchdog timeout greater that the worst-case  tape-change  time.
195              The  watchdog is activated with parsing option -W or after pars‐
196              ing all options. To avoid that the watchdog will trigger  during
197              network initialization, put the option -W after -I and -O.
198

DEFAULT VALUES

200       The  default values for most options can be set as key = value pairs in
201       one or more configuration files. See the sample  mbuffer.rc  files  for
202       available  options  and  their  default values. Configuration files are
203       read in following sequence listed below:
204
205       - /etc/mbuffer.rc
206       - $PREFIX/etc/mbuffer.rc
207       - $HOME/.mbuffer.rc
208       - $MBUFFERRC
209
210       The default values given in the files above are  overriden  by  options
211       passed on the command-line.
212
213

ENVIRONMENT VARIABLES

215       If  TMPDIR  is set, mbuffer allocates storage for file-based buffers in
216       this directory. If TMPDIR is unset, /var/tmp will be used.
217
218       MBUFFERRC can be used to set a custom mbuffer.rc config file.
219

FILES

221       $PREFIX/bin/mbuffer
222       /var/tmp/mbuffer-*
223       ~/.mbuffer.rc
224

EXAMPLES

226       To run this program with the default options just type:
227
228       mbuffer
229
230       Using mbuffer to do a backup with tar to the default tape  device.  Op‐
231       tions  for this example: memory-mapped temporary file with a size of 10
232       Megabytes, start after 80% of the buffer have been filled.
233
234       tar cf - mydirectory | gzip | mbuffer -t -m 10M -P 80 -f -o $TAPE
235
236       Using mbuffer with 3 tapes for input and extracting the contents in the
237       current work directory:
238
239       mbuffer -n 3 -i $TAPE | gzip -dc | tar xf -
240
241       Using mbuffer to write to multiple tape volumes:
242
243       tar cf - /usr | mbuffer -f -o $TAPE
244
245       Write to multiple tapes and erase every tape before writing:
246
247       tar cf - /usr | mbuffer -A "echo next tape; read a < /dev/tty; mt erase
248       $TAPE" -f -o $TAPE
249
250       Making a backup via network:
251
252       tape server: mbuffer -I 8000 -f -o $TAPE
253
254       backup client: tar zcf - /home | mbuffer -O tapeserver:8000
255
256       Distributing a directory tree to multiple machines:
257
258       master: tar cf - /tree_to_clone | mbuffer -O clone0:8000 -O clone1:8000
259
260       clones: mbuffer -I master:8000 | tar xf -
261

EXITCODE

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

AUTHORS

267       Thomas Maier-Komor <thomas@maier-komor.de>
268

DONATIONS

270       If  you  like this software, and use it for production purposes in your
271       company, please consider making a donation to support this  work.   You
272       can   donate  directly  via  PayPal  to  the  author's  e-mail  address
273       (thomas@maier-komor.de).
274

HOMEPAGE

276       http://www.maier-komor.de/mbuffer.html
277

LICENSE

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

SEE ALSO

283       buffer(1)
284
285
286
287Thomas Maier-Komor                 R20220418                        mbuffer(1)
Impressum