-.TH fio 1 "October 2013" "User Manual"
+.TH fio 1 "December 2014" "User Manual"
.SH NAME
fio \- flexible I/O tester
.SH SYNOPSIS
.BI \-\-runtime \fR=\fPruntime
Limit run time to \fIruntime\fR seconds.
.TP
-.B \-\-latency\-log
-Generate per-job latency logs.
-.TP
.B \-\-bandwidth\-log
Generate per-job bandwidth logs.
.TP
may override any parameter set in global sections.
.SH "JOB PARAMETERS"
.SS Types
-Some parameters may take arguments of a specific type. The types used are:
+Some parameters may take arguments of a specific type.
+Anywhere a numeric value is required, an arithmetic expression may be used,
+provided it is surrounded by parentheses. Supported operators are:
+.RS
+.RS
+.TP
+.B addition (+)
+.TP
+.B subtraction (-)
+.TP
+.B multiplication (*)
+.TP
+.B division (/)
+.TP
+.B modulus (%)
+.TP
+.B exponentiation (^)
+.RE
+.RE
+.P
+For time values in expressions, units are microseconds by default. This is
+different than for time values not in expressions (not enclosed in
+parentheses). The types used are:
.TP
.I str
String: a sequence of alphanumeric characters.
control what sequence of output is being generated. If not set, the random
sequence depends on the \fBrandrepeat\fR setting.
.TP
-.BI use_os_rand \fR=\fPbool
-Fio can either use the random generator supplied by the OS to generate random
-offsets, or it can use its own internal generator (based on Tausworthe).
-Default is to use the internal generator, which is often of better quality and
-faster. Default: false.
-.TP
.BI fallocate \fR=\fPstr
Whether pre-allocation is performed when laying down files. Accepted values
are:
.TP
.BI size \fR=\fPint
Total size of I/O for this job. \fBfio\fR will run until this many bytes have
-been transferred, unless limited by other options (\fBruntime\fR, for instance).
-Unless \fBnrfiles\fR and \fBfilesize\fR options are given, this amount will be
-divided between the available files for the job. If not set, fio will use the
-full size of the given files or devices. If the files do not exist, size
-must be given. It is also possible to give size as a percentage between 1 and
-100. If size=20% is given, fio will use 20% of the full size of the given
-files or devices.
-.TP
-.BI io_limit \fR=\fPint
+been transferred, unless limited by other options (\fBruntime\fR, for instance,
+or increased/descreased by \fBio_size\fR). Unless \fBnrfiles\fR and
+\fBfilesize\fR options are given, this amount will be divided between the
+available files for the job. If not set, fio will use the full size of the
+given files or devices. If the files do not exist, size must be given. It is
+also possible to give size as a percentage between 1 and 100. If size=20% is
+given, fio will use 20% of the full size of the given files or devices.
+.TP
+.BI io_size \fR=\fPint "\fR,\fB io_limit \fR=\fPint
Normally fio operates within the region set by \fBsize\fR, which means that
the \fBsize\fR option sets both the region and size of IO to be performed.
Sometimes that is not what you want. With this option, it is possible to
define just the amount of IO that fio should do. For instance, if \fBsize\fR
is set to 20G and \fBio_limit\fR is set to 5G, fio will perform IO within
-the first 20G but exit when 5G have been done.
+the first 20G but exit when 5G have been done. The opposite is also
+possible - if \fBsize\fR is set to 20G, and \fBio_size\fR is set to 40G, then
+fio will do 40G of IO within the 0..20G region.
.TP
.BI fill_device \fR=\fPbool "\fR,\fB fill_fs" \fR=\fPbool
Sets size to something really large and waits for ENOSPC (no space left on
.BI buffer_compress_percentage \fR=\fPint
If this is set, then fio will attempt to provide IO buffer content (on WRITEs)
that compress to the specified level. Fio does this by providing a mix of
-random data and zeroes. Note that this is per block size unit, for file/disk
-wide compression level that matches this setting, you'll also want to set
-\fBrefill_buffers\fR.
+random data and a fixed pattern. The fixed pattern is either zeroes, or the
+pattern specified by \fBbuffer_pattern\fR. If the pattern option is used, it
+might skew the compression ratio slightly. Note that this is per block size
+unit, for file/disk wide compression level that matches this setting. Note
+that this is per block size unit, for file/disk wide compression level that
+matches this setting, you'll also want to set refill_buffers.
.TP
.BI buffer_compress_chunk \fR=\fPint
See \fBbuffer_compress_percentage\fR. This setting allows fio to manage how
If set, fio will fill the IO buffers with this pattern. If not set, the contents
of IO buffers is defined by the other options related to buffer contents. The
setting can be any pattern of bytes, and can be prefixed with 0x for hex
-values.
+values. It may also be a string, where the string must then be wrapped with
+"".
+.TP
+.BI dedupe_percentage \fR=\fPint
+If set, fio will generate this percentage of identical buffers when writing.
+These buffers will be naturally dedupable. The contents of the buffers depend
+on what other buffer compression settings have been set. It's possible to have
+the individual buffers either fully compressible, or not at all. This option
+only controls the distribution of unique buffers.
.TP
.BI nrfiles \fR=\fPint
Number of files to use for this job. Default: 1.
having to go through FUSE. This ioengine defines engine specific
options.
.TP
-.B hdfs
-Read and write through Hadoop (HDFS)
+.B libhdfs
+Read and write through Hadoop (HDFS). The \fBfilename\fR option is used to
+specify host,port of the hdfs name-node to connect. This engine interprets
+offsets a little differently. In HDFS, files once created cannot be modified.
+So random writes are not possible. To imitate this, libhdfs engine expects
+bunch of small files to be created over HDFS, and engine will randomly pick a
+file out of those files based on the offset generated by fio backend. (see the
+example job file to create such files, use rw=write option). Please note, you
+might want to set necessary environment variables to work with hdfs/libhdfs
+properly.
.RE
.P
.RE
set by \fBsize\fR, or if it exhaust the allocated time (or hits an error
condition). With this setting, the range/size can be set independently of
the number of IOs to perform. When fio reaches this number, it will exit
-normally and report status.
+normally and report status. Note that this does not extend the amount
+of IO that will be done, it will only stop fio if this condition is met
+before other end-of-job criteria.
.TP
.BI fsync \fR=\fPint
How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data. If
.BI startdelay \fR=\fPirange
Delay start of job for the specified number of seconds. Supports all time
suffixes to allow specification of hours, minutes, seconds and
-milliseconds - seconds are the default if a unit is ommited.
+milliseconds - seconds are the default if a unit is omitted.
Can be given as a range which causes each thread to choose randomly out of the
range.
.TP
.BI experimental_verify \fR=\fPbool
Enable experimental verification.
.TP
+.BI verify_state_save \fR=\fPbool
+When a job exits during the write phase of a verify workload, save its
+current state. This allows fio to replay up until that point, if the
+verify state is loaded for the verify read phase.
+.TP
+.BI verify_state_load \fR=\fPbool
+If a verify termination trigger was used, fio stores the current write
+state of each thread. This can be used at verification time so that fio
+knows how far it should verify. Without this information, fio will run
+a full verification pass, according to the settings in the job file used.
+.TP
.B stonewall "\fR,\fP wait_for_previous"
Wait for preceding jobs in the job file to exit before starting this one.
\fBstonewall\fR implies \fBnew_group\fR.
used and must be omitted unless it is a valid UDP multicast address.
.TP
.BI (net,netsplice)port \fR=\fPint
-The TCP or UDP port to bind to or connect to.
+The TCP or UDP port to bind to or connect to. If this is used with
+\fBnumjobs\fR to spawn multiple instances of the same job type, then
+this will be the starting port number since fio will use a range of ports.
.TP
.BI (net,netsplice)interface \fR=\fPstr
The IP address of the network interface used to send or receive UDP multicast
send back. For UDP multicast traffic pingpong=1 should only be set for a single
reader when multiple readers are listening to the same address.
.TP
+.BI (net, window_size) \fR=\fPint
+Set the desired socket buffer size for the connection.
+.TP
+.BI (net, mss) \fR=\fPint
+Set the TCP maximum segment size (TCP_MAXSEG).
+.TP
.BI (e4defrag,donorname) \fR=\fPstr
File will be used as a block donor (swap extents between files)
.TP
You can connect to multiple clients as well, to do that you could run:
fio \-\-client=server2 \-\-client=server2 <job file(s)>
+
+If the job file is located on the fio server, then you can tell the server
+to load a local file as well. This is done by using \-\-remote-config:
+
+fio \-\-client=server \-\-remote-config /path/to/file.fio
+
+Then the fio serer will open this local (to the server) job file instead
+of being passed one from the client.
.SH AUTHORS
.B fio
was written by Jens Axboe <jens.axboe@oracle.com>,
-now Jens Axboe <jaxboe@fusionio.com>.
+now Jens Axboe <axboe@fb.com>.
.br
This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
on documentation by Jens Axboe.
projects / fio.git / blobdiff