2919686e6dbcd42650869191e995870bba6a4c37
[fio.git] / fio.1
1 .TH fio 1 "July 2017" "User Manual"
2 .SH NAME
3 fio \- flexible I/O tester
4 .SH SYNOPSIS
5 .B fio
6 [\fIoptions\fR] [\fIjobfile\fR]...
7 .SH DESCRIPTION
8 .B fio
9 is a tool that will spawn a number of threads or processes doing a
10 particular type of I/O action as specified by the user.
11 The typical use of fio is to write a job file matching the I/O load
12 one wants to simulate.
13 .SH OPTIONS
14 .TP
15 .BI \-\-debug \fR=\fPtype
16 Enable verbose tracing of various fio actions. May be `all' for all types
17 or individual types separated by a comma (e.g. \-\-debug=file,mem will enable
18 file and memory debugging). `help' will list all available tracing options.
19 .TP
20 .BI \-\-parse-only
21 Parse options only, don't start any I/O.
22 .TP
23 .BI \-\-output \fR=\fPfilename
24 Write output to \fIfilename\fR.
25 .TP
26 .BI \-\-output-format \fR=\fPformat
27 Set the reporting format to \fInormal\fR, \fIterse\fR, \fIjson\fR, or
28 \fIjson+\fR. Multiple formats can be selected, separate by a comma. \fIterse\fR
29 is a CSV based format. \fIjson+\fR is like \fIjson\fR, except it adds a full
30 dump of the latency buckets.
31 .TP
32 .BI \-\-runtime \fR=\fPruntime
33 Limit run time to \fIruntime\fR seconds.
34 .TP
35 .B \-\-bandwidth\-log
36 Generate aggregate bandwidth logs.
37 .TP
38 .B \-\-minimal
39 Print statistics in a terse, semicolon-delimited format.
40 .TP
41 .B \-\-append-terse
42 Print statistics in selected mode AND terse, semicolon-delimited format.
43 Deprecated, use \-\-output-format instead to select multiple formats.
44 .TP
45 .BI \-\-terse\-version \fR=\fPversion
46 Set terse version output format (default 3, or 2, 4, 5)
47 .TP
48 .B \-\-version
49 Print version information and exit.
50 .TP
51 .B \-\-help
52 Print a summary of the command line options and exit.
53 .TP
54 .B \-\-cpuclock-test
55 Perform test and validation of internal CPU clock.
56 .TP
57 .BI \-\-crctest \fR=\fP[test]
58 Test the speed of the built-in checksumming functions. If no argument is given,
59 all of them are tested. Alternatively, a comma separated list can be passed, in which
60 case the given ones are tested.
61 .TP
62 .BI \-\-cmdhelp \fR=\fPcommand
63 Print help information for \fIcommand\fR. May be `all' for all commands.
64 .TP
65 .BI \-\-enghelp \fR=\fPioengine[,command]
66 List all commands defined by \fIioengine\fR, or print help for \fIcommand\fR defined by \fIioengine\fR.
67 If no \fIioengine\fR is given, list all available ioengines.
68 .TP
69 .BI \-\-showcmd \fR=\fPjobfile
70 Convert \fIjobfile\fR to a set of command-line options.
71 .TP
72 .BI \-\-readonly
73 Turn on safety read-only checks, preventing writes. The \-\-readonly
74 option is an extra safety guard to prevent users from accidentally starting
75 a write workload when that is not desired. Fio will only write if
76 `rw=write/randwrite/rw/randrw` is given. This extra safety net can be used
77 as an extra precaution as \-\-readonly will also enable a write check in
78 the I/O engine core to prevent writes due to unknown user space bug(s).
79 .TP
80 .BI \-\-eta \fR=\fPwhen
81 Specifies when real-time ETA estimate should be printed. \fIwhen\fR may
82 be `always', `never' or `auto'.
83 .TP
84 .BI \-\-eta\-newline \fR=\fPtime
85 Force a new line for every \fItime\fR period passed. When the unit is omitted,
86 the value is interpreted in seconds.
87 .TP
88 .BI \-\-status\-interval \fR=\fPtime
89 Force full status dump every \fItime\fR period passed. When the unit is omitted,
90 the value is interpreted in seconds.
91 .TP
92 .BI \-\-section \fR=\fPname
93 Only run specified section \fIname\fR in job file. Multiple sections can be specified.
94 The \-\-section option allows one to combine related jobs into one file.
95 E.g. one job file could define light, moderate, and heavy sections. Tell
96 fio to run only the "heavy" section by giving \-\-section=heavy
97 command line option. One can also specify the "write" operations in one
98 section and "verify" operation in another section. The \-\-section option
99 only applies to job sections. The reserved *global* section is always
100 parsed and used.
101 .TP
102 .BI \-\-alloc\-size \fR=\fPkb
103 Set the internal smalloc pool size to \fIkb\fP in KiB. The
104 \-\-alloc-size switch allows one to use a larger pool size for smalloc.
105 If running large jobs with randommap enabled, fio can run out of memory.
106 Smalloc is an internal allocator for shared structures from a fixed size
107 memory pool and can grow to 16 pools. The pool size defaults to 16MiB.
108 NOTE: While running .fio_smalloc.* backing store files are visible
109 in /tmp.
110 .TP
111 .BI \-\-warnings\-fatal
112 All fio parser warnings are fatal, causing fio to exit with an error.
113 .TP
114 .BI \-\-max\-jobs \fR=\fPnr
115 Set the maximum number of threads/processes to support.
116 .TP
117 .BI \-\-server \fR=\fPargs
118 Start a backend server, with \fIargs\fP specifying what to listen to. See Client/Server section.
119 .TP
120 .BI \-\-daemonize \fR=\fPpidfile
121 Background a fio server, writing the pid to the given \fIpidfile\fP file.
122 .TP
123 .BI \-\-client \fR=\fPhostname
124 Instead of running the jobs locally, send and run them on the given host or set of hosts. See Client/Server section.
125 .TP
126 .BI \-\-remote-config \fR=\fPfile
127 Tell fio server to load this local file.
128 .TP
129 .BI \-\-idle\-prof \fR=\fPoption
130 Report CPU idleness. \fIoption\fP is one of the following:
131 .RS
132 .RS
133 .TP
134 .B calibrate
135 Run unit work calibration only and exit.
136 .TP
137 .B system
138 Show aggregate system idleness and unit work.
139 .TP
140 .B percpu
141 As "system" but also show per CPU idleness.
142 .RE
143 .RE
144 .TP
145 .BI \-\-inflate-log \fR=\fPlog
146 Inflate and output compressed log.
147 .TP
148 .BI \-\-trigger-file \fR=\fPfile
149 Execute trigger cmd when file exists.
150 .TP
151 .BI \-\-trigger-timeout \fR=\fPt
152 Execute trigger at this time.
153 .TP
154 .BI \-\-trigger \fR=\fPcmd
155 Set this command as local trigger.
156 .TP
157 .BI \-\-trigger-remote \fR=\fPcmd
158 Set this command as remote trigger.
159 .TP
160 .BI \-\-aux-path \fR=\fPpath
161 Use this path for fio state generated files.
162 .SH "JOB FILE FORMAT"
163 Any parameters following the options will be assumed to be job files, unless
164 they match a job file parameter. Multiple job files can be listed and each job
165 file will be regarded as a separate group. Fio will `stonewall` execution
166 between each group.
167
168 Fio accepts one or more job files describing what it is
169 supposed to do. The job file format is the classic ini file, where the names
170 enclosed in [] brackets define the job name. You are free to use any ASCII name
171 you want, except *global* which has special meaning. Following the job name is
172 a sequence of zero or more parameters, one per line, that define the behavior of
173 the job. If the first character in a line is a ';' or a '#', the entire line is
174 discarded as a comment.
175
176 A *global* section sets defaults for the jobs described in that file. A job may
177 override a *global* section parameter, and a job file may even have several
178 *global* sections if so desired. A job is only affected by a *global* section
179 residing above it.
180
181 The \-\-cmdhelp option also lists all options. If used with an `option`
182 argument, \-\-cmdhelp will detail the given `option`.
183
184 See the `examples/` directory in the fio source for inspiration on how to write
185 job files. Note the copyright and license requirements currently apply to
186 `examples/` files.
187 .SH "JOB FILE PARAMETERS"
188 Some parameters take an option of a given type, such as an integer or a
189 string. Anywhere a numeric value is required, an arithmetic expression may be
190 used, provided it is surrounded by parentheses. Supported operators are:
191 .RS
192 .RS
193 .TP
194 .B addition (+)
195 .TP
196 .B subtraction (-)
197 .TP
198 .B multiplication (*)
199 .TP
200 .B division (/)
201 .TP
202 .B modulus (%)
203 .TP
204 .B exponentiation (^)
205 .RE
206 .RE
207 .P
208 For time values in expressions, units are microseconds by default. This is
209 different than for time values not in expressions (not enclosed in
210 parentheses).
211 .SH "PARAMETER TYPES"
212 The following parameter types are used.
213 .TP
214 .I str
215 String. A sequence of alphanumeric characters.
216 .TP
217 .I time
218 Integer with possible time suffix. Without a unit value is interpreted as
219 seconds unless otherwise specified. Accepts a suffix of 'd' for days, 'h' for
220 hours, 'm' for minutes, 's' for seconds, 'ms' (or 'msec') for milliseconds and 'us'
221 (or 'usec') for microseconds. For example, use 10m for 10 minutes.
222 .TP
223 .I int
224 Integer. A whole number value, which may contain an integer prefix
225 and an integer suffix.
226 .RS
227 .RS
228 .P
229 [*integer prefix*] **number** [*integer suffix*]
230 .RE
231 .P
232 The optional *integer prefix* specifies the number's base. The default
233 is decimal. *0x* specifies hexadecimal.
234 .P
235 The optional *integer suffix* specifies the number's units, and includes an
236 optional unit prefix and an optional unit. For quantities of data, the
237 default unit is bytes. For quantities of time, the default unit is seconds
238 unless otherwise specified.
239 .P
240 With `kb_base=1000', fio follows international standards for unit
241 prefixes. To specify power-of-10 decimal values defined in the
242 International System of Units (SI):
243 .RS
244 .P
245 ki means kilo (K) or 1000
246 .RE
247 .RS
248 mi means mega (M) or 1000**2
249 .RE
250 .RS
251 gi means giga (G) or 1000**3
252 .RE
253 .RS
254 ti means tera (T) or 1000**4
255 .RE
256 .RS
257 pi means peta (P) or 1000**5
258 .RE
259 .P
260 To specify power-of-2 binary values defined in IEC 80000-13:
261 .RS
262 .P
263 k means kibi (Ki) or 1024
264 .RE
265 .RS
266 m means mebi (Mi) or 1024**2
267 .RE
268 .RS
269 g means gibi (Gi) or 1024**3
270 .RE
271 .RS
272 t means tebi (Ti) or 1024**4
273 .RE
274 .RS
275 p means pebi (Pi) or 1024**5
276 .RE
277 .P
278 With `kb_base=1024' (the default), the unit prefixes are opposite
279 from those specified in the SI and IEC 80000-13 standards to provide
280 compatibility with old scripts. For example, 4k means 4096.
281 .P
282 For quantities of data, an optional unit of 'B' may be included
283 (e.g., 'kB' is the same as 'k').
284 .P
285 The *integer suffix* is not case sensitive (e.g., m/mi mean mebi/mega,
286 not milli). 'b' and 'B' both mean byte, not bit.
287 .P
288 Examples with `kb_base=1000':
289 .RS
290 .P
291 4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
292 .RE
293 .RS
294 1 MiB: 1048576, 1m, 1024k
295 .RE
296 .RS
297 1 MB: 1000000, 1mi, 1000ki
298 .RE
299 .RS
300 1 TiB: 1073741824, 1t, 1024m, 1048576k
301 .RE
302 .RS
303 1 TB: 1000000000, 1ti, 1000mi, 1000000ki
304 .RE
305 .P
306 Examples with `kb_base=1024' (default):
307 .RS
308 .P
309 4 KiB: 4096, 4096b, 4096B, 4k, 4kb, 4kB, 4K, 4KB
310 .RE
311 .RS
312 1 MiB: 1048576, 1m, 1024k
313 .RE
314 .RS
315 1 MB: 1000000, 1mi, 1000ki
316 .RE
317 .RS
318 1 TiB: 1073741824, 1t, 1024m, 1048576k
319 .RE
320 .RS
321 1 TB: 1000000000, 1ti, 1000mi, 1000000ki
322 .RE
323 .P
324 To specify times (units are not case sensitive):
325 .RS
326 .P
327 D means days
328 .RE
329 .RS
330 H means hours
331 .RE
332 .RS
333 M mean minutes
334 .RE
335 .RS
336 s or sec means seconds (default)
337 .RE
338 .RS
339 ms or msec means milliseconds
340 .RE
341 .RS
342 us or usec means microseconds
343 .RE
344 .P
345 If the option accepts an upper and lower range, use a colon ':' or
346 minus '-' to separate such values. See `irange` parameter type.
347 If the lower value specified happens to be larger than the upper value
348 the two values are swapped.
349 .RE
350 .TP
351 .I bool
352 Boolean. Usually parsed as an integer, however only defined for
353 true and false (1 and 0).
354 .TP
355 .I irange
356 Integer range with suffix. Allows value range to be given, such as
357 1024-4096. A colon may also be used as the separator, e.g. 1k:4k. If the
358 option allows two sets of ranges, they can be specified with a ',' or '/'
359 delimiter: 1k-4k/8k-32k. Also see `int` parameter type.
360 .TP
361 .I float_list
362 A list of floating point numbers, separated by a ':' character.
363 .SH "JOB DESCRIPTION"
364 With the above in mind, here follows the complete list of fio job parameters.
365 .TP
366 .BI name \fR=\fPstr
367 May be used to override the job name.  On the command line, this parameter
368 has the special purpose of signalling the start of a new job.
369 .TP
370 .BI wait_for \fR=\fPstr
371 Specifies the name of the already defined job to wait for. Single waitee name
372 only may be specified. If set, the job won't be started until all workers of
373 the waitee job are done.  Wait_for operates on the job name basis, so there are
374 a few limitations. First, the waitee must be defined prior to the waiter job
375 (meaning no forward references). Second, if a job is being referenced as a
376 waitee, it must have a unique name (no duplicate waitees).
377 .TP
378 .BI description \fR=\fPstr
379 Human-readable description of the job. It is printed when the job is run, but
380 otherwise has no special purpose.
381 .TP
382 .BI directory \fR=\fPstr
383 Prefix filenames with this directory.  Used to place files in a location other
384 than `./'.
385 You can specify a number of directories by separating the names with a ':'
386 character. These directories will be assigned equally distributed to job clones
387 creates with \fInumjobs\fR as long as they are using generated filenames.
388 If specific \fIfilename(s)\fR are set fio will use the first listed directory,
389 and thereby matching the  \fIfilename\fR semantic which generates a file each
390 clone if not specified, but let all clones use the same if set. See
391 \fIfilename\fR for considerations regarding escaping certain characters on
392 some platforms.
393 .TP
394 .BI filename \fR=\fPstr
395 .B fio
396 normally makes up a file name based on the job name, thread number, and file
397 number. If you want to share files between threads in a job or several jobs,
398 specify a \fIfilename\fR for each of them to override the default.
399 If the I/O engine is file-based, you can specify
400 a number of files by separating the names with a `:' character. `\-' is a
401 reserved name, meaning stdin or stdout, depending on the read/write direction
402 set. On Windows, disk devices are accessed as \\.\PhysicalDrive0 for the first
403 device, \\.\PhysicalDrive1 for the second etc. Note: Windows and FreeBSD
404 prevent write access to areas of the disk containing in-use data
405 (e.g. filesystems). If the wanted filename does need to include a colon, then
406 escape that with a '\\' character. For instance, if the filename is
407 "/dev/dsk/foo@3,0:c", then you would use filename="/dev/dsk/foo@3,0\\:c".
408 .TP
409 .BI filename_format \fR=\fPstr
410 If sharing multiple files between jobs, it is usually necessary to have
411 fio generate the exact names that you want. By default, fio will name a file
412 based on the default file format specification of
413 \fBjobname.jobnumber.filenumber\fP. With this option, that can be
414 customized. Fio will recognize and replace the following keywords in this
415 string:
416 .RS
417 .RS
418 .TP
419 .B $jobname
420 The name of the worker thread or process.
421 .TP
422 .B $jobnum
423 The incremental number of the worker thread or process.
424 .TP
425 .B $filenum
426 The incremental number of the file for that worker thread or process.
427 .RE
428 .P
429 To have dependent jobs share a set of files, this option can be set to
430 have fio generate filenames that are shared between the two. For instance,
431 if \fBtestfiles.$filenum\fR is specified, file number 4 for any job will
432 be named \fBtestfiles.4\fR. The default of \fB$jobname.$jobnum.$filenum\fR
433 will be used if no other format specifier is given.
434 .RE
435 .P
436 .TP
437 .BI unique_filename \fR=\fPbool
438 To avoid collisions between networked clients, fio defaults to prefixing
439 any generated filenames (with a directory specified) with the source of
440 the client connecting. To disable this behavior, set this option to 0.
441 .TP
442 .BI lockfile \fR=\fPstr
443 Fio defaults to not locking any files before it does IO to them. If a file or
444 file descriptor is shared, fio can serialize IO to that file to make the end
445 result consistent. This is usual for emulating real workloads that share files.
446 The lock modes are:
447 .RS
448 .RS
449 .TP
450 .B none
451 No locking. This is the default.
452 .TP
453 .B exclusive
454 Only one thread or process may do IO at a time, excluding all others.
455 .TP
456 .B readwrite
457 Read-write locking on the file. Many readers may access the file at the same
458 time, but writes get exclusive access.
459 .RE
460 .RE
461 .P
462 .BI opendir \fR=\fPstr
463 Recursively open any files below directory \fIstr\fR.
464 .TP
465 .BI readwrite \fR=\fPstr "\fR,\fP rw" \fR=\fPstr
466 Type of I/O pattern.  Accepted values are:
467 .RS
468 .RS
469 .TP
470 .B read
471 Sequential reads.
472 .TP
473 .B write
474 Sequential writes.
475 .TP
476 .B trim
477 Sequential trims (Linux block devices only).
478 .TP
479 .B randread
480 Random reads.
481 .TP
482 .B randwrite
483 Random writes.
484 .TP
485 .B randtrim
486 Random trims (Linux block devices only).
487 .TP
488 .B rw, readwrite
489 Mixed sequential reads and writes.
490 .TP
491 .B randrw
492 Mixed random reads and writes.
493 .TP
494 .B trimwrite
495 Sequential trim and write mixed workload. Blocks will be trimmed first, then
496 the same blocks will be written to.
497 .RE
498 .P
499 Fio defaults to read if the option is not specified.
500 For mixed I/O, the default split is 50/50. For certain types of io the result
501 may still be skewed a bit, since the speed may be different. It is possible to
502 specify a number of IOs to do before getting a new offset, this is done by
503 appending a `:\fI<nr>\fR to the end of the string given. For a random read, it
504 would look like \fBrw=randread:8\fR for passing in an offset modifier with a
505 value of 8. If the postfix is used with a sequential IO pattern, then the value
506 specified will be added to the generated offset for each IO. For instance,
507 using \fBrw=write:4k\fR will skip 4k for every write. It turns sequential IO
508 into sequential IO with holes. See the \fBrw_sequencer\fR option.
509 .RE
510 .TP
511 .BI rw_sequencer \fR=\fPstr
512 If an offset modifier is given by appending a number to the \fBrw=<str>\fR line,
513 then this option controls how that number modifies the IO offset being
514 generated. Accepted values are:
515 .RS
516 .RS
517 .TP
518 .B sequential
519 Generate sequential offset
520 .TP
521 .B identical
522 Generate the same offset
523 .RE
524 .P
525 \fBsequential\fR is only useful for random IO, where fio would normally
526 generate a new random offset for every IO. If you append eg 8 to randread, you
527 would get a new random offset for every 8 IOs. The result would be a seek for
528 only every 8 IOs, instead of for every IO. Use \fBrw=randread:8\fR to specify
529 that. As sequential IO is already sequential, setting \fBsequential\fR for that
530 would not result in any differences.  \fBidentical\fR behaves in a similar
531 fashion, except it sends the same offset 8 number of times before generating a
532 new offset.
533 .RE
534 .P
535 .TP
536 .BI kb_base \fR=\fPint
537 The base unit for a kilobyte. The defacto base is 2^10, 1024.  Storage
538 manufacturers like to use 10^3 or 1000 as a base ten unit instead, for obvious
539 reasons. Allowed values are 1024 or 1000, with 1024 being the default.
540 .TP
541 .BI unified_rw_reporting \fR=\fPbool
542 Fio normally reports statistics on a per data direction basis, meaning that
543 reads, writes, and trims are accounted and reported separately. If this option is
544 set fio sums the results and reports them as "mixed" instead.
545 .TP
546 .BI randrepeat \fR=\fPbool
547 Seed the random number generator used for random I/O patterns in a predictable
548 way so the pattern is repeatable across runs.  Default: true.
549 .TP
550 .BI allrandrepeat \fR=\fPbool
551 Seed all random number generators in a predictable way so results are
552 repeatable across runs.  Default: false.
553 .TP
554 .BI randseed \fR=\fPint
555 Seed the random number generators based on this seed value, to be able to
556 control what sequence of output is being generated. If not set, the random
557 sequence depends on the \fBrandrepeat\fR setting.
558 .TP
559 .BI fallocate \fR=\fPstr
560 Whether pre-allocation is performed when laying down files. Accepted values
561 are:
562 .RS
563 .RS
564 .TP
565 .B none
566 Do not pre-allocate space.
567 .TP
568 .B native
569 Use a platform's native pre-allocation call but fall back to 'none' behavior if
570 it fails/is not implemented.
571 .TP
572 .B posix
573 Pre-allocate via \fBposix_fallocate\fR\|(3).
574 .TP
575 .B keep
576 Pre-allocate via \fBfallocate\fR\|(2) with FALLOC_FL_KEEP_SIZE set.
577 .TP
578 .B 0
579 Backward-compatible alias for 'none'.
580 .TP
581 .B 1
582 Backward-compatible alias for 'posix'.
583 .RE
584 .P
585 May not be available on all supported platforms. 'keep' is only
586 available on Linux. If using ZFS on Solaris this cannot be set to 'posix'
587 because ZFS doesn't support it. Default: 'native' if any pre-allocation methods
588 are available, 'none' if not.
589 .RE
590 .TP
591 .BI fadvise_hint \fR=\fPstr
592 Use \fBposix_fadvise\fR\|(2) to advise the kernel what I/O patterns
593 are likely to be issued. Accepted values are:
594 .RS
595 .RS
596 .TP
597 .B 0
598 Backwards compatible hint for "no hint".
599 .TP
600 .B 1
601 Backwards compatible hint for "advise with fio workload type". This
602 uses \fBFADV_RANDOM\fR for a random workload, and \fBFADV_SEQUENTIAL\fR
603 for a sequential workload.
604 .TP
605 .B sequential
606 Advise using \fBFADV_SEQUENTIAL\fR
607 .TP
608 .B random
609 Advise using \fBFADV_RANDOM\fR
610 .RE
611 .RE
612 .TP
613 .BI write_hint \fR=\fPstr
614 Use \fBfcntl\fR\|(2) to advise the kernel what life time to expect from a write.
615 Only supported on Linux, as of version 4.13. The values are all relative to
616 each other, and no absolute meaning should be associated with them. Accepted
617 values are:
618 .RS
619 .RS
620 .TP
621 .B none
622 No particular life time associated with this file.
623 .TP
624 .B short
625 Data written to this file has a short life time.
626 .TP
627 .B medium
628 Data written to this file has a medium life time.
629 .TP
630 .B long
631 Data written to this file has a long life time.
632 .TP
633 .B extreme
634 Data written to this file has a very long life time.
635 .RE
636 .RE
637 .TP
638 .BI size \fR=\fPint
639 Total size of I/O for this job.  \fBfio\fR will run until this many bytes have
640 been transferred, unless limited by other options (\fBruntime\fR, for instance,
641 or increased/descreased by \fBio_size\fR). Unless \fBnrfiles\fR and
642 \fBfilesize\fR options are given, this amount will be divided between the
643 available files for the job. If not set, fio will use the full size of the
644 given files or devices. If the files do not exist, size must be given. It is
645 also possible to give size as a percentage between 1 and 100. If size=20% is
646 given, fio will use 20% of the full size of the given files or devices.
647 .TP
648 .BI io_size \fR=\fPint "\fR,\fB io_limit \fR=\fPint
649 Normally fio operates within the region set by \fBsize\fR, which means that
650 the \fBsize\fR option sets both the region and size of IO to be performed.
651 Sometimes that is not what you want. With this option, it is possible to
652 define just the amount of IO that fio should do. For instance, if \fBsize\fR
653 is set to 20G and \fBio_limit\fR is set to 5G, fio will perform IO within
654 the first 20G but exit when 5G have been done. The opposite is also
655 possible - if \fBsize\fR is set to 20G, and \fBio_size\fR is set to 40G, then
656 fio will do 40G of IO within the 0..20G region.
657 .TP
658 .BI fill_device \fR=\fPbool "\fR,\fB fill_fs" \fR=\fPbool
659 Sets size to something really large and waits for ENOSPC (no space left on
660 device) as the terminating condition. Only makes sense with sequential write.
661 For a read workload, the mount point will be filled first then IO started on
662 the result. This option doesn't make sense if operating on a raw device node,
663 since the size of that is already known by the file system. Additionally,
664 writing beyond end-of-device will not return ENOSPC there.
665 .TP
666 .BI filesize \fR=\fPirange
667 Individual file sizes. May be a range, in which case \fBfio\fR will select sizes
668 for files at random within the given range, limited to \fBsize\fR in total (if
669 that is given). If \fBfilesize\fR is not specified, each created file is the
670 same size.
671 .TP
672 .BI file_append \fR=\fPbool
673 Perform IO after the end of the file. Normally fio will operate within the
674 size of a file. If this option is set, then fio will append to the file
675 instead. This has identical behavior to setting \fRoffset\fP to the size
676 of a file. This option is ignored on non-regular files.
677 .TP
678 .BI blocksize \fR=\fPint[,int][,int] "\fR,\fB bs" \fR=\fPint[,int][,int]
679 The block size in bytes for I/O units.  Default: 4096.
680 A single value applies to reads, writes, and trims.
681 Comma-separated values may be specified for reads, writes, and trims.
682 Empty values separated by commas use the default value. A value not
683 terminated in a comma applies to subsequent types.
684 .nf
685 Examples:
686 bs=256k    means 256k for reads, writes and trims
687 bs=8k,32k  means 8k for reads, 32k for writes and trims
688 bs=8k,32k, means 8k for reads, 32k for writes, and default for trims
689 bs=,8k     means default for reads, 8k for writes and trims
690 bs=,8k,    means default for reads, 8k for writes, and default for trims
691 .fi
692 .TP
693 .BI blocksize_range \fR=\fPirange[,irange][,irange] "\fR,\fB bsrange" \fR=\fPirange[,irange][,irange]
694 A range of block sizes in bytes for I/O units.
695 The issued I/O unit will always be a multiple of the minimum size, unless
696 \fBblocksize_unaligned\fR is set.
697 Comma-separated ranges may be specified for reads, writes, and trims
698 as described in \fBblocksize\fR.
699 .nf
700 Example: bsrange=1k-4k,2k-8k.
701 .fi
702 .TP
703 .BI bssplit \fR=\fPstr[,str][,str]
704 This option allows even finer grained control of the block sizes issued,
705 not just even splits between them. With this option, you can weight various
706 block sizes for exact control of the issued IO for a job that has mixed
707 block sizes. The format of the option is bssplit=blocksize/percentage,
708 optionally adding as many definitions as needed separated by a colon.
709 Example: bssplit=4k/10:64k/50:32k/40 would issue 50% 64k blocks, 10% 4k
710 blocks and 40% 32k blocks. \fBbssplit\fR also supports giving separate
711 splits to reads, writes, and trims.
712 Comma-separated values may be specified for reads, writes, and trims
713 as described in \fBblocksize\fR.
714 .TP
715 .B blocksize_unaligned\fR,\fB bs_unaligned
716 If set, fio will issue I/O units with any size within \fBblocksize_range\fR,
717 not just multiples of the minimum size.  This typically won't
718 work with direct I/O, as that normally requires sector alignment.
719 .TP
720 .BI bs_is_seq_rand \fR=\fPbool
721 If this option is set, fio will use the normal read,write blocksize settings as
722 sequential,random blocksize settings instead. Any random read or write will
723 use the WRITE blocksize settings, and any sequential read or write will use
724 the READ blocksize settings.
725 .TP
726 .BI blockalign \fR=\fPint[,int][,int] "\fR,\fB ba" \fR=\fPint[,int][,int]
727 Boundary to which fio will align random I/O units. Default: \fBblocksize\fR.
728 Minimum alignment is typically 512b for using direct IO, though it usually
729 depends on the hardware block size.  This option is mutually exclusive with
730 using a random map for files, so it will turn off that option.
731 Comma-separated values may be specified for reads, writes, and trims
732 as described in \fBblocksize\fR.
733 .TP
734 .B zero_buffers
735 Initialize buffers with all zeros. Default: fill buffers with random data.
736 .TP
737 .B refill_buffers
738 If this option is given, fio will refill the IO buffers on every submit. The
739 default is to only fill it at init time and reuse that data. Only makes sense
740 if zero_buffers isn't specified, naturally. If data verification is enabled,
741 refill_buffers is also automatically enabled.
742 .TP
743 .BI scramble_buffers \fR=\fPbool
744 If \fBrefill_buffers\fR is too costly and the target is using data
745 deduplication, then setting this option will slightly modify the IO buffer
746 contents to defeat normal de-dupe attempts. This is not enough to defeat
747 more clever block compression attempts, but it will stop naive dedupe
748 of blocks. Default: true.
749 .TP
750 .BI buffer_compress_percentage \fR=\fPint
751 If this is set, then fio will attempt to provide IO buffer content (on WRITEs)
752 that compress to the specified level. Fio does this by providing a mix of
753 random data and a fixed pattern. The fixed pattern is either zeroes, or the
754 pattern specified by \fBbuffer_pattern\fR. If the pattern option is used, it
755 might skew the compression ratio slightly. Note that this is per block size
756 unit, for file/disk wide compression level that matches this setting. Note
757 that this is per block size unit, for file/disk wide compression level that
758 matches this setting, you'll also want to set refill_buffers.
759 .TP
760 .BI buffer_compress_chunk \fR=\fPint
761 See \fBbuffer_compress_percentage\fR. This setting allows fio to manage how
762 big the ranges of random data and zeroed data is. Without this set, fio will
763 provide \fBbuffer_compress_percentage\fR of blocksize random data, followed by
764 the remaining zeroed. With this set to some chunk size smaller than the block
765 size, fio can alternate random and zeroed data throughout the IO buffer.
766 .TP
767 .BI buffer_pattern \fR=\fPstr
768 If set, fio will fill the I/O buffers with this pattern or with the contents
769 of a file. If not set, the contents of I/O buffers are defined by the other
770 options related to buffer contents. The setting can be any pattern of bytes,
771 and can be prefixed with 0x for hex values. It may also be a string, where
772 the string must then be wrapped with ``""``. Or it may also be a filename,
773 where the filename must be wrapped with ``''`` in which case the file is
774 opened and read. Note that not all the file contents will be read if that
775 would cause the buffers to overflow. So, for example:
776 .RS
777 .RS
778 \fBbuffer_pattern\fR='filename'
779 .RS
780 or
781 .RE
782 \fBbuffer_pattern\fR="abcd"
783 .RS
784 or
785 .RE
786 \fBbuffer_pattern\fR=-12
787 .RS
788 or
789 .RE
790 \fBbuffer_pattern\fR=0xdeadface
791 .RE
792 .LP
793 Also you can combine everything together in any order:
794 .LP
795 .RS
796 \fBbuffer_pattern\fR=0xdeadface"abcd"-12'filename'
797 .RE
798 .RE
799 .TP
800 .BI dedupe_percentage \fR=\fPint
801 If set, fio will generate this percentage of identical buffers when writing.
802 These buffers will be naturally dedupable. The contents of the buffers depend
803 on what other buffer compression settings have been set. It's possible to have
804 the individual buffers either fully compressible, or not at all. This option
805 only controls the distribution of unique buffers.
806 .TP
807 .BI nrfiles \fR=\fPint
808 Number of files to use for this job.  Default: 1.
809 .TP
810 .BI openfiles \fR=\fPint
811 Number of files to keep open at the same time.  Default: \fBnrfiles\fR.
812 .TP
813 .BI file_service_type \fR=\fPstr
814 Defines how files to service are selected.  The following types are defined:
815 .RS
816 .RS
817 .TP
818 .B random
819 Choose a file at random.
820 .TP
821 .B roundrobin
822 Round robin over opened files (default).
823 .TP
824 .B sequential
825 Do each file in the set sequentially.
826 .TP
827 .B zipf
828 Use a zipfian distribution to decide what file to access.
829 .TP
830 .B pareto
831 Use a pareto distribution to decide what file to access.
832 .TP
833 .B normal
834 Use a Gaussian (normal) distribution to decide what file to access.
835 .TP
836 .B gauss
837 Alias for normal.
838 .RE
839 .P
840 For \fBrandom\fR, \fBroundrobin\fR, and \fBsequential\fR, a postfix can be
841 appended to tell fio how many I/Os to issue before switching to a new file.
842 For example, specifying \fBfile_service_type=random:8\fR would cause fio to
843 issue \fI8\fR I/Os before selecting a new file at random. For the non-uniform
844 distributions, a floating point postfix can be given to influence how the
845 distribution is skewed. See \fBrandom_distribution\fR for a description of how
846 that would work.
847 .RE
848 .TP
849 .BI ioengine \fR=\fPstr
850 Defines how the job issues I/O.  The following types are defined:
851 .RS
852 .RS
853 .TP
854 .B sync
855 Basic \fBread\fR\|(2) or \fBwrite\fR\|(2) I/O.  \fBfseek\fR\|(2) is used to
856 position the I/O location.
857 .TP
858 .B psync
859 Basic \fBpread\fR\|(2) or \fBpwrite\fR\|(2) I/O.
860 Default on all supported operating systems except for Windows.
861 .TP
862 .B vsync
863 Basic \fBreadv\fR\|(2) or \fBwritev\fR\|(2) I/O. Will emulate queuing by
864 coalescing adjacent IOs into a single submission.
865 .TP
866 .B pvsync
867 Basic \fBpreadv\fR\|(2) or \fBpwritev\fR\|(2) I/O.
868 .TP
869 .B pvsync2
870 Basic \fBpreadv2\fR\|(2) or \fBpwritev2\fR\|(2) I/O.
871 .TP
872 .B libaio
873 Linux native asynchronous I/O. This ioengine defines engine specific options.
874 .TP
875 .B posixaio
876 POSIX asynchronous I/O using \fBaio_read\fR\|(3) and \fBaio_write\fR\|(3).
877 .TP
878 .B solarisaio
879 Solaris native asynchronous I/O.
880 .TP
881 .B windowsaio
882 Windows native asynchronous I/O. Default on Windows.
883 .TP
884 .B mmap
885 File is memory mapped with \fBmmap\fR\|(2) and data copied using
886 \fBmemcpy\fR\|(3).
887 .TP
888 .B splice
889 \fBsplice\fR\|(2) is used to transfer the data and \fBvmsplice\fR\|(2) to
890 transfer data from user-space to the kernel.
891 .TP
892 .B sg
893 SCSI generic sg v3 I/O. May be either synchronous using the SG_IO ioctl, or if
894 the target is an sg character device, we use \fBread\fR\|(2) and
895 \fBwrite\fR\|(2) for asynchronous I/O.
896 .TP
897 .B null
898 Doesn't transfer any data, just pretends to.  Mainly used to exercise \fBfio\fR
899 itself and for debugging and testing purposes.
900 .TP
901 .B net
902 Transfer over the network.  The protocol to be used can be defined with the
903 \fBprotocol\fR parameter.  Depending on the protocol, \fBfilename\fR,
904 \fBhostname\fR, \fBport\fR, or \fBlisten\fR must be specified.
905 This ioengine defines engine specific options.
906 .TP
907 .B netsplice
908 Like \fBnet\fR, but uses \fBsplice\fR\|(2) and \fBvmsplice\fR\|(2) to map data
909 and send/receive. This ioengine defines engine specific options.
910 .TP
911 .B cpuio
912 Doesn't transfer any data, but burns CPU cycles according to \fBcpuload\fR and
913 \fBcpuchunks\fR parameters. A job never finishes unless there is at least one
914 non-cpuio job.
915 .TP
916 .B guasi
917 The GUASI I/O engine is the Generic Userspace Asynchronous Syscall Interface
918 approach to asynchronous I/O.
919 .br
920 See <http://www.xmailserver.org/guasi\-lib.html>.
921 .TP
922 .B rdma
923 The RDMA I/O engine supports both RDMA memory semantics (RDMA_WRITE/RDMA_READ)
924 and channel semantics (Send/Recv) for the InfiniBand, RoCE and iWARP protocols.
925 .TP
926 .B external
927 Loads an external I/O engine object file.  Append the engine filename as
928 `:\fIenginepath\fR'.
929 .TP
930 .B falloc
931    IO engine that does regular linux native fallocate call to simulate data
932 transfer as fio ioengine
933 .br
934   DDIR_READ  does fallocate(,mode = FALLOC_FL_KEEP_SIZE,)
935 .br
936   DIR_WRITE does fallocate(,mode = 0)
937 .br
938   DDIR_TRIM does fallocate(,mode = FALLOC_FL_KEEP_SIZE|FALLOC_FL_PUNCH_HOLE)
939 .TP
940 .B e4defrag
941 IO engine that does regular EXT4_IOC_MOVE_EXT ioctls to simulate defragment activity
942 request to DDIR_WRITE event
943 .TP
944 .B rbd
945 IO engine supporting direct access to Ceph Rados Block Devices (RBD) via librbd
946 without the need to use the kernel rbd driver. This ioengine defines engine specific
947 options.
948 .TP
949 .B gfapi
950 Using Glusterfs libgfapi sync interface to direct access to Glusterfs volumes without
951 having to go through FUSE. This ioengine defines engine specific
952 options.
953 .TP
954 .B gfapi_async
955 Using Glusterfs libgfapi async interface to direct access to Glusterfs volumes without
956 having to go through FUSE. This ioengine defines engine specific
957 options.
958 .TP
959 .B libhdfs
960 Read and write through Hadoop (HDFS).  The \fBfilename\fR option is used to
961 specify host,port of the hdfs name-node to connect. This engine interprets
962 offsets a little differently. In HDFS, files once created cannot be modified.
963 So random writes are not possible. To imitate this, libhdfs engine expects
964 bunch of small files to be created over HDFS, and engine will randomly pick a
965 file out of those files based on the offset generated by fio backend. (see the
966 example job file to create such files, use rw=write option). Please note, you
967 might want to set necessary environment variables to work with hdfs/libhdfs
968 properly.
969 .TP
970 .B mtd
971 Read, write and erase an MTD character device (e.g., /dev/mtd0). Discards are
972 treated as erases. Depending on the underlying device type, the I/O may have
973 to go in a certain pattern, e.g., on NAND, writing sequentially to erase blocks
974 and discarding before overwriting. The trimwrite mode works well for this
975 constraint.
976 .TP
977 .B pmemblk
978 Read and write using filesystem DAX to a file on a filesystem mounted with
979 DAX on a persistent memory device through the NVML libpmemblk library.
980 .TP
981 .B dev-dax
982 Read and write using device DAX to a persistent memory device
983 (e.g., /dev/dax0.0) through the NVML libpmem library.
984 .RE
985 .P
986 .RE
987 .TP
988 .BI iodepth \fR=\fPint
989 Number of I/O units to keep in flight against the file. Note that increasing
990 iodepth beyond 1 will not affect synchronous ioengines (except for small
991 degress when verify_async is in use). Even async engines may impose OS
992 restrictions causing the desired depth not to be achieved.  This may happen on
993 Linux when using libaio and not setting \fBdirect\fR=1, since buffered IO is
994 not async on that OS. Keep an eye on the IO depth distribution in the
995 fio output to verify that the achieved depth is as expected. Default: 1.
996 .TP
997 .BI iodepth_batch \fR=\fPint "\fR,\fP iodepth_batch_submit" \fR=\fPint
998 This defines how many pieces of IO to submit at once. It defaults to 1
999 which means that we submit each IO as soon as it is available, but can
1000 be raised to submit bigger batches of IO at the time. If it is set to 0
1001 the \fBiodepth\fR value will be used.
1002 .TP
1003 .BI iodepth_batch_complete_min \fR=\fPint "\fR,\fP iodepth_batch_complete" \fR=\fPint
1004 This defines how many pieces of IO to retrieve at once. It defaults to 1 which
1005  means that we'll ask for a minimum of 1 IO in the retrieval process from the
1006 kernel. The IO retrieval will go on until we hit the limit set by
1007 \fBiodepth_low\fR. If this variable is set to 0, then fio will always check for
1008 completed events before queuing more IO. This helps reduce IO latency, at the
1009 cost of more retrieval system calls.
1010 .TP
1011 .BI iodepth_batch_complete_max \fR=\fPint
1012 This defines maximum pieces of IO to
1013 retrieve at once. This variable should be used along with
1014 \fBiodepth_batch_complete_min\fR=int variable, specifying the range
1015 of min and max amount of IO which should be retrieved. By default
1016 it is equal to \fBiodepth_batch_complete_min\fR value.
1017
1018 Example #1:
1019 .RS
1020 .RS
1021 \fBiodepth_batch_complete_min\fR=1
1022 .LP
1023 \fBiodepth_batch_complete_max\fR=<iodepth>
1024 .RE
1025
1026 which means that we will retrieve at least 1 IO and up to the
1027 whole submitted queue depth. If none of IO has been completed
1028 yet, we will wait.
1029
1030 Example #2:
1031 .RS
1032 \fBiodepth_batch_complete_min\fR=0
1033 .LP
1034 \fBiodepth_batch_complete_max\fR=<iodepth>
1035 .RE
1036
1037 which means that we can retrieve up to the whole submitted
1038 queue depth, but if none of IO has been completed yet, we will
1039 NOT wait and immediately exit the system call. In this example
1040 we simply do polling.
1041 .RE
1042 .TP
1043 .BI iodepth_low \fR=\fPint
1044 Low watermark indicating when to start filling the queue again.  Default:
1045 \fBiodepth\fR.
1046 .TP
1047 .BI io_submit_mode \fR=\fPstr
1048 This option controls how fio submits the IO to the IO engine. The default is
1049 \fBinline\fR, which means that the fio job threads submit and reap IO directly.
1050 If set to \fBoffload\fR, the job threads will offload IO submission to a
1051 dedicated pool of IO threads. This requires some coordination and thus has a
1052 bit of extra overhead, especially for lower queue depth IO where it can
1053 increase latencies. The benefit is that fio can manage submission rates
1054 independently of the device completion rates. This avoids skewed latency
1055 reporting if IO gets back up on the device side (the coordinated omission
1056 problem).
1057 .TP
1058 .BI direct \fR=\fPbool
1059 If true, use non-buffered I/O (usually O_DIRECT).  Default: false.
1060 .TP
1061 .BI atomic \fR=\fPbool
1062 If value is true, attempt to use atomic direct IO. Atomic writes are guaranteed
1063 to be stable once acknowledged by the operating system. Only Linux supports
1064 O_ATOMIC right now.
1065 .TP
1066 .BI buffered \fR=\fPbool
1067 If true, use buffered I/O.  This is the opposite of the \fBdirect\fR parameter.
1068 Default: true.
1069 .TP
1070 .BI offset \fR=\fPint
1071 Start I/O at the provided offset in the file, given as either a fixed size in
1072 bytes or a percentage. If a percentage is given, the next \fBblockalign\fR-ed
1073 offset will be used. Data before the given offset will not be touched. This
1074 effectively caps the file size at (real_size - offset). Can be combined with
1075 \fBsize\fR to constrain the start and end range of the I/O workload. A percentage
1076 can be specified by a number between 1 and 100 followed by '%', for example,
1077 offset=20% to specify 20%.
1078 .TP
1079 .BI offset_increment \fR=\fPint
1080 If this is provided, then the real offset becomes the
1081 offset + offset_increment * thread_number, where the thread number is a
1082 counter that starts at 0 and is incremented for each sub-job (i.e. when
1083 numjobs option is specified). This option is useful if there are several jobs
1084 which are intended to operate on a file in parallel disjoint segments, with
1085 even spacing between the starting points.
1086 .TP
1087 .BI number_ios \fR=\fPint
1088 Fio will normally perform IOs until it has exhausted the size of the region
1089 set by \fBsize\fR, or if it exhaust the allocated time (or hits an error
1090 condition). With this setting, the range/size can be set independently of
1091 the number of IOs to perform. When fio reaches this number, it will exit
1092 normally and report status. Note that this does not extend the amount
1093 of IO that will be done, it will only stop fio if this condition is met
1094 before other end-of-job criteria.
1095 .TP
1096 .BI fsync \fR=\fPint
1097 How many I/Os to perform before issuing an \fBfsync\fR\|(2) of dirty data.  If
1098 0, don't sync.  Default: 0.
1099 .TP
1100 .BI fdatasync \fR=\fPint
1101 Like \fBfsync\fR, but uses \fBfdatasync\fR\|(2) instead to only sync the
1102 data parts of the file. Default: 0.
1103 .TP
1104 .BI write_barrier \fR=\fPint
1105 Make every Nth write a barrier write.
1106 .TP
1107 .BI sync_file_range \fR=\fPstr:int
1108 Use \fBsync_file_range\fR\|(2) for every \fRval\fP number of write operations. Fio will
1109 track range of writes that have happened since the last \fBsync_file_range\fR\|(2) call.
1110 \fRstr\fP can currently be one or more of:
1111 .RS
1112 .TP
1113 .B wait_before
1114 SYNC_FILE_RANGE_WAIT_BEFORE
1115 .TP
1116 .B write
1117 SYNC_FILE_RANGE_WRITE
1118 .TP
1119 .B wait_after
1120 SYNC_FILE_RANGE_WAIT_AFTER
1121 .TP
1122 .RE
1123 .P
1124 So if you do sync_file_range=wait_before,write:8, fio would use
1125 \fBSYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE\fP for every 8 writes.
1126 Also see the \fBsync_file_range\fR\|(2) man page.  This option is Linux specific.
1127 .TP
1128 .BI overwrite \fR=\fPbool
1129 If writing, setup the file first and do overwrites.  Default: false.
1130 .TP
1131 .BI end_fsync \fR=\fPbool
1132 Sync file contents when a write stage has completed.  Default: false.
1133 .TP
1134 .BI fsync_on_close \fR=\fPbool
1135 If true, sync file contents on close.  This differs from \fBend_fsync\fR in that
1136 it will happen on every close, not just at the end of the job.  Default: false.
1137 .TP
1138 .BI rwmixread \fR=\fPint
1139 Percentage of a mixed workload that should be reads. Default: 50.
1140 .TP
1141 .BI rwmixwrite \fR=\fPint
1142 Percentage of a mixed workload that should be writes.  If \fBrwmixread\fR and
1143 \fBrwmixwrite\fR are given and do not sum to 100%, the latter of the two
1144 overrides the first. This may interfere with a given rate setting, if fio is
1145 asked to limit reads or writes to a certain rate. If that is the case, then
1146 the distribution may be skewed. Default: 50.
1147 .TP
1148 .BI random_distribution \fR=\fPstr:float
1149 By default, fio will use a completely uniform random distribution when asked
1150 to perform random IO. Sometimes it is useful to skew the distribution in
1151 specific ways, ensuring that some parts of the data is more hot than others.
1152 Fio includes the following distribution models:
1153 .RS
1154 .TP
1155 .B random
1156 Uniform random distribution
1157 .TP
1158 .B zipf
1159 Zipf distribution
1160 .TP
1161 .B pareto
1162 Pareto distribution
1163 .TP
1164 .B normal
1165 Normal (Gaussian) distribution
1166 .TP
1167 .B zoned
1168 Zoned random distribution
1169 .TP
1170 .RE
1171 When using a \fBzipf\fR or \fBpareto\fR distribution, an input value is also
1172 needed to define the access pattern. For \fBzipf\fR, this is the zipf theta.
1173 For \fBpareto\fR, it's the pareto power. Fio includes a test program, genzipf,
1174 that can be used visualize what the given input values will yield in terms of
1175 hit rates. If you wanted to use \fBzipf\fR with a theta of 1.2, you would use
1176 random_distribution=zipf:1.2 as the option. If a non-uniform model is used,
1177 fio will disable use of the random map. For the \fBnormal\fR distribution, a
1178 normal (Gaussian) deviation is supplied as a value between 0 and 100.
1179 .P
1180 .RS
1181 For a \fBzoned\fR distribution, fio supports specifying percentages of IO
1182 access that should fall within what range of the file or device. For example,
1183 given a criteria of:
1184 .P
1185 .RS
1186 60% of accesses should be to the first 10%
1187 .RE
1188 .RS
1189 30% of accesses should be to the next 20%
1190 .RE
1191 .RS
1192 8% of accesses should be to the next 30%
1193 .RE
1194 .RS
1195 2% of accesses should be to the next 40%
1196 .RE
1197 .P
1198 we can define that through zoning of the random accesses. For the above
1199 example, the user would do:
1200 .P
1201 .RS
1202 .B random_distribution=zoned:60/10:30/20:8/30:2/40
1203 .RE
1204 .P
1205 similarly to how \fBbssplit\fR works for setting ranges and percentages of block
1206 sizes. Like \fBbssplit\fR, it's possible to specify separate zones for reads,
1207 writes, and trims. If just one set is given, it'll apply to all of them.
1208 .RE
1209 .TP
1210 .BI percentage_random \fR=\fPint[,int][,int]
1211 For a random workload, set how big a percentage should be random. This defaults
1212 to 100%, in which case the workload is fully random. It can be set from
1213 anywhere from 0 to 100.  Setting it to 0 would make the workload fully
1214 sequential. It is possible to set different values for reads, writes, and
1215 trim. To do so, simply use a comma separated list. See \fBblocksize\fR.
1216 .TP
1217 .B norandommap
1218 Normally \fBfio\fR will cover every block of the file when doing random I/O. If
1219 this parameter is given, a new offset will be chosen without looking at past
1220 I/O history.  This parameter is mutually exclusive with \fBverify\fR.
1221 .TP
1222 .BI softrandommap \fR=\fPbool
1223 See \fBnorandommap\fR. If fio runs with the random block map enabled and it
1224 fails to allocate the map, if this option is set it will continue without a
1225 random block map. As coverage will not be as complete as with random maps, this
1226 option is disabled by default.
1227 .TP
1228 .BI random_generator \fR=\fPstr
1229 Fio supports the following engines for generating IO offsets for random IO:
1230 .RS
1231 .TP
1232 .B tausworthe
1233 Strong 2^88 cycle random number generator
1234 .TP
1235 .B lfsr
1236 Linear feedback shift register generator
1237 .TP
1238 .B tausworthe64
1239 Strong 64-bit 2^258 cycle random number generator
1240 .TP
1241 .RE
1242 .P
1243 Tausworthe is a strong random number generator, but it requires tracking on the
1244 side if we want to ensure that blocks are only read or written once. LFSR
1245 guarantees that we never generate the same offset twice, and it's also less
1246 computationally expensive. It's not a true random generator, however, though
1247 for IO purposes it's typically good enough. LFSR only works with single block
1248 sizes, not with workloads that use multiple block sizes. If used with such a
1249 workload, fio may read or write some blocks multiple times. The default
1250 value is tausworthe, unless the required space exceeds 2^32 blocks. If it does,
1251 then tausworthe64 is selected automatically.
1252 .TP
1253 .BI nice \fR=\fPint
1254 Run job with given nice value.  See \fBnice\fR\|(2).
1255 .TP
1256 .BI prio \fR=\fPint
1257 Set I/O priority value of this job between 0 (highest) and 7 (lowest).  See
1258 \fBionice\fR\|(1).
1259 .TP
1260 .BI prioclass \fR=\fPint
1261 Set I/O priority class.  See \fBionice\fR\|(1).
1262 .TP
1263 .BI thinktime \fR=\fPint
1264 Stall job for given number of microseconds between issuing I/Os.
1265 .TP
1266 .BI thinktime_spin \fR=\fPint
1267 Pretend to spend CPU time for given number of microseconds, sleeping the rest
1268 of the time specified by \fBthinktime\fR.  Only valid if \fBthinktime\fR is set.
1269 .TP
1270 .BI thinktime_blocks \fR=\fPint
1271 Only valid if thinktime is set - control how many blocks to issue, before
1272 waiting \fBthinktime\fR microseconds. If not set, defaults to 1 which will
1273 make fio wait \fBthinktime\fR microseconds after every block. This
1274 effectively makes any queue depth setting redundant, since no more than 1 IO
1275 will be queued before we have to complete it and do our thinktime. In other
1276 words, this setting effectively caps the queue depth if the latter is larger.
1277 Default: 1.
1278 .TP
1279 .BI rate \fR=\fPint[,int][,int]
1280 Cap bandwidth used by this job. The number is in bytes/sec, the normal postfix
1281 rules apply. You can use \fBrate\fR=500k to limit reads and writes to 500k each,
1282 or you can specify reads, write, and trim limits separately.
1283 Using \fBrate\fR=1m,500k would
1284 limit reads to 1MiB/sec and writes to 500KiB/sec. Capping only reads or writes
1285 can be done with \fBrate\fR=,500k or \fBrate\fR=500k,. The former will only
1286 limit writes (to 500KiB/sec), the latter will only limit reads.
1287 .TP
1288 .BI rate_min \fR=\fPint[,int][,int]
1289 Tell \fBfio\fR to do whatever it can to maintain at least the given bandwidth.
1290 Failing to meet this requirement will cause the job to exit. The same format
1291 as \fBrate\fR is used for read vs write vs trim separation.
1292 .TP
1293 .BI rate_iops \fR=\fPint[,int][,int]
1294 Cap the bandwidth to this number of IOPS. Basically the same as rate, just
1295 specified independently of bandwidth. The same format as \fBrate\fR is used for
1296 read vs write vs trim separation. If \fBblocksize\fR is a range, the smallest block
1297 size is used as the metric.
1298 .TP
1299 .BI rate_iops_min \fR=\fPint[,int][,int]
1300 If this rate of I/O is not met, the job will exit. The same format as \fBrate\fR
1301 is used for read vs write vs trim separation.
1302 .TP
1303 .BI rate_process \fR=\fPstr
1304 This option controls how fio manages rated IO submissions. The default is
1305 \fBlinear\fR, which submits IO in a linear fashion with fixed delays between
1306 IOs that gets adjusted based on IO completion rates. If this is set to
1307 \fBpoisson\fR, fio will submit IO based on a more real world random request
1308 flow, known as the Poisson process
1309 (https://en.wikipedia.org/wiki/Poisson_process). The lambda will be
1310 10^6 / IOPS for the given workload.
1311 .TP
1312 .BI rate_cycle \fR=\fPint
1313 Average bandwidth for \fBrate\fR and \fBrate_min\fR over this number of
1314 milliseconds.  Default: 1000ms.
1315 .TP
1316 .BI latency_target \fR=\fPint
1317 If set, fio will attempt to find the max performance point that the given
1318 workload will run at while maintaining a latency below this target. The
1319 values is given in microseconds. See \fBlatency_window\fR and
1320 \fBlatency_percentile\fR.
1321 .TP
1322 .BI latency_window \fR=\fPint
1323 Used with \fBlatency_target\fR to specify the sample window that the job
1324 is run at varying queue depths to test the performance. The value is given
1325 in microseconds.
1326 .TP
1327 .BI latency_percentile \fR=\fPfloat
1328 The percentage of IOs that must fall within the criteria specified by
1329 \fBlatency_target\fR and \fBlatency_window\fR. If not set, this defaults
1330 to 100.0, meaning that all IOs must be equal or below to the value set
1331 by \fBlatency_target\fR.
1332 .TP
1333 .BI max_latency \fR=\fPint
1334 If set, fio will exit the job if it exceeds this maximum latency. It will exit
1335 with an ETIME error.
1336 .TP
1337 .BI cpumask \fR=\fPint
1338 Set CPU affinity for this job. \fIint\fR is a bitmask of allowed CPUs the job
1339 may run on.  See \fBsched_setaffinity\fR\|(2).
1340 .TP
1341 .BI cpus_allowed \fR=\fPstr
1342 Same as \fBcpumask\fR, but allows a comma-delimited list of CPU numbers.
1343 .TP
1344 .BI cpus_allowed_policy \fR=\fPstr
1345 Set the policy of how fio distributes the CPUs specified by \fBcpus_allowed\fR
1346 or \fBcpumask\fR. Two policies are supported:
1347 .RS
1348 .RS
1349 .TP
1350 .B shared
1351 All jobs will share the CPU set specified.
1352 .TP
1353 .B split
1354 Each job will get a unique CPU from the CPU set.
1355 .RE
1356 .P
1357 \fBshared\fR is the default behaviour, if the option isn't specified. If
1358 \fBsplit\fR is specified, then fio will assign one cpu per job. If not enough
1359 CPUs are given for the jobs listed, then fio will roundrobin the CPUs in
1360 the set.
1361 .RE
1362 .P
1363 .TP
1364 .BI numa_cpu_nodes \fR=\fPstr
1365 Set this job running on specified NUMA nodes' CPUs. The arguments allow
1366 comma delimited list of cpu numbers, A-B ranges, or 'all'.
1367 .TP
1368 .BI numa_mem_policy \fR=\fPstr
1369 Set this job's memory policy and corresponding NUMA nodes. Format of
1370 the arguments:
1371 .RS
1372 .TP
1373 .B <mode>[:<nodelist>]
1374 .TP
1375 .B mode
1376 is one of the following memory policy:
1377 .TP
1378 .B default, prefer, bind, interleave, local
1379 .TP
1380 .RE
1381 For \fBdefault\fR and \fBlocal\fR memory policy, no \fBnodelist\fR is
1382 needed to be specified. For \fBprefer\fR, only one node is
1383 allowed. For \fBbind\fR and \fBinterleave\fR, \fBnodelist\fR allows
1384 comma delimited list of numbers, A-B ranges, or 'all'.
1385 .TP
1386 .BI startdelay \fR=\fPirange
1387 Delay start of job for the specified number of seconds. Supports all time
1388 suffixes to allow specification of hours, minutes, seconds and
1389 milliseconds - seconds are the default if a unit is omitted.
1390 Can be given as a range which causes each thread to choose randomly out of the
1391 range.
1392 .TP
1393 .BI runtime \fR=\fPint
1394 Terminate processing after the specified number of seconds.
1395 .TP
1396 .B time_based
1397 If given, run for the specified \fBruntime\fR duration even if the files are
1398 completely read or written. The same workload will be repeated as many times
1399 as \fBruntime\fR allows.
1400 .TP
1401 .BI ramp_time \fR=\fPint
1402 If set, fio will run the specified workload for this amount of time before
1403 logging any performance numbers. Useful for letting performance settle before
1404 logging results, thus minimizing the runtime required for stable results. Note
1405 that the \fBramp_time\fR is considered lead in time for a job, thus it will
1406 increase the total runtime if a special timeout or runtime is specified.
1407 .TP
1408 .BI steadystate \fR=\fPstr:float "\fR,\fP ss" \fR=\fPstr:float
1409 Define the criterion and limit for assessing steady state performance. The
1410 first parameter designates the criterion whereas the second parameter sets the
1411 threshold. When the criterion falls below the threshold for the specified
1412 duration, the job will stop. For example, iops_slope:0.1% will direct fio
1413 to terminate the job when the least squares regression slope falls below 0.1%
1414 of the mean IOPS. If group_reporting is enabled this will apply to all jobs in
1415 the group. All assessments are carried out using only data from the rolling
1416 collection window. Threshold limits can be expressed as a fixed value or as a
1417 percentage of the mean in the collection window. Below are the available steady
1418 state assessment criteria.
1419 .RS
1420 .RS
1421 .TP
1422 .B iops
1423 Collect IOPS data. Stop the job if all individual IOPS measurements are within
1424 the specified limit of the mean IOPS (e.g., iops:2 means that all individual
1425 IOPS values must be within 2 of the mean, whereas iops:0.2% means that all
1426 individual IOPS values must be within 0.2% of the mean IOPS to terminate the
1427 job).
1428 .TP
1429 .B iops_slope
1430 Collect IOPS data and calculate the least squares regression slope. Stop the
1431 job if the slope falls below the specified limit.
1432 .TP
1433 .B bw
1434 Collect bandwidth data. Stop the job if all individual bandwidth measurements
1435 are within the specified limit of the mean bandwidth.
1436 .TP
1437 .B bw_slope
1438 Collect bandwidth data and calculate the least squares regression slope. Stop
1439 the job if the slope falls below the specified limit.
1440 .RE
1441 .RE
1442 .TP
1443 .BI steadystate_duration \fR=\fPtime "\fR,\fP ss_dur" \fR=\fPtime
1444 A rolling window of this duration will be used to judge whether steady state
1445 has been reached. Data will be collected once per second. The default is 0
1446 which disables steady state detection.
1447 .TP
1448 .BI steadystate_ramp_time \fR=\fPtime "\fR,\fP ss_ramp" \fR=\fPtime
1449 Allow the job to run for the specified duration before beginning data collection
1450 for checking the steady state job termination criterion. The default is 0.
1451 .TP
1452 .BI invalidate \fR=\fPbool
1453 Invalidate buffer-cache for the file prior to starting I/O.  Default: true.
1454 .TP
1455 .BI sync \fR=\fPbool
1456 Use synchronous I/O for buffered writes.  For the majority of I/O engines,
1457 this means using O_SYNC.  Default: false.
1458 .TP
1459 .BI iomem \fR=\fPstr "\fR,\fP mem" \fR=\fPstr
1460 Allocation method for I/O unit buffer.  Allowed values are:
1461 .RS
1462 .RS
1463 .TP
1464 .B malloc
1465 Allocate memory with \fBmalloc\fR\|(3). Default memory type.
1466 .TP
1467 .B shm
1468 Use shared memory buffers allocated through \fBshmget\fR\|(2).
1469 .TP
1470 .B shmhuge
1471 Same as \fBshm\fR, but use huge pages as backing.
1472 .TP
1473 .B mmap
1474 Use \fBmmap\fR\|(2) for allocation.  Uses anonymous memory unless a filename
1475 is given after the option in the format `:\fIfile\fR'.
1476 .TP
1477 .B mmaphuge
1478 Same as \fBmmap\fR, but use huge files as backing.
1479 .TP
1480 .B mmapshared
1481 Same as \fBmmap\fR, but use a MMAP_SHARED mapping.
1482 .TP
1483 .B cudamalloc
1484 Use GPU memory as the buffers for GPUDirect RDMA benchmark. The ioengine must be \fBrdma\fR.
1485 .RE
1486 .P
1487 The amount of memory allocated is the maximum allowed \fBblocksize\fR for the
1488 job multiplied by \fBiodepth\fR.  For \fBshmhuge\fR or \fBmmaphuge\fR to work,
1489 the system must have free huge pages allocated.  \fBmmaphuge\fR also needs to
1490 have hugetlbfs mounted, and \fIfile\fR must point there. At least on Linux,
1491 huge pages must be manually allocated. See \fB/proc/sys/vm/nr_hugehages\fR
1492 and the documentation for that. Normally you just need to echo an appropriate
1493 number, eg echoing 8 will ensure that the OS has 8 huge pages ready for
1494 use.
1495 .RE
1496 .TP
1497 .BI iomem_align \fR=\fPint "\fR,\fP mem_align" \fR=\fPint
1498 This indicates the memory alignment of the IO memory buffers. Note that the
1499 given alignment is applied to the first IO unit buffer, if using \fBiodepth\fR
1500 the alignment of the following buffers are given by the \fBbs\fR used. In
1501 other words, if using a \fBbs\fR that is a multiple of the page sized in the
1502 system, all buffers will be aligned to this value. If using a \fBbs\fR that
1503 is not page aligned, the alignment of subsequent IO memory buffers is the
1504 sum of the \fBiomem_align\fR and \fBbs\fR used.
1505 .TP
1506 .BI hugepage\-size \fR=\fPint
1507 Defines the size of a huge page.  Must be at least equal to the system setting.
1508 Should be a multiple of 1MiB. Default: 4MiB.
1509 .TP
1510 .B exitall
1511 Terminate all jobs when one finishes.  Default: wait for each job to finish.
1512 .TP
1513 .B exitall_on_error \fR=\fPbool
1514 Terminate all jobs if one job finishes in error.  Default: wait for each job
1515 to finish.
1516 .TP
1517 .BI bwavgtime \fR=\fPint
1518 Average bandwidth calculations over the given time in milliseconds. If the job
1519 also does bandwidth logging through \fBwrite_bw_log\fR, then the minimum of
1520 this option and \fBlog_avg_msec\fR will be used.  Default: 500ms.
1521 .TP
1522 .BI iopsavgtime \fR=\fPint
1523 Average IOPS calculations over the given time in milliseconds. If the job
1524 also does IOPS logging through \fBwrite_iops_log\fR, then the minimum of
1525 this option and \fBlog_avg_msec\fR will be used.  Default: 500ms.
1526 .TP
1527 .BI create_serialize \fR=\fPbool
1528 If true, serialize file creation for the jobs.  Default: true.
1529 .TP
1530 .BI create_fsync \fR=\fPbool
1531 \fBfsync\fR\|(2) data file after creation.  Default: true.
1532 .TP
1533 .BI create_on_open \fR=\fPbool
1534 If true, the files are not created until they are opened for IO by the job.
1535 .TP
1536 .BI create_only \fR=\fPbool
1537 If true, fio will only run the setup phase of the job. If files need to be
1538 laid out or updated on disk, only that will be done. The actual job contents
1539 are not executed.
1540 .TP
1541 .BI allow_file_create \fR=\fPbool
1542 If true, fio is permitted to create files as part of its workload. This is
1543 the default behavior. If this option is false, then fio will error out if the
1544 files it needs to use don't already exist. Default: true.
1545 .TP
1546 .BI allow_mounted_write \fR=\fPbool
1547 If this isn't set, fio will abort jobs that are destructive (eg that write)
1548 to what appears to be a mounted device or partition. This should help catch
1549 creating inadvertently destructive tests, not realizing that the test will
1550 destroy data on the mounted file system. Default: false.
1551 .TP
1552 .BI pre_read \fR=\fPbool
1553 If this is given, files will be pre-read into memory before starting the given
1554 IO operation. This will also clear the \fR \fBinvalidate\fR flag, since it is
1555 pointless to pre-read and then drop the cache. This will only work for IO
1556 engines that are seekable, since they allow you to read the same data
1557 multiple times. Thus it will not work on eg network or splice IO.
1558 .TP
1559 .BI unlink \fR=\fPbool
1560 Unlink job files when done.  Default: false.
1561 .TP
1562 .BI unlink_each_loop \fR=\fPbool
1563 Unlink job files after each iteration or loop.  Default: false.
1564 .TP
1565 .BI loops \fR=\fPint
1566 Specifies the number of iterations (runs of the same workload) of this job.
1567 Default: 1.
1568 .TP
1569 .BI verify_only \fR=\fPbool
1570 Do not perform the specified workload, only verify data still matches previous
1571 invocation of this workload. This option allows one to check data multiple
1572 times at a later date without overwriting it. This option makes sense only for
1573 workloads that write data, and does not support workloads with the
1574 \fBtime_based\fR option set.
1575 .TP
1576 .BI do_verify \fR=\fPbool
1577 Run the verify phase after a write phase.  Only valid if \fBverify\fR is set.
1578 Default: true.
1579 .TP
1580 .BI verify \fR=\fPstr
1581 Method of verifying file contents after each iteration of the job. Each
1582 verification method also implies verification of special header, which is
1583 written to the beginning of each block. This header also includes meta
1584 information, like offset of the block, block number, timestamp when block
1585 was written, etc.  \fBverify\fR=str can be combined with \fBverify_pattern\fR=str
1586 option.  The allowed values are:
1587 .RS
1588 .RS
1589 .TP
1590 .B md5 crc16 crc32 crc32c crc32c-intel crc64 crc7 sha256 sha512 sha1 sha3-224 sha3-256 sha3-384 sha3-512 xxhash
1591 Store appropriate checksum in the header of each block. crc32c-intel is
1592 hardware accelerated SSE4.2 driven, falls back to regular crc32c if
1593 not supported by the system.
1594 .TP
1595 .B meta
1596 This option is deprecated, since now meta information is included in generic
1597 verification header and meta verification happens by default.  For detailed
1598 information see the description of the \fBverify\fR=str setting. This option
1599 is kept because of compatibility's sake with old configurations. Do not use it.
1600 .TP
1601 .B pattern
1602 Verify a strict pattern. Normally fio includes a header with some basic
1603 information and checksumming, but if this option is set, only the
1604 specific pattern set with \fBverify_pattern\fR is verified.
1605 .TP
1606 .B null
1607 Pretend to verify.  Used for testing internals.
1608 .RE
1609
1610 This option can be used for repeated burn-in tests of a system to make sure
1611 that the written data is also correctly read back. If the data direction given
1612 is a read or random read, fio will assume that it should verify a previously
1613 written file. If the data direction includes any form of write, the verify will
1614 be of the newly written data.
1615 .RE
1616 .TP
1617 .BI verifysort \fR=\fPbool
1618 If true, written verify blocks are sorted if \fBfio\fR deems it to be faster to
1619 read them back in a sorted manner.  Default: true.
1620 .TP
1621 .BI verifysort_nr \fR=\fPint
1622 Pre-load and sort verify blocks for a read workload.
1623 .TP
1624 .BI verify_offset \fR=\fPint
1625 Swap the verification header with data somewhere else in the block before
1626 writing.  It is swapped back before verifying.
1627 .TP
1628 .BI verify_interval \fR=\fPint
1629 Write the verification header for this number of bytes, which should divide
1630 \fBblocksize\fR.  Default: \fBblocksize\fR.
1631 .TP
1632 .BI verify_pattern \fR=\fPstr
1633 If set, fio will fill the io buffers with this pattern. Fio defaults to filling
1634 with totally random bytes, but sometimes it's interesting to fill with a known
1635 pattern for io verification purposes. Depending on the width of the pattern,
1636 fio will fill 1/2/3/4 bytes of the buffer at the time(it can be either a
1637 decimal or a hex number). The verify_pattern if larger than a 32-bit quantity
1638 has to be a hex number that starts with either "0x" or "0X". Use with
1639 \fBverify\fP=str. Also, verify_pattern supports %o format, which means that for
1640 each block offset will be written and then verified back, e.g.:
1641 .RS
1642 .RS
1643 \fBverify_pattern\fR=%o
1644 .RE
1645 Or use combination of everything:
1646 .LP
1647 .RS
1648 \fBverify_pattern\fR=0xff%o"abcd"-21
1649 .RE
1650 .RE
1651 .TP
1652 .BI verify_fatal \fR=\fPbool
1653 If true, exit the job on the first observed verification failure.  Default:
1654 false.
1655 .TP
1656 .BI verify_dump \fR=\fPbool
1657 If set, dump the contents of both the original data block and the data block we
1658 read off disk to files. This allows later analysis to inspect just what kind of
1659 data corruption occurred. Off by default.
1660 .TP
1661 .BI verify_async \fR=\fPint
1662 Fio will normally verify IO inline from the submitting thread. This option
1663 takes an integer describing how many async offload threads to create for IO
1664 verification instead, causing fio to offload the duty of verifying IO contents
1665 to one or more separate threads.  If using this offload option, even sync IO
1666 engines can benefit from using an \fBiodepth\fR setting higher than 1, as it
1667 allows them to have IO in flight while verifies are running.
1668 .TP
1669 .BI verify_async_cpus \fR=\fPstr
1670 Tell fio to set the given CPU affinity on the async IO verification threads.
1671 See \fBcpus_allowed\fP for the format used.
1672 .TP
1673 .BI verify_backlog \fR=\fPint
1674 Fio will normally verify the written contents of a job that utilizes verify
1675 once that job has completed. In other words, everything is written then
1676 everything is read back and verified. You may want to verify continually
1677 instead for a variety of reasons. Fio stores the meta data associated with an
1678 IO block in memory, so for large verify workloads, quite a bit of memory would
1679 be used up holding this meta data. If this option is enabled, fio will write
1680 only N blocks before verifying these blocks.
1681 .TP
1682 .BI verify_backlog_batch \fR=\fPint
1683 Control how many blocks fio will verify if verify_backlog is set. If not set,
1684 will default to the value of \fBverify_backlog\fR (meaning the entire queue is
1685 read back and verified).  If \fBverify_backlog_batch\fR is less than
1686 \fBverify_backlog\fR then not all blocks will be verified,  if
1687 \fBverify_backlog_batch\fR is larger than \fBverify_backlog\fR,  some blocks
1688 will be verified more than once.
1689 .TP
1690 .BI trim_percentage \fR=\fPint
1691 Number of verify blocks to discard/trim.
1692 .TP
1693 .BI trim_verify_zero \fR=\fPbool
1694 Verify that trim/discarded blocks are returned as zeroes.
1695 .TP
1696 .BI trim_backlog \fR=\fPint
1697 Trim after this number of blocks are written.
1698 .TP
1699 .BI trim_backlog_batch \fR=\fPint
1700 Trim this number of IO blocks.
1701 .TP
1702 .BI experimental_verify \fR=\fPbool
1703 Enable experimental verification.
1704 .TP
1705 .BI verify_state_save \fR=\fPbool
1706 When a job exits during the write phase of a verify workload, save its
1707 current state. This allows fio to replay up until that point, if the
1708 verify state is loaded for the verify read phase.
1709 .TP
1710 .BI verify_state_load \fR=\fPbool
1711 If a verify termination trigger was used, fio stores the current write
1712 state of each thread. This can be used at verification time so that fio
1713 knows how far it should verify. Without this information, fio will run
1714 a full verification pass, according to the settings in the job file used.
1715 .TP
1716 .B stonewall "\fR,\fP wait_for_previous"
1717 Wait for preceding jobs in the job file to exit before starting this one.
1718 \fBstonewall\fR implies \fBnew_group\fR.
1719 .TP
1720 .B new_group
1721 Start a new reporting group.  If not given, all jobs in a file will be part
1722 of the same reporting group, unless separated by a stonewall.
1723 .TP
1724 .BI stats \fR=\fPbool
1725 By default, fio collects and shows final output results for all jobs that run.
1726 If this option is set to 0, then fio will ignore it in the final stat output.
1727 .TP
1728 .BI numjobs \fR=\fPint
1729 Number of clones (processes/threads performing the same workload) of this job.
1730 Default: 1.
1731 .TP
1732 .B group_reporting
1733 If set, display per-group reports instead of per-job when \fBnumjobs\fR is
1734 specified.
1735 .TP
1736 .B thread
1737 Use threads created with \fBpthread_create\fR\|(3) instead of processes created
1738 with \fBfork\fR\|(2).
1739 .TP
1740 .BI zonesize \fR=\fPint
1741 Divide file into zones of the specified size in bytes.  See \fBzoneskip\fR.
1742 .TP
1743 .BI zonerange \fR=\fPint
1744 Give size of an IO zone.  See \fBzoneskip\fR.
1745 .TP
1746 .BI zoneskip \fR=\fPint
1747 Skip the specified number of bytes when \fBzonesize\fR bytes of data have been
1748 read.
1749 .TP
1750 .BI write_iolog \fR=\fPstr
1751 Write the issued I/O patterns to the specified file.  Specify a separate file
1752 for each job, otherwise the iologs will be interspersed and the file may be
1753 corrupt.
1754 .TP
1755 .BI read_iolog \fR=\fPstr
1756 Replay the I/O patterns contained in the specified file generated by
1757 \fBwrite_iolog\fR, or may be a \fBblktrace\fR binary file.
1758 .TP
1759 .BI replay_no_stall \fR=\fPint
1760 While replaying I/O patterns using \fBread_iolog\fR the default behavior
1761 attempts to respect timing information between I/Os.  Enabling
1762 \fBreplay_no_stall\fR causes I/Os to be replayed as fast as possible while
1763 still respecting ordering.
1764 .TP
1765 .BI replay_redirect \fR=\fPstr
1766 While replaying I/O patterns using \fBread_iolog\fR the default behavior
1767 is to replay the IOPS onto the major/minor device that each IOP was recorded
1768 from.  Setting \fBreplay_redirect\fR causes all IOPS to be replayed onto the
1769 single specified device regardless of the device it was recorded from.
1770 .TP
1771 .BI replay_align \fR=\fPint
1772 Force alignment of IO offsets and lengths in a trace to this power of 2 value.
1773 .TP
1774 .BI replay_scale \fR=\fPint
1775 Scale sector offsets down by this factor when replaying traces.
1776 .TP
1777 .BI per_job_logs \fR=\fPbool
1778 If set, this generates bw/clat/iops log with per file private filenames. If
1779 not set, jobs with identical names will share the log filename. Default: true.
1780 .TP
1781 .BI write_bw_log \fR=\fPstr
1782 If given, write a bandwidth log for this job. Can be used to store data of the
1783 bandwidth of the jobs in their lifetime. The included fio_generate_plots script
1784 uses gnuplot to turn these text files into nice graphs. See \fBwrite_lat_log\fR
1785 for behaviour of given filename. For this option, the postfix is _bw.x.log,
1786 where x is the index of the job (1..N, where N is the number of jobs). If
1787 \fBper_job_logs\fR is false, then the filename will not include the job index.
1788 See the \fBLOG FILE FORMATS\fR
1789 section.
1790 .TP
1791 .BI write_lat_log \fR=\fPstr
1792 Same as \fBwrite_bw_log\fR, but writes I/O completion latencies.  If no
1793 filename is given with this option, the default filename of
1794 "jobname_type.x.log" is used, where x is the index of the job (1..N, where
1795 N is the number of jobs). Even if the filename is given, fio will still
1796 append the type of log. If \fBper_job_logs\fR is false, then the filename will
1797 not include the job index. See the \fBLOG FILE FORMATS\fR section.
1798 .TP
1799 .BI write_hist_log \fR=\fPstr
1800 Same as \fBwrite_lat_log\fR, but writes I/O completion latency histograms. If
1801 no filename is given with this option, the default filename of
1802 "jobname_clat_hist.x.log" is used, where x is the index of the job (1..N, where
1803 N is the number of jobs). Even if the filename is given, fio will still append
1804 the type of log. If \fBper_job_logs\fR is false, then the filename will not
1805 include the job index. See the \fBLOG FILE FORMATS\fR section.
1806 .TP
1807 .BI write_iops_log \fR=\fPstr
1808 Same as \fBwrite_bw_log\fR, but writes IOPS. If no filename is given with this
1809 option, the default filename of "jobname_type.x.log" is used, where x is the
1810 index of the job (1..N, where N is the number of jobs). Even if the filename
1811 is given, fio will still append the type of log. If \fBper_job_logs\fR is false,
1812 then the filename will not include the job index. See the \fBLOG FILE FORMATS\fR
1813 section.
1814 .TP
1815 .BI log_avg_msec \fR=\fPint
1816 By default, fio will log an entry in the iops, latency, or bw log for every
1817 IO that completes. When writing to the disk log, that can quickly grow to a
1818 very large size. Setting this option makes fio average the each log entry
1819 over the specified period of time, reducing the resolution of the log. See
1820 \fBlog_max_value\fR as well.  Defaults to 0, logging all entries.
1821 .TP
1822 .BI log_max_value \fR=\fPbool
1823 If \fBlog_avg_msec\fR is set, fio logs the average over that window. If you
1824 instead want to log the maximum value, set this option to 1.  Defaults to
1825 0, meaning that averaged values are logged.
1826 .TP
1827 .BI log_hist_msec \fR=\fPint
1828 Same as \fBlog_avg_msec\fR, but logs entries for completion latency histograms.
1829 Computing latency percentiles from averages of intervals using \fBlog_avg_msec\fR
1830 is innacurate. Setting this option makes fio log histogram entries over the
1831 specified period of time, reducing log sizes for high IOPS devices while
1832 retaining percentile accuracy. See \fBlog_hist_coarseness\fR as well. Defaults
1833 to 0, meaning histogram logging is disabled.
1834 .TP
1835 .BI log_hist_coarseness \fR=\fPint
1836 Integer ranging from 0 to 6, defining the coarseness of the resolution of the
1837 histogram logs enabled with \fBlog_hist_msec\fR. For each increment in
1838 coarseness, fio outputs half as many bins. Defaults to 0, for which histogram
1839 logs contain 1216 latency bins. See the \fBLOG FILE FORMATS\fR section.
1840 .TP
1841 .BI log_offset \fR=\fPbool
1842 If this is set, the iolog options will include the byte offset for the IO
1843 entry as well as the other data values. Defaults to 0 meaning that offsets are
1844 not present in logs. See the \fBLOG FILE FORMATS\fR section.
1845 .TP
1846 .BI log_compression \fR=\fPint
1847 If this is set, fio will compress the IO logs as it goes, to keep the memory
1848 footprint lower. When a log reaches the specified size, that chunk is removed
1849 and compressed in the background. Given that IO logs are fairly highly
1850 compressible, this yields a nice memory savings for longer runs. The downside
1851 is that the compression will consume some background CPU cycles, so it may
1852 impact the run. This, however, is also true if the logging ends up consuming
1853 most of the system memory. So pick your poison. The IO logs are saved
1854 normally at the end of a run, by decompressing the chunks and storing them
1855 in the specified log file. This feature depends on the availability of zlib.
1856 .TP
1857 .BI log_compression_cpus \fR=\fPstr
1858 Define the set of CPUs that are allowed to handle online log compression
1859 for the IO jobs. This can provide better isolation between performance
1860 sensitive jobs, and background compression work.
1861 .TP
1862 .BI log_store_compressed \fR=\fPbool
1863 If set, fio will store the log files in a compressed format. They can be
1864 decompressed with fio, using the \fB\-\-inflate-log\fR command line parameter.
1865 The files will be stored with a \fB\.fz\fR suffix.
1866 .TP
1867 .BI log_unix_epoch \fR=\fPbool
1868 If set, fio will log Unix timestamps to the log files produced by enabling
1869 \fBwrite_type_log\fR for each log type, instead of the default zero-based
1870 timestamps.
1871 .TP
1872 .BI block_error_percentiles \fR=\fPbool
1873 If set, record errors in trim block-sized units from writes and trims and output
1874 a histogram of how many trims it took to get to errors, and what kind of error
1875 was encountered.
1876 .TP
1877 .BI disable_lat \fR=\fPbool
1878 Disable measurements of total latency numbers. Useful only for cutting
1879 back the number of calls to \fBgettimeofday\fR\|(2), as that does impact performance at
1880 really high IOPS rates.  Note that to really get rid of a large amount of these
1881 calls, this option must be used with disable_slat and disable_bw as well.
1882 .TP
1883 .BI disable_clat \fR=\fPbool
1884 Disable measurements of completion latency numbers. See \fBdisable_lat\fR.
1885 .TP
1886 .BI disable_slat \fR=\fPbool
1887 Disable measurements of submission latency numbers. See \fBdisable_lat\fR.
1888 .TP
1889 .BI disable_bw_measurement \fR=\fPbool
1890 Disable measurements of throughput/bandwidth numbers. See \fBdisable_lat\fR.
1891 .TP
1892 .BI lockmem \fR=\fPint
1893 Pin the specified amount of memory with \fBmlock\fR\|(2).  Can be used to
1894 simulate a smaller amount of memory. The amount specified is per worker.
1895 .TP
1896 .BI exec_prerun \fR=\fPstr
1897 Before running the job, execute the specified command with \fBsystem\fR\|(3).
1898 .RS
1899 Output is redirected in a file called \fBjobname.prerun.txt\fR
1900 .RE
1901 .TP
1902 .BI exec_postrun \fR=\fPstr
1903 Same as \fBexec_prerun\fR, but the command is executed after the job completes.
1904 .RS
1905 Output is redirected in a file called \fBjobname.postrun.txt\fR
1906 .RE
1907 .TP
1908 .BI ioscheduler \fR=\fPstr
1909 Attempt to switch the device hosting the file to the specified I/O scheduler.
1910 .TP
1911 .BI disk_util \fR=\fPbool
1912 Generate disk utilization statistics if the platform supports it. Default: true.
1913 .TP
1914 .BI clocksource \fR=\fPstr
1915 Use the given clocksource as the base of timing. The supported options are:
1916 .RS
1917 .TP
1918 .B gettimeofday
1919 \fBgettimeofday\fR\|(2)
1920 .TP
1921 .B clock_gettime
1922 \fBclock_gettime\fR\|(2)
1923 .TP
1924 .B cpu
1925 Internal CPU clock source
1926 .TP
1927 .RE
1928 .P
1929 \fBcpu\fR is the preferred clocksource if it is reliable, as it is very fast
1930 (and fio is heavy on time calls). Fio will automatically use this clocksource
1931 if it's supported and considered reliable on the system it is running on,
1932 unless another clocksource is specifically set. For x86/x86-64 CPUs, this
1933 means supporting TSC Invariant.
1934 .TP
1935 .BI gtod_reduce \fR=\fPbool
1936 Enable all of the \fBgettimeofday\fR\|(2) reducing options (disable_clat, disable_slat,
1937 disable_bw) plus reduce precision of the timeout somewhat to really shrink the
1938 \fBgettimeofday\fR\|(2) call count. With this option enabled, we only do about 0.4% of
1939 the gtod() calls we would have done if all time keeping was enabled.
1940 .TP
1941 .BI gtod_cpu \fR=\fPint
1942 Sometimes it's cheaper to dedicate a single thread of execution to just getting
1943 the current time. Fio (and databases, for instance) are very intensive on
1944 \fBgettimeofday\fR\|(2) calls. With this option, you can set one CPU aside for doing
1945 nothing but logging current time to a shared memory location. Then the other
1946 threads/processes that run IO workloads need only copy that segment, instead of
1947 entering the kernel with a \fBgettimeofday\fR\|(2) call. The CPU set aside for doing
1948 these time calls will be excluded from other uses. Fio will manually clear it
1949 from the CPU mask of other jobs.
1950 .TP
1951 .BI ignore_error \fR=\fPstr
1952 Sometimes you want to ignore some errors during test in that case you can specify
1953 error list for each error type.
1954 .br
1955 ignore_error=READ_ERR_LIST,WRITE_ERR_LIST,VERIFY_ERR_LIST
1956 .br
1957 errors for given error type is separated with ':'.
1958 Error may be symbol ('ENOSPC', 'ENOMEM') or an integer.
1959 .br
1960 Example: ignore_error=EAGAIN,ENOSPC:122 .
1961 .br
1962 This option will ignore EAGAIN from READ, and ENOSPC and 122(EDQUOT) from WRITE.
1963 .TP
1964 .BI error_dump \fR=\fPbool
1965 If set dump every error even if it is non fatal, true by default. If disabled
1966 only fatal error will be dumped
1967 .TP
1968 .BI profile \fR=\fPstr
1969 Select a specific builtin performance test.
1970 .TP
1971 .BI cgroup \fR=\fPstr
1972 Add job to this control group. If it doesn't exist, it will be created.
1973 The system must have a mounted cgroup blkio mount point for this to work. If
1974 your system doesn't have it mounted, you can do so with:
1975
1976 # mount \-t cgroup \-o blkio none /cgroup
1977 .TP
1978 .BI cgroup_weight \fR=\fPint
1979 Set the weight of the cgroup to this value. See the documentation that comes
1980 with the kernel, allowed values are in the range of 100..1000.
1981 .TP
1982 .BI cgroup_nodelete \fR=\fPbool
1983 Normally fio will delete the cgroups it has created after the job completion.
1984 To override this behavior and to leave cgroups around after the job completion,
1985 set cgroup_nodelete=1. This can be useful if one wants to inspect various
1986 cgroup files after job completion. Default: false
1987 .TP
1988 .BI uid \fR=\fPint
1989 Instead of running as the invoking user, set the user ID to this value before
1990 the thread/process does any work.
1991 .TP
1992 .BI gid \fR=\fPint
1993 Set group ID, see \fBuid\fR.
1994 .TP
1995 .BI unit_base \fR=\fPint
1996 Base unit for reporting.  Allowed values are:
1997 .RS
1998 .TP
1999 .B 0
2000 Use auto-detection (default).
2001 .TP
2002 .B 8
2003 Byte based.
2004 .TP
2005 .B 1
2006 Bit based.
2007 .RE
2008 .P
2009 .TP
2010 .BI flow_id \fR=\fPint
2011 The ID of the flow. If not specified, it defaults to being a global flow. See
2012 \fBflow\fR.
2013 .TP
2014 .BI flow \fR=\fPint
2015 Weight in token-based flow control. If this value is used, then there is a
2016 \fBflow counter\fR which is used to regulate the proportion of activity between
2017 two or more jobs. fio attempts to keep this flow counter near zero. The
2018 \fBflow\fR parameter stands for how much should be added or subtracted to the
2019 flow counter on each iteration of the main I/O loop. That is, if one job has
2020 \fBflow=8\fR and another job has \fBflow=-1\fR, then there will be a roughly
2021 1:8 ratio in how much one runs vs the other.
2022 .TP
2023 .BI flow_watermark \fR=\fPint
2024 The maximum value that the absolute value of the flow counter is allowed to
2025 reach before the job must wait for a lower value of the counter.
2026 .TP
2027 .BI flow_sleep \fR=\fPint
2028 The period of time, in microseconds, to wait after the flow watermark has been
2029 exceeded before retrying operations
2030 .TP
2031 .BI clat_percentiles \fR=\fPbool
2032 Enable the reporting of percentiles of completion latencies.
2033 .TP
2034 .BI percentile_list \fR=\fPfloat_list
2035 Overwrite the default list of percentiles for completion latencies and the
2036 block error histogram. Each number is a floating number in the range (0,100],
2037 and the maximum length of the list is 20. Use ':' to separate the
2038 numbers. For example, \-\-percentile_list=99.5:99.9 will cause fio to
2039 report the values of completion latency below which 99.5% and 99.9% of
2040 the observed latencies fell, respectively.
2041 .SS "Ioengine Parameters List"
2042 Some parameters are only valid when a specific ioengine is in use. These are
2043 used identically to normal parameters, with the caveat that when used on the
2044 command line, they must come after the ioengine.
2045 .TP
2046 .BI (cpuio)cpuload \fR=\fPint
2047 Attempt to use the specified percentage of CPU cycles.
2048 .TP
2049 .BI (cpuio)cpuchunks \fR=\fPint
2050 Split the load into cycles of the given time. In microseconds.
2051 .TP
2052 .BI (cpuio)exit_on_io_done \fR=\fPbool
2053 Detect when IO threads are done, then exit.
2054 .TP
2055 .BI (libaio)userspace_reap
2056 Normally, with the libaio engine in use, fio will use
2057 the io_getevents system call to reap newly returned events.
2058 With this flag turned on, the AIO ring will be read directly
2059 from user-space to reap events. The reaping mode is only
2060 enabled when polling for a minimum of 0 events (eg when
2061 iodepth_batch_complete=0).
2062 .TP
2063 .BI (pvsync2)hipri
2064 Set RWF_HIPRI on IO, indicating to the kernel that it's of
2065 higher priority than normal.
2066 .TP
2067 .BI (pvsync2)hipri_percentage
2068 When hipri is set this determines the probability of a pvsync2 IO being high
2069 priority. The default is 100%.
2070 .TP
2071 .BI (net,netsplice)hostname \fR=\fPstr
2072 The host name or IP address to use for TCP or UDP based IO.
2073 If the job is a TCP listener or UDP reader, the hostname is not
2074 used and must be omitted unless it is a valid UDP multicast address.
2075 .TP
2076 .BI (net,netsplice)port \fR=\fPint
2077 The TCP or UDP port to bind to or connect to. If this is used with
2078 \fBnumjobs\fR to spawn multiple instances of the same job type, then
2079 this will be the starting port number since fio will use a range of ports.
2080 .TP
2081 .BI (net,netsplice)interface \fR=\fPstr
2082 The IP address of the network interface used to send or receive UDP multicast
2083 packets.
2084 .TP
2085 .BI (net,netsplice)ttl \fR=\fPint
2086 Time-to-live value for outgoing UDP multicast packets. Default: 1
2087 .TP
2088 .BI (net,netsplice)nodelay \fR=\fPbool
2089 Set TCP_NODELAY on TCP connections.
2090 .TP
2091 .BI (net,netsplice)protocol \fR=\fPstr "\fR,\fP proto" \fR=\fPstr
2092 The network protocol to use. Accepted values are:
2093 .RS
2094 .RS
2095 .TP
2096 .B tcp
2097 Transmission control protocol
2098 .TP
2099 .B tcpv6
2100 Transmission control protocol V6
2101 .TP
2102 .B udp
2103 User datagram protocol
2104 .TP
2105 .B udpv6
2106 User datagram protocol V6
2107 .TP
2108 .B unix
2109 UNIX domain socket
2110 .RE
2111 .P
2112 When the protocol is TCP or UDP, the port must also be given,
2113 as well as the hostname if the job is a TCP listener or UDP
2114 reader. For unix sockets, the normal filename option should be
2115 used and the port is invalid.
2116 .RE
2117 .TP
2118 .BI (net,netsplice)listen
2119 For TCP network connections, tell fio to listen for incoming
2120 connections rather than initiating an outgoing connection. The
2121 hostname must be omitted if this option is used.
2122 .TP
2123 .BI (net,netsplice)pingpong \fR=\fPbool
2124 Normally a network writer will just continue writing data, and a network reader
2125 will just consume packets. If pingpong=1 is set, a writer will send its normal
2126 payload to the reader, then wait for the reader to send the same payload back.
2127 This allows fio to measure network latencies. The submission and completion
2128 latencies then measure local time spent sending or receiving, and the
2129 completion latency measures how long it took for the other end to receive and
2130 send back. For UDP multicast traffic pingpong=1 should only be set for a single
2131 reader when multiple readers are listening to the same address.
2132 .TP
2133 .BI (net,netsplice)window_size \fR=\fPint
2134 Set the desired socket buffer size for the connection.
2135 .TP
2136 .BI (net,netsplice)mss \fR=\fPint
2137 Set the TCP maximum segment size (TCP_MAXSEG).
2138 .TP
2139 .BI (e4defrag)donorname \fR=\fPstr
2140 File will be used as a block donor (swap extents between files)
2141 .TP
2142 .BI (e4defrag)inplace \fR=\fPint
2143 Configure donor file block allocation strategy
2144 .RS
2145 .BI 0(default) :
2146 Preallocate donor's file on init
2147 .TP
2148 .BI 1:
2149 allocate space immediately inside defragment event, and free right after event
2150 .RE
2151 .TP
2152 .BI (rbd)clustername \fR=\fPstr
2153 Specifies the name of the ceph cluster.
2154 .TP
2155 .BI (rbd)rbdname \fR=\fPstr
2156 Specifies the name of the RBD.
2157 .TP
2158 .BI (rbd)pool \fR=\fPstr
2159 Specifies the name of the Ceph pool containing the RBD.
2160 .TP
2161 .BI (rbd)clientname \fR=\fPstr
2162 Specifies the username (without the 'client.' prefix) used to access the Ceph
2163 cluster. If the clustername is specified, the clientname shall be the full
2164 type.id string. If no type. prefix is given, fio will add 'client.' by default.
2165 .TP
2166 .BI (mtd)skipbad \fR=\fPbool
2167 Skip operations against known bad blocks.
2168 .SH OUTPUT
2169 While running, \fBfio\fR will display the status of the created jobs.  For
2170 example:
2171 .RS
2172 .P
2173 Jobs: 1: [_r] [24.8% done] [ 13509/  8334 kb/s] [eta 00h:01m:31s]
2174 .RE
2175 .P
2176 The characters in the first set of brackets denote the current status of each
2177 threads.  The possible values are:
2178 .P
2179 .PD 0
2180 .RS
2181 .TP
2182 .B P
2183 Setup but not started.
2184 .TP
2185 .B C
2186 Thread created.
2187 .TP
2188 .B I
2189 Initialized, waiting.
2190 .TP
2191 .B R
2192 Running, doing sequential reads.
2193 .TP
2194 .B r
2195 Running, doing random reads.
2196 .TP
2197 .B W
2198 Running, doing sequential writes.
2199 .TP
2200 .B w
2201 Running, doing random writes.
2202 .TP
2203 .B M
2204 Running, doing mixed sequential reads/writes.
2205 .TP
2206 .B m
2207 Running, doing mixed random reads/writes.
2208 .TP
2209 .B F
2210 Running, currently waiting for \fBfsync\fR\|(2).
2211 .TP
2212 .B V
2213 Running, verifying written data.
2214 .TP
2215 .B E
2216 Exited, not reaped by main thread.
2217 .TP
2218 .B \-
2219 Exited, thread reaped.
2220 .RE
2221 .PD
2222 .P
2223 The second set of brackets shows the estimated completion percentage of
2224 the current group.  The third set shows the read and write I/O rate,
2225 respectively. Finally, the estimated run time of the job is displayed.
2226 .P
2227 When \fBfio\fR completes (or is interrupted by Ctrl-C), it will show data
2228 for each thread, each group of threads, and each disk, in that order.
2229 .P
2230 Per-thread statistics first show the threads client number, group-id, and
2231 error code.  The remaining figures are as follows:
2232 .RS
2233 .TP
2234 .B io
2235 Number of megabytes of I/O performed.
2236 .TP
2237 .B bw
2238 Average data rate (bandwidth).
2239 .TP
2240 .B runt
2241 Threads run time.
2242 .TP
2243 .B slat
2244 Submission latency minimum, maximum, average and standard deviation. This is
2245 the time it took to submit the I/O.
2246 .TP
2247 .B clat
2248 Completion latency minimum, maximum, average and standard deviation.  This
2249 is the time between submission and completion.
2250 .TP
2251 .B bw
2252 Bandwidth minimum, maximum, percentage of aggregate bandwidth received, average
2253 and standard deviation.
2254 .TP
2255 .B cpu
2256 CPU usage statistics. Includes user and system time, number of context switches
2257 this thread went through and number of major and minor page faults. The CPU
2258 utilization numbers are averages for the jobs in that reporting group, while
2259 the context and fault counters are summed.
2260 .TP
2261 .B IO depths
2262 Distribution of I/O depths.  Each depth includes everything less than (or equal)
2263 to it, but greater than the previous depth.
2264 .TP
2265 .B IO issued
2266 Number of read/write requests issued, and number of short read/write requests.
2267 .TP
2268 .B IO latencies
2269 Distribution of I/O completion latencies.  The numbers follow the same pattern
2270 as \fBIO depths\fR.
2271 .RE
2272 .P
2273 The group statistics show:
2274 .PD 0
2275 .RS
2276 .TP
2277 .B io
2278 Number of megabytes I/O performed.
2279 .TP
2280 .B aggrb
2281 Aggregate bandwidth of threads in the group.
2282 .TP
2283 .B minb
2284 Minimum average bandwidth a thread saw.
2285 .TP
2286 .B maxb
2287 Maximum average bandwidth a thread saw.
2288 .TP
2289 .B mint
2290 Shortest runtime of threads in the group.
2291 .TP
2292 .B maxt
2293 Longest runtime of threads in the group.
2294 .RE
2295 .PD
2296 .P
2297 Finally, disk statistics are printed with reads first:
2298 .PD 0
2299 .RS
2300 .TP
2301 .B ios
2302 Number of I/Os performed by all groups.
2303 .TP
2304 .B merge
2305 Number of merges performed by the I/O scheduler.
2306 .TP
2307 .B ticks
2308 Number of ticks we kept the disk busy.
2309 .TP
2310 .B io_queue
2311 Total time spent in the disk queue.
2312 .TP
2313 .B util
2314 Disk utilization.
2315 .RE
2316 .PD
2317 .P
2318 It is also possible to get fio to dump the current output while it is
2319 running, without terminating the job. To do that, send fio the \fBUSR1\fR
2320 signal.
2321 .SH TERSE OUTPUT
2322 If the \fB\-\-minimal\fR / \fB\-\-append-terse\fR options are given, the
2323 results will be printed/appended in a semicolon-delimited format suitable for
2324 scripted use.
2325 A job description (if provided) follows on a new line.  Note that the first
2326 number in the line is the version number. If the output has to be changed
2327 for some reason, this number will be incremented by 1 to signify that
2328 change. Numbers in brackets (e.g. "[v3]") indicate which terse version
2329 introduced a field. The fields are:
2330 .P
2331 .RS
2332 .B terse version, fio version [v3], jobname, groupid, error
2333 .P
2334 Read status:
2335 .RS
2336 .B Total I/O \fR(KiB)\fP, bandwidth \fR(KiB/s)\fP, IOPS, runtime \fR(ms)\fP
2337 .P
2338 Submission latency:
2339 .RS
2340 .B min, max, mean, standard deviation
2341 .RE
2342 Completion latency:
2343 .RS
2344 .B min, max, mean, standard deviation
2345 .RE
2346 Completion latency percentiles (20 fields):
2347 .RS
2348 .B Xth percentile=usec
2349 .RE
2350 Total latency:
2351 .RS
2352 .B min, max, mean, standard deviation
2353 .RE
2354 Bandwidth:
2355 .RS
2356 .B min, max, aggregate percentage of total, mean, standard deviation, number of samples [v5]
2357 .RE
2358 IOPS [v5]:
2359 .RS
2360 .B min, max, mean, standard deviation, number of samples
2361 .RE
2362 .RE
2363 .P
2364 Write status:
2365 .RS
2366 .B Total I/O \fR(KiB)\fP, bandwidth \fR(KiB/s)\fP, IOPS, runtime \fR(ms)\fP
2367 .P
2368 Submission latency:
2369 .RS
2370 .B min, max, mean, standard deviation
2371 .RE
2372 Completion latency:
2373 .RS
2374 .B min, max, mean, standard deviation
2375 .RE
2376 Completion latency percentiles (20 fields):
2377 .RS
2378 .B Xth percentile=usec
2379 .RE
2380 Total latency:
2381 .RS
2382 .B min, max, mean, standard deviation
2383 .RE
2384 Bandwidth:
2385 .RS
2386 .B min, max, aggregate percentage of total, mean, standard deviation, number of samples [v5]
2387 .RE
2388 IOPS [v5]:
2389 .RS
2390 .B min, max, mean, standard deviation, number of samples
2391 .RE
2392 .RE
2393 .P
2394 Trim status [all but version 3]:
2395 .RS
2396 Similar to Read/Write status but for trims.
2397 .RE
2398 .P
2399 CPU usage:
2400 .RS
2401 .B user, system, context switches, major page faults, minor page faults
2402 .RE
2403 .P
2404 IO depth distribution:
2405 .RS
2406 .B <=1, 2, 4, 8, 16, 32, >=64
2407 .RE
2408 .P
2409 IO latency distribution:
2410 .RS
2411 Microseconds:
2412 .RS
2413 .B <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000
2414 .RE
2415 Milliseconds:
2416 .RS
2417 .B <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, 2000, >=2000
2418 .RE
2419 .RE
2420 .P
2421 Disk utilization (1 for each disk used) [v3]:
2422 .RS
2423 .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
2424 .RE
2425 .P
2426 Error Info (dependent on continue_on_error, default off):
2427 .RS
2428 .B total # errors, first error code
2429 .RE
2430 .P
2431 .B text description (if provided in config - appears on newline)
2432 .RE
2433 .P
2434 Below is a single line containing short names for each of the fields in
2435 the minimal output v3, separated by semicolons:
2436 .RS
2437 .P
2438 .nf
2439 terse_version_3;fio_version;jobname;groupid;error;read_kb;read_bandwidth;read_iops;read_runtime_ms;read_slat_min;read_slat_max;read_slat_mean;read_slat_dev;read_clat_max;read_clat_min;read_clat_mean;read_clat_dev;read_clat_pct01;read_clat_pct02;read_clat_pct03;read_clat_pct04;read_clat_pct05;read_clat_pct06;read_clat_pct07;read_clat_pct08;read_clat_pct09;read_clat_pct10;read_clat_pct11;read_clat_pct12;read_clat_pct13;read_clat_pct14;read_clat_pct15;read_clat_pct16;read_clat_pct17;read_clat_pct18;read_clat_pct19;read_clat_pct20;read_tlat_min;read_lat_max;read_lat_mean;read_lat_dev;read_bw_min;read_bw_max;read_bw_agg_pct;read_bw_mean;read_bw_dev;write_kb;write_bandwidth;write_iops;write_runtime_ms;write_slat_min;write_slat_max;write_slat_mean;write_slat_dev;write_clat_max;write_clat_min;write_clat_mean;write_clat_dev;write_clat_pct01;write_clat_pct02;write_clat_pct03;write_clat_pct04;write_clat_pct05;write_clat_pct06;write_clat_pct07;write_clat_pct08;write_clat_pct09;write_clat_pct10;write_clat_pct11;write_clat_pct12;write_clat_pct13;write_clat_pct14;write_clat_pct15;write_clat_pct16;write_clat_pct17;write_clat_pct18;write_clat_pct19;write_clat_pct20;write_tlat_min;write_lat_max;write_lat_mean;write_lat_dev;write_bw_min;write_bw_max;write_bw_agg_pct;write_bw_mean;write_bw_dev;cpu_user;cpu_sys;cpu_csw;cpu_mjf;pu_minf;iodepth_1;iodepth_2;iodepth_4;iodepth_8;iodepth_16;iodepth_32;iodepth_64;lat_2us;lat_4us;lat_10us;lat_20us;lat_50us;lat_100us;lat_250us;lat_500us;lat_750us;lat_1000us;lat_2ms;lat_4ms;lat_10ms;lat_20ms;lat_50ms;lat_100ms;lat_250ms;lat_500ms;lat_750ms;lat_1000ms;lat_2000ms;lat_over_2000ms;disk_name;disk_read_iops;disk_write_iops;disk_read_merges;disk_write_merges;disk_read_ticks;write_ticks;disk_queue_time;disk_util
2440 .fi
2441 .RE
2442 .SH TRACE FILE FORMAT
2443 There are two trace file format that you can encounter. The older (v1) format
2444 is unsupported since version 1.20-rc3 (March 2008). It will still be described
2445 below in case that you get an old trace and want to understand it.
2446
2447 In any case the trace is a simple text file with a single action per line.
2448
2449 .P
2450 .B Trace file format v1
2451 .RS
2452 Each line represents a single io action in the following format:
2453
2454 rw, offset, length
2455
2456 where rw=0/1 for read/write, and the offset and length entries being in bytes.
2457
2458 This format is not supported in Fio versions => 1.20-rc3.
2459
2460 .RE
2461 .P
2462 .B Trace file format v2
2463 .RS
2464 The second version of the trace file format was added in Fio version 1.17.
2465 It allows one to access more then one file per trace and has a bigger set of
2466 possible file actions.
2467
2468 The first line of the trace file has to be:
2469
2470 \fBfio version 2 iolog\fR
2471
2472 Following this can be lines in two different formats, which are described below.
2473 The file management format:
2474
2475 \fBfilename action\fR
2476
2477 The filename is given as an absolute path. The action can be one of these:
2478
2479 .P
2480 .PD 0
2481 .RS
2482 .TP
2483 .B add
2484 Add the given filename to the trace
2485 .TP
2486 .B open
2487 Open the file with the given filename. The filename has to have been previously
2488 added with the \fBadd\fR action.
2489 .TP
2490 .B close
2491 Close the file with the given filename. The file must have previously been
2492 opened.
2493 .RE
2494 .PD
2495 .P
2496
2497 The file io action format:
2498
2499 \fBfilename action offset length\fR
2500
2501 The filename is given as an absolute path, and has to have been added and opened
2502 before it can be used with this format. The offset and length are given in
2503 bytes. The action can be one of these:
2504
2505 .P
2506 .PD 0
2507 .RS
2508 .TP
2509 .B wait
2510 Wait for 'offset' microseconds. Everything below 100 is discarded.  The time is
2511 relative to the previous wait statement.
2512 .TP
2513 .B read
2514 Read \fBlength\fR bytes beginning from \fBoffset\fR
2515 .TP
2516 .B write
2517 Write \fBlength\fR bytes beginning from \fBoffset\fR
2518 .TP
2519 .B sync
2520 fsync() the file
2521 .TP
2522 .B datasync
2523 fdatasync() the file
2524 .TP
2525 .B trim
2526 trim the given file from the given \fBoffset\fR for \fBlength\fR bytes
2527 .RE
2528 .PD
2529 .P
2530
2531 .SH CPU IDLENESS PROFILING
2532 In some cases, we want to understand CPU overhead in a test. For example,
2533 we test patches for the specific goodness of whether they reduce CPU usage.
2534 fio implements a balloon approach to create a thread per CPU that runs at
2535 idle priority, meaning that it only runs when nobody else needs the cpu.
2536 By measuring the amount of work completed by the thread, idleness of each
2537 CPU can be derived accordingly.
2538
2539 An unit work is defined as touching a full page of unsigned characters. Mean
2540 and standard deviation of time to complete an unit work is reported in "unit
2541 work" section. Options can be chosen to report detailed percpu idleness or
2542 overall system idleness by aggregating percpu stats.
2543
2544 .SH VERIFICATION AND TRIGGERS
2545 Fio is usually run in one of two ways, when data verification is done. The
2546 first is a normal write job of some sort with verify enabled. When the
2547 write phase has completed, fio switches to reads and verifies everything
2548 it wrote. The second model is running just the write phase, and then later
2549 on running the same job (but with reads instead of writes) to repeat the
2550 same IO patterns and verify the contents. Both of these methods depend
2551 on the write phase being completed, as fio otherwise has no idea how much
2552 data was written.
2553
2554 With verification triggers, fio supports dumping the current write state
2555 to local files. Then a subsequent read verify workload can load this state
2556 and know exactly where to stop. This is useful for testing cases where
2557 power is cut to a server in a managed fashion, for instance.
2558
2559 A verification trigger consists of two things:
2560
2561 .RS
2562 Storing the write state of each job
2563 .LP
2564 Executing a trigger command
2565 .RE
2566
2567 The write state is relatively small, on the order of hundreds of bytes
2568 to single kilobytes. It contains information on the number of completions
2569 done, the last X completions, etc.
2570
2571 A trigger is invoked either through creation (\fBtouch\fR) of a specified
2572 file in the system, or through a timeout setting. If fio is run with
2573 \fB\-\-trigger\-file=/tmp/trigger-file\fR, then it will continually check for
2574 the existence of /tmp/trigger-file. When it sees this file, it will
2575 fire off the trigger (thus saving state, and executing the trigger
2576 command).
2577
2578 For client/server runs, there's both a local and remote trigger. If
2579 fio is running as a server backend, it will send the job states back
2580 to the client for safe storage, then execute the remote trigger, if
2581 specified. If a local trigger is specified, the server will still send
2582 back the write state, but the client will then execute the trigger.
2583
2584 .RE
2585 .P
2586 .B Verification trigger example
2587 .RS
2588
2589 Lets say we want to run a powercut test on the remote machine 'server'.
2590 Our write workload is in write-test.fio. We want to cut power to 'server'
2591 at some point during the run, and we'll run this test from the safety
2592 or our local machine, 'localbox'. On the server, we'll start the fio
2593 backend normally:
2594
2595 server# \fBfio \-\-server\fR
2596
2597 and on the client, we'll fire off the workload:
2598
2599 localbox$ \fBfio \-\-client=server \-\-trigger\-file=/tmp/my\-trigger \-\-trigger-remote="bash \-c "echo b > /proc/sysrq-triger""\fR
2600
2601 We set \fB/tmp/my-trigger\fR as the trigger file, and we tell fio to execute
2602
2603 \fBecho b > /proc/sysrq-trigger\fR
2604
2605 on the server once it has received the trigger and sent us the write
2606 state. This will work, but it's not \fIreally\fR cutting power to the server,
2607 it's merely abruptly rebooting it. If we have a remote way of cutting
2608 power to the server through IPMI or similar, we could do that through
2609 a local trigger command instead. Lets assume we have a script that does
2610 IPMI reboot of a given hostname, ipmi-reboot. On localbox, we could
2611 then have run fio with a local trigger instead:
2612
2613 localbox$ \fBfio \-\-client=server \-\-trigger\-file=/tmp/my\-trigger \-\-trigger="ipmi-reboot server"\fR
2614
2615 For this case, fio would wait for the server to send us the write state,
2616 then execute 'ipmi-reboot server' when that happened.
2617
2618 .RE
2619 .P
2620 .B Loading verify state
2621 .RS
2622 To load store write state, read verification job file must contain
2623 the verify_state_load option. If that is set, fio will load the previously
2624 stored state. For a local fio run this is done by loading the files directly,
2625 and on a client/server run, the server backend will ask the client to send
2626 the files over and load them from there.
2627
2628 .RE
2629
2630 .SH LOG FILE FORMATS
2631
2632 Fio supports a variety of log file formats, for logging latencies, bandwidth,
2633 and IOPS. The logs share a common format, which looks like this:
2634
2635 .B time (msec), value, data direction, block size (bytes), offset (bytes)
2636
2637 Time for the log entry is always in milliseconds. The value logged depends
2638 on the type of log, it will be one of the following:
2639
2640 .P
2641 .PD 0
2642 .TP
2643 .B Latency log
2644 Value is in latency in usecs
2645 .TP
2646 .B Bandwidth log
2647 Value is in KiB/sec
2648 .TP
2649 .B IOPS log
2650 Value is in IOPS
2651 .PD
2652 .P
2653
2654 Data direction is one of the following:
2655
2656 .P
2657 .PD 0
2658 .TP
2659 .B 0
2660 IO is a READ
2661 .TP
2662 .B 1
2663 IO is a WRITE
2664 .TP
2665 .B 2
2666 IO is a TRIM
2667 .PD
2668 .P
2669
2670 The entry's *block size* is always in bytes. The \fIoffset\fR is the offset, in
2671 bytes, from the start of the file, for that particular IO. The logging of the
2672 offset can be toggled with \fBlog_offset\fR.
2673
2674 If windowed logging is enabled through \fBlog_avg_msec\fR, then fio doesn't log
2675 individual IOs. Instead of logs the average values over the specified
2676 period of time. Since \fIdata direction\fR, \fIblock size\fR and \fIoffset\fR
2677 are per-IO values, if windowed logging is enabled they aren't applicable and
2678 will be 0. If windowed logging is enabled and \fBlog_max_value\fR is set, then
2679 fio logs maximum values in that window instead of averages.
2680
2681 For histogram logging the logs look like this:
2682
2683 .B time (msec), data direction, block-size, bin 0, bin 1, ..., bin 1215
2684
2685 Where 'bin i' gives the frequency of IO requests with a latency falling in
2686 the i-th bin. See \fBlog_hist_coarseness\fR for logging fewer bins.
2687
2688 .RE
2689
2690 .SH CLIENT / SERVER
2691 Normally you would run fio as a stand-alone application on the machine
2692 where the IO workload should be generated. However, it is also possible to
2693 run the frontend and backend of fio separately. This makes it possible to
2694 have a fio server running on the machine(s) where the IO workload should
2695 be running, while controlling it from another machine.
2696
2697 To start the server, you would do:
2698
2699 \fBfio \-\-server=args\fR
2700
2701 on that machine, where args defines what fio listens to. The arguments
2702 are of the form 'type:hostname or IP:port'. 'type' is either 'ip' (or ip4)
2703 for TCP/IP v4, 'ip6' for TCP/IP v6, or 'sock' for a local unix domain
2704 socket. 'hostname' is either a hostname or IP address, and 'port' is the port to
2705 listen to (only valid for TCP/IP, not a local socket). Some examples:
2706
2707 1) \fBfio \-\-server\fR
2708
2709    Start a fio server, listening on all interfaces on the default port (8765).
2710
2711 2) \fBfio \-\-server=ip:hostname,4444\fR
2712
2713    Start a fio server, listening on IP belonging to hostname and on port 4444.
2714
2715 3) \fBfio \-\-server=ip6:::1,4444\fR
2716
2717    Start a fio server, listening on IPv6 localhost ::1 and on port 4444.
2718
2719 4) \fBfio \-\-server=,4444\fR
2720
2721    Start a fio server, listening on all interfaces on port 4444.
2722
2723 5) \fBfio \-\-server=1.2.3.4\fR
2724
2725    Start a fio server, listening on IP 1.2.3.4 on the default port.
2726
2727 6) \fBfio \-\-server=sock:/tmp/fio.sock\fR
2728
2729    Start a fio server, listening on the local socket /tmp/fio.sock.
2730
2731 When a server is running, you can connect to it from a client. The client
2732 is run with:
2733
2734 \fBfio \-\-local-args \-\-client=server \-\-remote-args <job file(s)>\fR
2735
2736 where \-\-local-args are arguments that are local to the client where it is
2737 running, 'server' is the connect string, and \-\-remote-args and <job file(s)>
2738 are sent to the server. The 'server' string follows the same format as it
2739 does on the server side, to allow IP/hostname/socket and port strings.
2740 You can connect to multiple clients as well, to do that you could run:
2741
2742 \fBfio \-\-client=server2 \-\-client=server2 <job file(s)>\fR
2743
2744 If the job file is located on the fio server, then you can tell the server
2745 to load a local file as well. This is done by using \-\-remote-config:
2746
2747 \fBfio \-\-client=server \-\-remote-config /path/to/file.fio\fR
2748
2749 Then fio will open this local (to the server) job file instead
2750 of being passed one from the client.
2751
2752 If you have many servers (example: 100 VMs/containers), you can input a pathname
2753 of a file containing host IPs/names as the parameter value for the \-\-client option.
2754 For example, here is an example "host.list" file containing 2 hostnames:
2755
2756 host1.your.dns.domain
2757 .br
2758 host2.your.dns.domain
2759
2760 The fio command would then be:
2761
2762 \fBfio \-\-client=host.list <job file>\fR
2763
2764 In this mode, you cannot input server-specific parameters or job files, and all
2765 servers receive the same job file.
2766
2767 In order to enable fio \-\-client runs utilizing a shared filesystem from multiple hosts,
2768 fio \-\-client now prepends the IP address of the server to the filename. For example,
2769 if fio is using directory /mnt/nfs/fio and is writing filename fileio.tmp,
2770 with a \-\-client hostfile
2771 containing two hostnames h1 and h2 with IP addresses 192.168.10.120 and 192.168.10.121, then
2772 fio will create two files:
2773
2774 /mnt/nfs/fio/192.168.10.120.fileio.tmp
2775 .br
2776 /mnt/nfs/fio/192.168.10.121.fileio.tmp
2777
2778 .SH AUTHORS
2779
2780 .B fio
2781 was written by Jens Axboe <jens.axboe@oracle.com>,
2782 now Jens Axboe <axboe@fb.com>.
2783 .br
2784 This man page was written by Aaron Carroll <aaronc@cse.unsw.edu.au> based
2785 on documentation by Jens Axboe.
2786 .SH "REPORTING BUGS"
2787 Report bugs to the \fBfio\fR mailing list <fio@vger.kernel.org>.
2788 .br
2789 See \fBREPORTING-BUGS\fR.
2790
2791 \fBREPORTING-BUGS\fR: http://git.kernel.dk/cgit/fio/plain/REPORTING-BUGS
2792 .SH "SEE ALSO"
2793 For further documentation see \fBHOWTO\fR and \fBREADME\fR.
2794 .br
2795 Sample jobfiles are available in the \fBexamples\fR directory.
2796 .br
2797 These are typically located under /usr/share/doc/fio.
2798
2799 \fBHOWTO\fR:  http://git.kernel.dk/cgit/fio/plain/HOWTO
2800 .br
2801 \fBREADME\fR: http://git.kernel.dk/cgit/fio/plain/README
2802 .br