one wants to simulate.
.SH OPTIONS
.TP
+.BI \-\-debug \fR=\fPtype
+Enable verbose tracing of various fio actions. May be `all' for all types
+or individual types separated by a comma (eg \-\-debug=io,file). `help' will
+list all available tracing options.
+.TP
.BI \-\-output \fR=\fPfilename
Write output to \fIfilename\fR.
.TP
.B \-\-minimal
Print statistics in a terse, semicolon-delimited format.
.TP
+.B \-\-version
+Display version information and exit.
+.TP
+.BI \-\-terse\-version \fR=\fPversion
+Set terse version output format (Current version 3, or older version 2).
+.TP
+.B \-\-help
+Display usage information and exit.
+.TP
+.BI \-\-cmdhelp \fR=\fPcommand
+Print help information for \fIcommand\fR. May be `all' for all commands.
+.TP
.BI \-\-showcmd \fR=\fPjobfile
Convert \fIjobfile\fR to a set of command-line options.
.TP
Specifies when real-time ETA estimate should be printed. \fIwhen\fR may
be one of `always', `never' or `auto'.
.TP
+.BI \-\-readonly
+Turn on safety read-only checks, preventing any attempted write.
+.TP
.BI \-\-section \fR=\fPsec
-Only run section \fIsec\fR from job file.
+Only run section \fIsec\fR from job file. Multiple of these options can be given, adding more sections to run.
.TP
-.BI \-\-cmdhelp \fR=\fPcommand
-Print help information for \fIcommand\fR. May be `all' for all commands.
+.BI \-\-alloc\-size \fR=\fPkb
+Set the internal smalloc pool size to \fIkb\fP kilobytes.
.TP
-.BI \-\-debug \fR=\fPtype
-Enable verbose tracing of various fio actions. May be `all' for all types
-or individual types separated by a comma (eg \-\-debug=io,file). `help' will
-list all available tracing options.
+.BI \-\-warnings\-fatal
+All fio parser warnings are fatal, causing fio to exit with an error.
.TP
-.B \-\-help
-Display usage information and exit.
+.BI \-\-max\-jobs \fR=\fPnr
+Set the maximum allowed number of jobs (threads/processes) to suport.
.TP
-.B \-\-version
-Display version information and exit.
+.BI \-\-server \fR=\fPargs
+Start a backend server, with \fIargs\fP specifying what to listen to. See client/server section.
+.TP
+.BI \-\-daemonize \fR=\fPpidfile
+Background a fio server, writing the pid to the given pid file.
+.TP
+.BI \-\-client \fR=\fPhost
+Instead of running the jobs locally, send and run them on the given host.
.SH "JOB FILE FORMAT"
Job files are in `ini' format. They consist of one or more
job definitions, which begin with a job name in square brackets and
if zero_buffers isn't specified, naturally. If data verification is enabled,
refill_buffers is also automatically enabled.
.TP
+.BI scramble_buffers \fR=\fPbool
+If \fBrefill_buffers\fR is too costly and the target is using data
+deduplication, then setting this option will slightly modify the IO buffer
+contents to defeat normal de-dupe attempts. This is not enough to defeat
+more clever block compression attempts, but it will stop naive dedupe
+of blocks. Default: true.
+.TP
.BI nrfiles \fR=\fPint
Number of files to use for this job. Default: 1.
.TP
.TP
.B net
Transfer over the network. \fBfilename\fR must be set appropriately to
-`\fIhost\fR/\fIport\fR' regardless of data direction. If receiving, only the
-\fIport\fR argument is used.
+`\fIhost\fR,\fIport\fR,\fItype\fR' regardless of data direction. \fItype\fR
+is one of \fBtcp\fR, \fBudp\fR, or \fBunix\fR. For UNIX domain sockets,
+the \fIhost\fR parameter is a file system path.
.TP
.B netsplice
Like \fBnet\fR, but uses \fIsplice\fR\|(2) and \fIvmsplice\fR\|(2) to map data
Average bandwidth calculations over the given time in milliseconds. Default:
500ms.
.TP
+.BI iopsavgtime \fR=\fPint
+Average IOPS calculations over the given time in milliseconds. Default:
+500ms.
+.TP
.BI create_serialize \fR=\fPbool
If true, serialize file creation for the jobs. Default: true.
.TP
from. Setting \fBreplay_redirect\fR causes all IOPS to be replayed onto the
single specified device regardless of the device it was recorded from.
.TP
-.B write_bw_log \fR=\fPstr
+.BI write_bw_log \fR=\fPstr
If given, write a bandwidth log of the jobs in this job file. Can be used to
store data of the bandwidth of the jobs in their lifetime. The included
fio_generate_plots script uses gnuplot to turn these text files into nice
graphs. See \fBwrite_log_log\fR for behaviour of given filename. For this
option, the postfix is _bw.log.
.TP
-.B write_lat_log \fR=\fPstr
+.BI write_lat_log \fR=\fPstr
Same as \fBwrite_bw_log\fR, but writes I/O completion latencies. If no
filename is given with this option, the default filename of "jobname_type.log"
is used. Even if the filename is given, fio will still append the type of log.
.TP
-.B disable_lat \fR=\fPbool
+.BI write_iops_log \fR=\fPstr
+Same as \fBwrite_bw_log\fR, but writes IOPS. If no filename is given with this
+option, the default filename of "jobname_type.log" is used. Even if the
+filename is given, fio will still append the type of log.
+.TP
+.BI disable_lat \fR=\fPbool
Disable measurements of total latency numbers. Useful only for cutting
back the number of calls to gettimeofday, as that does impact performance at
really high IOPS rates. Note that to really get rid of a large amount of these
calls, this option must be used with disable_slat and disable_bw as well.
.TP
-.B disable_clat \fR=\fPbool
+.BI disable_clat \fR=\fPbool
Disable measurements of completion latency numbers. See \fBdisable_lat\fR.
.TP
-.B disable_slat \fR=\fPbool
+.BI disable_slat \fR=\fPbool
Disable measurements of submission latency numbers. See \fBdisable_lat\fR.
.TP
-.B disable_bw_measurement \fR=\fPbool
+.BI disable_bw_measurement \fR=\fPbool
Disable measurements of throughput/bandwidth numbers. See \fBdisable_lat\fR.
.TP
.BI lockmem \fR=\fPint
Overwrite the default list of percentiles for completion
latencies. Each number is a floating number in the range (0,100], and
the maximum length of the list is 20. Use ':' to separate the
-numbers. For example, --percentile_list=99.5:99.9 will cause fio to
+numbers. For example, \-\-percentile_list=99.5:99.9 will cause fio to
report the values of completion latency below which 99.5% and 99.9% of
the observed latencies fell, respectively.
.SH OUTPUT
change. The fields are:
.P
.RS
-.B version, jobname, groupid, error
+.B terse version, fio version, jobname, groupid, error
.P
Read status:
.RS
-.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP
+.B Total I/O \fR(KB)\fP, bandwidth \fR(KB/s)\fP, IOPS, runtime \fR(ms)\fP
.P
Submission latency:
.RS
.RS
.B min, max, mean, standard deviation
.RE
+Completion latency percentiles (20 fields):
+.RS
+.B Xth percentile=usec
+.RE
Total latency:
.RS
.B min, max, mean, standard deviation
.P
Write status:
.RS
-.B KB I/O, bandwidth \fR(KB/s)\fP, runtime \fR(ms)\fP
+.B Total I/O \fR(KB)\fP, bandwidth \fR(KB/s)\fP, IOPS, runtime \fR(ms)\fP
.P
Submission latency:
.RS
.RS
.B min, max, mean, standard deviation
.RE
+Completion latency percentiles (20 fields):
+.RS
+.B Xth percentile=usec
+.RE
Total latency:
.RS
.B min, max, mean, standard deviation
.RE
.RE
.P
+Disk utilization (1 for each disk used):
+.RS
+.B name, read ios, write ios, read merges, write merges, read ticks, write ticks, read in-queue time, write in-queue time, disk utilization percentage
+.RE
+.P
Error Info (dependent on continue_on_error, default off):
.RS
.B total # errors, first error code
.P
.B text description (if provided in config - appears on newline)
.RE
+.SH CLIENT / SERVER
+Normally you would run fio as a stand-alone application on the machine
+where the IO workload should be generated. However, it is also possible to
+run the frontend and backend of fio separately. This makes it possible to
+have a fio server running on the machine(s) where the IO workload should
+be running, while controlling it from another machine.
+
+To start the server, you would do:
+
+\fBfio \-\-server=args\fR
+
+on that machine, where args defines what fio listens to. The arguments
+are of the form 'type:hostname or IP:port'. 'type' is either 'ip' for
+TCP/IP, or 'sock' for a local unix domain socket. 'hostname' is either
+a hostname or IP address, and 'port' is the port to listen to (only valid
+for TCP/IP, not a local socket). Some examples:
+
+1) fio --server
+
+ Start a fio server, listening on all interfaces on the default port (8765).
+
+2) fio --server=ip:hostname:4444
+
+ Start a fio server, listening on IP belonging to hostname and on port 4444.
+
+3) fio --server=:4444
+
+ Start a fio server, listening on all interfaces on port 4444.
+
+4) fio --server=1.2.3.4
+
+ Start a fio server, listening on IP 1.2.3.4 on the default port.
+
+5) fio --server=sock:/tmp/fio.sock
+
+ Start a fio server, listening on the local socket /tmp/fio.sock.
+
+When a server is running, you can connect to it from a client. The client
+is run with:
+
+fio --local-args --client=server --remote-args <job file(s)>
+
+where --local-args are arguments that are local to the client where it is
+running, 'server' is the connect string, and --remote-args and <job file(s)>
+are sent to the server. The 'server' string follows the same format as it
+does on the server side, to allow IP/hostname/socket and port strings.
+You can connect to multiple clients as well, to do that you could run:
+
+fio --client=server2 --client=server2 <job file(s)>
.SH AUTHORS
+
.B fio
was written by Jens Axboe <jens.axboe@oracle.com>,
now Jens Axboe <jaxboe@fusionio.com>.
projects / fio.git / blobdiff