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