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, multiple output targets,
14 and many more options than the standard buffer command.
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 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 -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 --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 -6 Force IPv6 mode for the following network I/O options on command
162 line.
163 -4 Force IPv4 mode for the following network I/O options on command
165 line.
166 -0 Choose IPv4/IPv6 mode on demand.
168 -h, --help
170 Output help information and exit.
171 -H, --md5
173 Generate a MD5 hash of transferred data.
174 --hash <alg>
176 Use algorithm alg, if alg is 'list' possible algorithms are
177 listed.
178 --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 -V, --version
186 Output version information and exit.
187 -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
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 - /etc/mbuffer.rc
206 - $PREFIX/etc/mbuffer.rc
207 - $HOME/.mbuffer.rc
208 - $MBUFFERRC
209 The default values given in the files above are overriden by options
211 passed on the command-line.
212
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 MBUFFERRC can be used to set a custom mbuffer.rc config file.
219
221 $PREFIX/bin/mbuffer
222 /var/tmp/mbuffer-*
223 ~/.mbuffer.rc
224
226 To run this program with the default options just type:
227 mbuffer
229 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 tar cf - mydirectory | gzip | mbuffer -t -m 10M -P 80 -f -o $TAPE
235 Using mbuffer with 3 tapes for input and extracting the contents in the
237 current work directory:
238 mbuffer -n 3 -i $TAPE | gzip -dc | tar xf -
240 Using mbuffer to write to multiple tape volumes:
242 tar cf - /usr | mbuffer -f -o $TAPE
244 Write to multiple tapes and erase every tape before writing:
246 tar cf - /usr | mbuffer -A "echo next tape; read a < /dev/tty; mt erase
248 $TAPE" -f -o $TAPE
249 Making a backup via network:
251 tape server: mbuffer -I 8000 -f -o $TAPE
253 backup client: tar zcf - /home | mbuffer -O tapeserver:8000
255 Distributing a directory tree to multiple machines:
257 master: tar cf - /tree_to_clone | mbuffer -O clone0:8000 -O clone1:8000
259 clones: mbuffer -I master:8000 | tar xf -
261
263 mbuffer return 0 upon success. Any kind of failure will yield a non-
264 zero exit code.
265
267 Thomas Maier-Komor <thomas@maier-komor.de>
268
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
276 http://www.maier-komor.de/mbuffer.html
277
279 This software is published under GNU General Public License V3. See
280 file LICENSE for details.
281
283 buffer(1)
284Thomas Maier-Komor R20220418 mbuffer(1)