1mbuffer(1) console utility mbuffer(1)
2
6 mbuffer - measuring buffer
7
9 mbuffer [options]
10
12 mbuffer buffers I/O operations and displays the throughput rate. It is
13 multi-threaded, supports network connections, and offers more options
14 than the standard buffer.
15
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 -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 -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 -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 -b <num>
40 Use num blocks for buffer (default is determined on startup).
41 -s <size>
43 Use blocks of size bytes for buffer (default is determined on
44 startup).
45 -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 -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 -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 -t use a memory-mapped temporary file as buffer (use with huge buf‐
62 fers)
63 -T <file>
65 as -t but use file instead
66 -d use block-size of device for output (needed for some devices,
68 slows output down)
69 -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 -P <num>
79 start writing after the buffer has been filled to num% (default
80 0 - start at once)
81 -p <num>
83 start reading after the buffer has dropped below fill-ratio of
84 num% (default 100 - start at once)
85 -l <file>
87 log messages to file instead of standard error output
88 -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 -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 -R <rate>
104 Same as above only for setting the transfer limit for the
105 writer.
106 -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 -a <time>
116 the device used is an autoloader which takes time seconds to
117 load a new tape
118 -f overwrite output file if it exists already
120 -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
124 decrease 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 -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 -q quiet - do not display the status on the standard error output
136 -Q quiet - do not log the status in the log file
138 --append
140 Open next output file given via option -o in append mode.
141 --truncate
143 Truncate next output file given via option -o when opening it.
144 --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 -6 Force IPv6 mode for the following network I/O options on command
157 line. -4 Force IPv4 mode for the following network I/O options
158 on command line. -0 Choose IPv4/IPv6 mode on demand.
159 -h, --help
161 Output help information and exit.
162 -H, --md5
164 Generate a MD5 hash of transferred data.
165 --hash <alg>
167 Use algorithm alg, if alg is 'list' possible algorithms are
168 listed.
169 --pid Print PID of current process. This option can help you to figure
171 out which instance of mbuffer to kill, if multiple are running
172 and one is hanging due to a network issue. Printing of the PID
173 can also be triggered by adding "printpid = 1" to your
174 .mbuffer.rc file.
175 -V, --version
177 Output version information and exit.
178 -W <timeout>
180 Activates a watchdog that gets triggered every timeout seconds
181 and checks whether I/O activity has stalled. If either channel
182 has stalled for a complete period, the watchdog writes an error
183 message and terminates mbuffer via SIGINT. Be aware that the
184 watchdog is unaware of tape-change activities. So choose the
185 watchdog timeout greater that the worst-case tape-change time.
186 The watchdog is activated with parsing option -W or after pars‐
187 ing all options. To avoid that the watchdog will trigger during
188 network initialization, put the option -W after -I and -O.
189
191 The default values for following options can be set as key = value
192 pairs in the ~/.mbuffer.rc file:
193 blocksize: block size (option -s)
194 timeout: watchdog timeout (option -W)
195 totalmem: total buffer size (option -m)
196 maxreadspeed: maximum read speed (option -r)
197 maxwritespeed: maximum write speed (option -R)
198 startwrite: threshold for start writing (option -P)
199 startread: threshold for start reading (option -p)
200 pause: pause after writing a block (option -u)
201 numblocks: number of blocks in buffer (option -b)
202 memlock: lock buffer in memory (option -L)
203 showstatus: print transfer status on console (option -q)
204 logstatus: write transfer status to logfile (option -Q)
205 tcpbuffer: TCP buffer size (option --tcpbuffer)
206
210 If TMPDIR is set, mbuffer allocates storage for file-based buffers in
211 this directory. If TMPDIR is unset, /var/tmp will be used.
212
214 /usr/bin/mbuffer
215 /var/tmp/mbuffer-*
216 ~/.mbuffer.rc
217
219 To run this program with the default options just type:
220 mbuffer
222 Using mbuffer to do a backup with tar to the default tape device.
224 Options for this example: memory-mapped temporary file with a size of
225 10 Megabytes, start after 80% of the buffer have been filled.
226 tar cf - mydirectory | gzip | mbuffer -t -m 10M -P 80 -f -o $TAPE
228 Using mbuffer with 3 tapes for input and extracting the contents in the
230 current work directory:
231 mbuffer -n 3 -i $TAPE | gzip -dc | tar xf -
233 Using mbuffer to write to multiple tape volumes:
235 tar cf - /usr | mbuffer -f -o $TAPE
237 Write to multiple tapes and erase every tape before writing:
239 tar cf - /usr | mbuffer -A "echo next tape; read a < /dev/tty; mt erase
241 $TAPE" -f -o $TAPE
242 Making a backup via network:
244 tape server: mbuffer -I 8000 -f -o $TAPE
246 backup client: tar zcf - /home | mbuffer -O tapeserver:8000
248 Distributing a directory tree to multiple machines:
250 master: tar cf - /tree_to_clone | mbuffer -O clone0:8000 -O clone1:8000
252 clones: mbuffer -I master:8000 | tar xf -
254
256 mbuffer return 0 upon success. Any kind of failure will yield a non-
257 zero exit code.
258
260 Thomas Maier-Komor <thomas@maier-komor.de>
261
263 If you like this software, and use it for production purposes in your
264 company, please consider making a donation to support this work. You
265 can donate directly via PayPal to the author's e-mail address
266 (thomas@maier-komor.de).
267
269 http://www.maier-komor.de/mbuffer.html
270
272 This software is published under GNU General Public License V3. See
273 file LICENSE for details.
274
276 buffer(1)
277Thomas Maier-Komor 20200505 mbuffer(1)