b21d27e3b15fb74325703a60de6455cef6960596
[fio.git] / HOWTO
1 Table of contents
2 -----------------
3
4 1. Overview
5 2. How fio works
6 3. Running fio
7 4. Job file format
8 5. Detailed list of parameters
9 6. Normal output
10 7. Terse output
11 8. Trace file format
12 9. CPU idleness profiling
13
14 1.0 Overview and history
15 ------------------------
16 fio was originally written to save me the hassle of writing special test
17 case programs when I wanted to test a specific workload, either for
18 performance reasons or to find/reproduce a bug. The process of writing
19 such a test app can be tiresome, especially if you have to do it often.
20 Hence I needed a tool that would be able to simulate a given io workload
21 without resorting to writing a tailored test case again and again.
22
23 A test work load is difficult to define, though. There can be any number
24 of processes or threads involved, and they can each be using their own
25 way of generating io. You could have someone dirtying large amounts of
26 memory in an memory mapped file, or maybe several threads issuing
27 reads using asynchronous io. fio needed to be flexible enough to
28 simulate both of these cases, and many more.
29
30 2.0 How fio works
31 -----------------
32 The first step in getting fio to simulate a desired io workload, is
33 writing a job file describing that specific setup. A job file may contain
34 any number of threads and/or files - the typical contents of the job file
35 is a global section defining shared parameters, and one or more job
36 sections describing the jobs involved. When run, fio parses this file
37 and sets everything up as described. If we break down a job from top to
38 bottom, it contains the following basic parameters:
39
40         IO type         Defines the io pattern issued to the file(s).
41                         We may only be reading sequentially from this
42                         file(s), or we may be writing randomly. Or even
43                         mixing reads and writes, sequentially or randomly.
44
45         Block size      In how large chunks are we issuing io? This may be
46                         a single value, or it may describe a range of
47                         block sizes.
48
49         IO size         How much data are we going to be reading/writing.
50
51         IO engine       How do we issue io? We could be memory mapping the
52                         file, we could be using regular read/write, we
53                         could be using splice, async io, syslet, or even
54                         SG (SCSI generic sg).
55
56         IO depth        If the io engine is async, how large a queuing
57                         depth do we want to maintain?
58
59         IO type         Should we be doing buffered io, or direct/raw io?
60
61         Num files       How many files are we spreading the workload over.
62
63         Num threads     How many threads or processes should we spread
64                         this workload over.
65
66 The above are the basic parameters defined for a workload, in addition
67 there's a multitude of parameters that modify other aspects of how this
68 job behaves.
69
70
71 3.0 Running fio
72 ---------------
73 See the README file for command line parameters, there are only a few
74 of them.
75
76 Running fio is normally the easiest part - you just give it the job file
77 (or job files) as parameters:
78
79 $ fio job_file
80
81 and it will start doing what the job_file tells it to do. You can give
82 more than one job file on the command line, fio will serialize the running
83 of those files. Internally that is the same as using the 'stonewall'
84 parameter described in the parameter section.
85
86 If the job file contains only one job, you may as well just give the
87 parameters on the command line. The command line parameters are identical
88 to the job parameters, with a few extra that control global parameters
89 (see README). For example, for the job file parameter iodepth=2, the
90 mirror command line option would be --iodepth 2 or --iodepth=2. You can
91 also use the command line for giving more than one job entry. For each
92 --name option that fio sees, it will start a new job with that name.
93 Command line entries following a --name entry will apply to that job,
94 until there are no more entries or a new --name entry is seen. This is
95 similar to the job file options, where each option applies to the current
96 job until a new [] job entry is seen.
97
98 fio does not need to run as root, except if the files or devices specified
99 in the job section requires that. Some other options may also be restricted,
100 such as memory locking, io scheduler switching, and decreasing the nice value.
101
102
103 4.0 Job file format
104 -------------------
105 As previously described, fio accepts one or more job files describing
106 what it is supposed to do. The job file format is the classic ini file,
107 where the names enclosed in [] brackets define the job name. You are free
108 to use any ascii name you want, except 'global' which has special meaning.
109 A global section sets defaults for the jobs described in that file. A job
110 may override a global section parameter, and a job file may even have
111 several global sections if so desired. A job is only affected by a global
112 section residing above it. If the first character in a line is a ';' or a
113 '#', the entire line is discarded as a comment.
114
115 So let's look at a really simple job file that defines two processes, each
116 randomly reading from a 128MB file.
117
118 ; -- start job file --
119 [global]
120 rw=randread
121 size=128m
122
123 [job1]
124
125 [job2]
126
127 ; -- end job file --
128
129 As you can see, the job file sections themselves are empty as all the
130 described parameters are shared. As no filename= option is given, fio
131 makes up a filename for each of the jobs as it sees fit. On the command
132 line, this job would look as follows:
133
134 $ fio --name=global --rw=randread --size=128m --name=job1 --name=job2
135
136
137 Let's look at an example that has a number of processes writing randomly
138 to files.
139
140 ; -- start job file --
141 [random-writers]
142 ioengine=libaio
143 iodepth=4
144 rw=randwrite
145 bs=32k
146 direct=0
147 size=64m
148 numjobs=4
149
150 ; -- end job file --
151
152 Here we have no global section, as we only have one job defined anyway.
153 We want to use async io here, with a depth of 4 for each file. We also
154 increased the buffer size used to 32KB and define numjobs to 4 to
155 fork 4 identical jobs. The result is 4 processes each randomly writing
156 to their own 64MB file. Instead of using the above job file, you could
157 have given the parameters on the command line. For this case, you would
158 specify:
159
160 $ fio --name=random-writers --ioengine=libaio --iodepth=4 --rw=randwrite --bs=32k --direct=0 --size=64m --numjobs=4
161
162 When fio is utilized as a basis of any reasonably large test suite, it might be
163 desirable to share a set of standardized settings across multiple job files.
164 Instead of copy/pasting such settings, any section may pull in an external
165 .fio file with 'include filename' directive, as in the following example:
166
167 ; -- start job file including.fio --
168 [global]
169 filename=/tmp/test
170 filesize=1m
171 include glob-include.fio
172
173 [test]
174 rw=randread
175 bs=4k
176 time_based=1
177 runtime=10
178 include test-include.fio
179 ; -- end job file including.fio --
180
181 ; -- start job file glob-include.fio --
182 thread=1
183 group_reporting=1
184 ; -- end job file glob-include.fio --
185
186 ; -- start job file test-include.fio --
187 ioengine=libaio
188 iodepth=4
189 ; -- end job file test-include.fio --
190
191 Settings pulled into a section apply to that section only (except global
192 section). Include directives may be nested in that any included file may
193 contain further include directive(s). Include files may not contain []
194 sections.
195
196
197 4.1 Environment variables
198 -------------------------
199
200 fio also supports environment variable expansion in job files. Any
201 sub-string of the form "${VARNAME}" as part of an option value (in other
202 words, on the right of the `='), will be expanded to the value of the
203 environment variable called VARNAME.  If no such environment variable
204 is defined, or VARNAME is the empty string, the empty string will be
205 substituted.
206
207 As an example, let's look at a sample fio invocation and job file:
208
209 $ SIZE=64m NUMJOBS=4 fio jobfile.fio
210
211 ; -- start job file --
212 [random-writers]
213 rw=randwrite
214 size=${SIZE}
215 numjobs=${NUMJOBS}
216 ; -- end job file --
217
218 This will expand to the following equivalent job file at runtime:
219
220 ; -- start job file --
221 [random-writers]
222 rw=randwrite
223 size=64m
224 numjobs=4
225 ; -- end job file --
226
227 fio ships with a few example job files, you can also look there for
228 inspiration.
229
230 4.2 Reserved keywords
231 ---------------------
232
233 Additionally, fio has a set of reserved keywords that will be replaced
234 internally with the appropriate value. Those keywords are:
235
236 $pagesize       The architecture page size of the running system
237 $mb_memory      Megabytes of total memory in the system
238 $ncpus          Number of online available CPUs
239
240 These can be used on the command line or in the job file, and will be
241 automatically substituted with the current system values when the job
242 is run. Simple math is also supported on these keywords, so you can
243 perform actions like:
244
245 size=8*$mb_memory
246
247 and get that properly expanded to 8 times the size of memory in the
248 machine.
249
250
251 5.0 Detailed list of parameters
252 -------------------------------
253
254 This section describes in details each parameter associated with a job.
255 Some parameters take an option of a given type, such as an integer or
256 a string. Anywhere a numeric value is required, an arithmetic expression
257 may be used, provided it is surrounded by parentheses. Supported operators
258 are:
259
260         addition (+)
261         subtraction (-)
262         multiplication (*)
263         division (/)
264         modulus (%)
265         exponentiation (^)
266
267 For time values in expressions, units are microseconds by default. This is
268 different than for time values not in expressions (not enclosed in
269 parentheses). The following types are used:
270
271 str     String. This is a sequence of alpha characters.
272 time    Integer with possible time suffix. In seconds unless otherwise
273         specified, use eg 10m for 10 minutes. Accepts s/m/h for seconds,
274         minutes, and hours, and accepts 'ms' (or 'msec') for milliseconds,
275         and 'us' (or 'usec') for microseconds.
276 int     SI integer. A whole number value, which may contain a suffix
277         describing the base of the number. Accepted suffixes are k/m/g/t/p,
278         meaning kilo, mega, giga, tera, and peta. The suffix is not case
279         sensitive, and you may also include trailing 'b' (eg 'kb' is the same
280         as 'k'). So if you want to specify 4096, you could either write
281         out '4096' or just give 4k. The suffixes signify base 2 values, so
282         1024 is 1k and 1024k is 1m and so on, unless the suffix is explicitly
283         set to a base 10 value using 'kib', 'mib', 'gib', etc. If that is the
284         case, then 1000 is used as the multiplier. This can be handy for
285         disks, since manufacturers generally use base 10 values when listing
286         the capacity of a drive. If the option accepts an upper and lower
287         range, use a colon ':' or minus '-' to separate such values.  May also
288         include a prefix to indicate numbers base. If 0x is used, the number
289         is assumed to be hexadecimal.  See irange.
290 bool    Boolean. Usually parsed as an integer, however only defined for
291         true and false (1 and 0).
292 irange  Integer range with suffix. Allows value range to be given, such
293         as 1024-4096. A colon may also be used as the separator, eg
294         1k:4k. If the option allows two sets of ranges, they can be
295         specified with a ',' or '/' delimiter: 1k-4k/8k-32k. Also see
296         int.
297 float_list      A list of floating numbers, separated by a ':' character.
298
299 With the above in mind, here follows the complete list of fio job
300 parameters.
301
302 name=str        ASCII name of the job. This may be used to override the
303                 name printed by fio for this job. Otherwise the job
304                 name is used. On the command line this parameter has the
305                 special purpose of also signaling the start of a new
306                 job.
307
308 description=str Text description of the job. Doesn't do anything except
309                 dump this text description when this job is run. It's
310                 not parsed.
311
312 directory=str   Prefix filenames with this directory. Used to place files
313                 in a different location than "./". See the 'filename' option
314                 for escaping certain characters.
315
316 filename=str    Fio normally makes up a filename based on the job name,
317                 thread number, and file number. If you want to share
318                 files between threads in a job or several jobs, specify
319                 a filename for each of them to override the default. If
320                 the ioengine used is 'net', the filename is the host, port,
321                 and protocol to use in the format of =host,port,protocol.
322                 See ioengine=net for more. If the ioengine is file based, you
323                 can specify a number of files by separating the names with a
324                 ':' colon. So if you wanted a job to open /dev/sda and /dev/sdb
325                 as the two working files, you would use
326                 filename=/dev/sda:/dev/sdb. On Windows, disk devices are
327                 accessed as \\.\PhysicalDrive0 for the first device,
328                 \\.\PhysicalDrive1 for the second etc. Note: Windows and
329                 FreeBSD prevent write access to areas of the disk containing
330                 in-use data (e.g. filesystems).
331                 If the wanted filename does need to include a colon, then
332                 escape that with a '\' character. For instance, if the filename
333                 is "/dev/dsk/foo@3,0:c", then you would use
334                 filename="/dev/dsk/foo@3,0\:c". '-' is a reserved name, meaning
335                 stdin or stdout. Which of the two depends on the read/write
336                 direction set.
337
338 filename_format=str
339                 If sharing multiple files between jobs, it is usually necessary
340                 to  have fio generate the exact names that you want. By default,
341                 fio will name a file based on the default file format
342                 specification of jobname.jobnumber.filenumber. With this
343                 option, that can be customized. Fio will recognize and replace
344                 the following keywords in this string:
345
346                 $jobname
347                         The name of the worker thread or process.
348
349                 $jobnum
350                         The incremental number of the worker thread or
351                         process.
352
353                 $filenum
354                         The incremental number of the file for that worker
355                         thread or process.
356
357                 To have dependent jobs share a set of files, this option can
358                 be set to have fio generate filenames that are shared between
359                 the two. For instance, if testfiles.$filenum is specified,
360                 file number 4 for any job will be named testfiles.4. The
361                 default of $jobname.$jobnum.$filenum will be used if
362                 no other format specifier is given.
363
364 opendir=str     Tell fio to recursively add any file it can find in this
365                 directory and down the file system tree.
366
367 lockfile=str    Fio defaults to not locking any files before it does
368                 IO to them. If a file or file descriptor is shared, fio
369                 can serialize IO to that file to make the end result
370                 consistent. This is usual for emulating real workloads that
371                 share files. The lock modes are:
372
373                         none            No locking. The default.
374                         exclusive       Only one thread/process may do IO,
375                                         excluding all others.
376                         readwrite       Read-write locking on the file. Many
377                                         readers may access the file at the
378                                         same time, but writes get exclusive
379                                         access.
380
381 readwrite=str
382 rw=str          Type of io pattern. Accepted values are:
383
384                         read            Sequential reads
385                         write           Sequential writes
386                         randwrite       Random writes
387                         randread        Random reads
388                         rw,readwrite    Sequential mixed reads and writes
389                         randrw          Random mixed reads and writes
390                         trimwrite       Mixed trims and writes. Blocks will be
391                                         trimmed first, then written to.
392
393                 For the mixed io types, the default is to split them 50/50.
394                 For certain types of io the result may still be skewed a bit,
395                 since the speed may be different. It is possible to specify
396                 a number of IO's to do before getting a new offset, this is
397                 done by appending a ':<nr>' to the end of the string given.
398                 For a random read, it would look like 'rw=randread:8' for
399                 passing in an offset modifier with a value of 8. If the
400                 suffix is used with a sequential IO pattern, then the value
401                 specified will be added to the generated offset for each IO.
402                 For instance, using rw=write:4k will skip 4k for every
403                 write. It turns sequential IO into sequential IO with holes.
404                 See the 'rw_sequencer' option.
405
406 rw_sequencer=str If an offset modifier is given by appending a number to
407                 the rw=<str> line, then this option controls how that
408                 number modifies the IO offset being generated. Accepted
409                 values are:
410
411                         sequential      Generate sequential offset
412                         identical       Generate the same offset
413
414                 'sequential' is only useful for random IO, where fio would
415                 normally generate a new random offset for every IO. If you
416                 append eg 8 to randread, you would get a new random offset for
417                 every 8 IO's. The result would be a seek for only every 8
418                 IO's, instead of for every IO. Use rw=randread:8 to specify
419                 that. As sequential IO is already sequential, setting
420                 'sequential' for that would not result in any differences.
421                 'identical' behaves in a similar fashion, except it sends
422                 the same offset 8 number of times before generating a new
423                 offset.
424
425 kb_base=int     The base unit for a kilobyte. The defacto base is 2^10, 1024.
426                 Storage manufacturers like to use 10^3 or 1000 as a base
427                 ten unit instead, for obvious reasons. Allow values are
428                 1024 or 1000, with 1024 being the default.
429
430 unified_rw_reporting=bool       Fio normally reports statistics on a per
431                 data direction basis, meaning that read, write, and trim are
432                 accounted and reported separately. If this option is set,
433                 the fio will sum the results and report them as "mixed"
434                 instead.
435
436 randrepeat=bool For random IO workloads, seed the generator in a predictable
437                 way so that results are repeatable across repetitions.
438                 Defaults to true.
439
440 randseed=int    Seed the random number generators based on this seed value, to
441                 be able to control what sequence of output is being generated.
442                 If not set, the random sequence depends on the randrepeat
443                 setting.
444
445 fallocate=str   Whether pre-allocation is performed when laying down files.
446                 Accepted values are:
447
448                         none            Do not pre-allocate space
449                         posix           Pre-allocate via posix_fallocate()
450                         keep            Pre-allocate via fallocate() with
451                                         FALLOC_FL_KEEP_SIZE set
452                         0               Backward-compatible alias for 'none'
453                         1               Backward-compatible alias for 'posix'
454
455                 May not be available on all supported platforms. 'keep' is only
456                 available on Linux.If using ZFS on Solaris this must be set to
457                 'none' because ZFS doesn't support it. Default: 'posix'.
458
459 fadvise_hint=bool By default, fio will use fadvise() to advise the kernel
460                 on what IO patterns it is likely to issue. Sometimes you
461                 want to test specific IO patterns without telling the
462                 kernel about it, in which case you can disable this option.
463                 If set, fio will use POSIX_FADV_SEQUENTIAL for sequential
464                 IO and POSIX_FADV_RANDOM for random IO.
465
466 fadvise_stream=int Notify the kernel what write stream ID to place these
467                 writes under. Only supported on Linux. Note, this option
468                 may change going forward.
469
470 size=int        The total size of file io for this job. Fio will run until
471                 this many bytes has been transferred, unless runtime is
472                 limited by other options (such as 'runtime', for instance,
473                 or increased/decreased by 'io_size'). Unless specific nrfiles
474                 and filesize options are given, fio will divide this size
475                 between the available files specified by the job. If not set,
476                 fio will use the full size of the given files or devices.
477                 If the files do not exist, size must be given. It is also
478                 possible to give size as a percentage between 1 and 100. If
479                 size=20% is given, fio will use 20% of the full size of the
480                 given files or devices.
481
482 io_size=int
483 io_limit=int    Normally fio operates within the region set by 'size', which
484                 means that the 'size' option sets both the region and size of
485                 IO to be performed. Sometimes that is not what you want. With
486                 this option, it is possible to define just the amount of IO
487                 that fio should do. For instance, if 'size' is set to 20G and
488                 'io_size' is set to 5G, fio will perform IO within the first
489                 20G but exit when 5G have been done. The opposite is also
490                 possible - if 'size' is set to 20G, and 'io_size' is set to
491                 40G, then fio will do 40G of IO within the 0..20G region.
492
493 filesize=int    Individual file sizes. May be a range, in which case fio
494                 will select sizes for files at random within the given range
495                 and limited to 'size' in total (if that is given). If not
496                 given, each created file is the same size.
497
498 file_append=bool        Perform IO after the end of the file. Normally fio will
499                 operate within the size of a file. If this option is set, then
500                 fio will append to the file instead. This has identical
501                 behavior to setting offset to the size of a file. This option
502                 is ignored on non-regular files.
503
504 fill_device=bool
505 fill_fs=bool    Sets size to something really large and waits for ENOSPC (no
506                 space left on device) as the terminating condition. Only makes
507                 sense with sequential write. For a read workload, the mount
508                 point will be filled first then IO started on the result. This
509                 option doesn't make sense if operating on a raw device node,
510                 since the size of that is already known by the file system.
511                 Additionally, writing beyond end-of-device will not return
512                 ENOSPC there.
513
514 blocksize=int
515 bs=int          The block size used for the io units. Defaults to 4k. Values
516                 can be given for both read and writes. If a single int is
517                 given, it will apply to both. If a second int is specified
518                 after a comma, it will apply to writes only. In other words,
519                 the format is either bs=read_and_write or bs=read,write,trim.
520                 bs=4k,8k will thus use 4k blocks for reads, 8k blocks for
521                 writes, and 8k for trims. You can terminate the list with
522                 a trailing comma. bs=4k,8k, would use the default value for
523                 trims.. If you only wish to set the write size, you
524                 can do so by passing an empty read size - bs=,8k will set
525                 8k for writes and leave the read default value.
526
527 blockalign=int
528 ba=int          At what boundary to align random IO offsets. Defaults to
529                 the same as 'blocksize' the minimum blocksize given.
530                 Minimum alignment is typically 512b for using direct IO,
531                 though it usually depends on the hardware block size. This
532                 option is mutually exclusive with using a random map for
533                 files, so it will turn off that option.
534
535 blocksize_range=irange
536 bsrange=irange  Instead of giving a single block size, specify a range
537                 and fio will mix the issued io block sizes. The issued
538                 io unit will always be a multiple of the minimum value
539                 given (also see bs_unaligned). Applies to both reads and
540                 writes, however a second range can be given after a comma.
541                 See bs=.
542
543 bssplit=str     Sometimes you want even finer grained control of the
544                 block sizes issued, not just an even split between them.
545                 This option allows you to weight various block sizes,
546                 so that you are able to define a specific amount of
547                 block sizes issued. The format for this option is:
548
549                         bssplit=blocksize/percentage:blocksize/percentage
550
551                 for as many block sizes as needed. So if you want to define
552                 a workload that has 50% 64k blocks, 10% 4k blocks, and
553                 40% 32k blocks, you would write:
554
555                         bssplit=4k/10:64k/50:32k/40
556
557                 Ordering does not matter. If the percentage is left blank,
558                 fio will fill in the remaining values evenly. So a bssplit
559                 option like this one:
560
561                         bssplit=4k/50:1k/:32k/
562
563                 would have 50% 4k ios, and 25% 1k and 32k ios. The percentages
564                 always add up to 100, if bssplit is given a range that adds
565                 up to more, it will error out.
566
567                 bssplit also supports giving separate splits to reads and
568                 writes. The format is identical to what bs= accepts. You
569                 have to separate the read and write parts with a comma. So
570                 if you want a workload that has 50% 2k reads and 50% 4k reads,
571                 while having 90% 4k writes and 10% 8k writes, you would
572                 specify:
573
574                 bssplit=2k/50:4k/50,4k/90:8k/10
575
576 blocksize_unaligned
577 bs_unaligned    If this option is given, any byte size value within bsrange
578                 may be used as a block range. This typically wont work with
579                 direct IO, as that normally requires sector alignment.
580
581 bs_is_seq_rand  If this option is set, fio will use the normal read,write
582                 blocksize settings as sequential,random instead. Any random
583                 read or write will use the WRITE blocksize settings, and any
584                 sequential read or write will use the READ blocksize setting.
585
586 zero_buffers    If this option is given, fio will init the IO buffers to
587                 all zeroes. The default is to fill them with random data.
588
589 refill_buffers  If this option is given, fio will refill the IO buffers
590                 on every submit. The default is to only fill it at init
591                 time and reuse that data. Only makes sense if zero_buffers
592                 isn't specified, naturally. If data verification is enabled,
593                 refill_buffers is also automatically enabled.
594
595 scramble_buffers=bool   If refill_buffers is too costly and the target is
596                 using data deduplication, then setting this option will
597                 slightly modify the IO buffer contents to defeat normal
598                 de-dupe attempts. This is not enough to defeat more clever
599                 block compression attempts, but it will stop naive dedupe of
600                 blocks. Default: true.
601
602 buffer_compress_percentage=int  If this is set, then fio will attempt to
603                 provide IO buffer content (on WRITEs) that compress to
604                 the specified level. Fio does this by providing a mix of
605                 random data and a fixed pattern. The fixed pattern is either
606                 zeroes, or the pattern specified by buffer_pattern. If the
607                 pattern option is used, it might skew the compression ratio
608                 slightly. Note that this is per block size unit, for file/disk
609                 wide compression level that matches this setting, you'll also
610                 want to set refill_buffers.
611
612 buffer_compress_chunk=int       See buffer_compress_percentage. This
613                 setting allows fio to manage how big the ranges of random
614                 data and zeroed data is. Without this set, fio will
615                 provide buffer_compress_percentage of blocksize random
616                 data, followed by the remaining zeroed. With this set
617                 to some chunk size smaller than the block size, fio can
618                 alternate random and zeroed data throughout the IO
619                 buffer.
620
621 buffer_pattern=str      If set, fio will fill the io buffers with this
622                 pattern. If not set, the contents of io buffers is defined by
623                 the other options related to buffer contents. The setting can
624                 be any pattern of bytes, and can be prefixed with 0x for hex
625                 values. It may also be a string, where the string must then
626                 be wrapped with "", e.g.:
627
628                 buffer_pattern="abcd"
629                   or
630                 buffer_pattern=-12
631                   or
632                 buffer_pattern=0xdeadface
633
634                 Also you can combine everything together in any order:
635                 buffer_pattern=0xdeadface"abcd"-12
636
637 dedupe_percentage=int   If set, fio will generate this percentage of
638                 identical buffers when writing. These buffers will be
639                 naturally dedupable. The contents of the buffers depend on
640                 what other buffer compression settings have been set. It's
641                 possible to have the individual buffers either fully
642                 compressible, or not at all. This option only controls the
643                 distribution of unique buffers.
644
645 nrfiles=int     Number of files to use for this job. Defaults to 1.
646
647 openfiles=int   Number of files to keep open at the same time. Defaults to
648                 the same as nrfiles, can be set smaller to limit the number
649                 simultaneous opens.
650
651 file_service_type=str  Defines how fio decides which file from a job to
652                 service next. The following types are defined:
653
654                         random  Just choose a file at random.
655
656                         roundrobin  Round robin over open files. This
657                                 is the default.
658
659                         sequential  Finish one file before moving on to
660                                 the next. Multiple files can still be
661                                 open depending on 'openfiles'.
662
663                 The string can have a number appended, indicating how
664                 often to switch to a new file. So if option random:4 is
665                 given, fio will switch to a new random file after 4 ios
666                 have been issued.
667
668 ioengine=str    Defines how the job issues io to the file. The following
669                 types are defined:
670
671                         sync    Basic read(2) or write(2) io. lseek(2) is
672                                 used to position the io location.
673
674                         psync   Basic pread(2) or pwrite(2) io.
675
676                         vsync   Basic readv(2) or writev(2) IO.
677
678                         psyncv  Basic preadv(2) or pwritev(2) IO.
679
680                         libaio  Linux native asynchronous io. Note that Linux
681                                 may only support queued behaviour with
682                                 non-buffered IO (set direct=1 or buffered=0).
683                                 This engine defines engine specific options.
684
685                         posixaio glibc posix asynchronous io.
686
687                         solarisaio Solaris native asynchronous io.
688
689                         windowsaio Windows native asynchronous io.
690
691                         mmap    File is memory mapped and data copied
692                                 to/from using memcpy(3).
693
694                         splice  splice(2) is used to transfer the data and
695                                 vmsplice(2) to transfer data from user
696                                 space to the kernel.
697
698                         syslet-rw Use the syslet system calls to make
699                                 regular read/write async.
700
701                         sg      SCSI generic sg v3 io. May either be
702                                 synchronous using the SG_IO ioctl, or if
703                                 the target is an sg character device
704                                 we use read(2) and write(2) for asynchronous
705                                 io.
706
707                         null    Doesn't transfer any data, just pretends
708                                 to. This is mainly used to exercise fio
709                                 itself and for debugging/testing purposes.
710
711                         net     Transfer over the network to given host:port.
712                                 Depending on the protocol used, the hostname,
713                                 port, listen and filename options are used to
714                                 specify what sort of connection to make, while
715                                 the protocol option determines which protocol
716                                 will be used.
717                                 This engine defines engine specific options.
718
719                         netsplice Like net, but uses splice/vmsplice to
720                                 map data and send/receive.
721                                 This engine defines engine specific options.
722
723                         cpuio   Doesn't transfer any data, but burns CPU
724                                 cycles according to the cpuload= and
725                                 cpucycle= options. Setting cpuload=85
726                                 will cause that job to do nothing but burn
727                                 85% of the CPU. In case of SMP machines,
728                                 use numjobs=<no_of_cpu> to get desired CPU
729                                 usage, as the cpuload only loads a single
730                                 CPU at the desired rate.
731
732                         guasi   The GUASI IO engine is the Generic Userspace
733                                 Asyncronous Syscall Interface approach
734                                 to async IO. See
735
736                                 http://www.xmailserver.org/guasi-lib.html
737
738                                 for more info on GUASI.
739
740                         rdma    The RDMA I/O engine  supports  both  RDMA
741                                 memory semantics (RDMA_WRITE/RDMA_READ) and
742                                 channel semantics (Send/Recv) for the
743                                 InfiniBand, RoCE and iWARP protocols.
744
745                         falloc  IO engine that does regular fallocate to
746                                 simulate data transfer as fio ioengine.
747                                 DDIR_READ  does fallocate(,mode = keep_size,)
748                                 DDIR_WRITE does fallocate(,mode = 0)
749                                 DDIR_TRIM  does fallocate(,mode = punch_hole)
750
751                         e4defrag IO engine that does regular EXT4_IOC_MOVE_EXT
752                                 ioctls to simulate defragment activity in
753                                 request to DDIR_WRITE event
754
755                         rbd     IO engine supporting direct access to Ceph
756                                 Rados Block Devices (RBD) via librbd without
757                                 the need to use the kernel rbd driver. This
758                                 ioengine defines engine specific options.
759
760                         gfapi   Using Glusterfs libgfapi sync interface to
761                                 direct access to Glusterfs volumes without
762                                 options.
763
764                         gfapi_async Using Glusterfs libgfapi async interface
765                                 to direct access to Glusterfs volumes without
766                                 having to go through FUSE. This ioengine
767                                 defines engine specific options.
768
769                         libhdfs Read and write through Hadoop (HDFS).
770                                 The 'filename' option is used to specify host,
771                                 port of the hdfs name-node to connect. This
772                                 engine interprets offsets a little
773                                 differently. In HDFS, files once created
774                                 cannot be modified. So random writes are not
775                                 possible. To imitate this, libhdfs engine
776                                 expects bunch of small files to be created
777                                 over HDFS, and engine will randomly pick a
778                                 file out of those files based on the offset
779                                 generated by fio backend. (see the example
780                                 job file to create such files, use rw=write
781                                 option). Please note, you might want to set
782                                 necessary environment variables to work with
783                                 hdfs/libhdfs properly.
784
785                         mtd     Read, write and erase an MTD character device
786                                 (e.g., /dev/mtd0). Discards are treated as
787                                 erases. Depending on the underlying device
788                                 type, the I/O may have to go in a certain
789                                 pattern, e.g., on NAND, writing sequentially
790                                 to erase blocks and discarding before
791                                 overwriting. The writetrim mode works well
792                                 for this constraint.
793
794                         external Prefix to specify loading an external
795                                 IO engine object file. Append the engine
796                                 filename, eg ioengine=external:/tmp/foo.o
797                                 to load ioengine foo.o in /tmp.
798
799 iodepth=int     This defines how many io units to keep in flight against
800                 the file. The default is 1 for each file defined in this
801                 job, can be overridden with a larger value for higher
802                 concurrency. Note that increasing iodepth beyond 1 will not
803                 affect synchronous ioengines (except for small degress when
804                 verify_async is in use). Even async engines may impose OS
805                 restrictions causing the desired depth not to be achieved.
806                 This may happen on Linux when using libaio and not setting
807                 direct=1, since buffered IO is not async on that OS. Keep an
808                 eye on the IO depth distribution in the fio output to verify
809                 that the achieved depth is as expected. Default: 1.
810
811 iodepth_batch_submit=int
812 iodepth_batch=int This defines how many pieces of IO to submit at once.
813                 It defaults to 1 which means that we submit each IO
814                 as soon as it is available, but can be raised to submit
815                 bigger batches of IO at the time. If it is set to 0 the iodepth
816                 value will be used.
817
818 iodepth_batch_complete_min=int
819 iodepth_batch_complete=int This defines how many pieces of IO to retrieve
820                 at once. It defaults to 1 which means that we'll ask
821                 for a minimum of 1 IO in the retrieval process from
822                 the kernel. The IO retrieval will go on until we
823                 hit the limit set by iodepth_low. If this variable is
824                 set to 0, then fio will always check for completed
825                 events before queuing more IO. This helps reduce
826                 IO latency, at the cost of more retrieval system calls.
827
828 iodepth_batch_complete_max=int This defines maximum pieces of IO to
829                 retrieve at once. This variable should be used along with
830                 iodepth_batch_complete_min=int variable, specifying the range
831                 of min and max amount of IO which should be retrieved. By default
832                 it is equal to iodepth_batch_complete_min value.
833
834                 Example #1:
835
836                 iodepth_batch_complete_min=1
837                 iodepth_batch_complete_max=<iodepth>
838
839                 which means that we will retrieve at leat 1 IO and up to the
840                 whole submitted queue depth. If none of IO has been completed
841                 yet, we will wait.
842
843                 Example #2:
844
845                 iodepth_batch_complete_min=0
846                 iodepth_batch_complete_max=<iodepth>
847
848                 which means that we can retrieve up to the whole submitted
849                 queue depth, but if none of IO has been completed yet, we will
850                 NOT wait and immediately exit the system call. In this example
851                 we simply do polling.
852
853 iodepth_low=int The low water mark indicating when to start filling
854                 the queue again. Defaults to the same as iodepth, meaning
855                 that fio will attempt to keep the queue full at all times.
856                 If iodepth is set to eg 16 and iodepth_low is set to 4, then
857                 after fio has filled the queue of 16 requests, it will let
858                 the depth drain down to 4 before starting to fill it again.
859
860 io_submit_mode=str      This option controls how fio submits the IO to
861                 the IO engine. The default is 'inline', which means that the
862                 fio job threads submit and reap IO directly. If set to
863                 'offload', the job threads will offload IO submission to a
864                 dedicated pool of IO threads. This requires some coordination
865                 and thus has a bit of extra overhead, especially for lower
866                 queue depth IO where it can increase latencies. The benefit
867                 is that fio can manage submission rates independently of
868                 the device completion rates. This avoids skewed latency
869                 reporting if IO gets back up on the device side (the
870                 coordinated omission problem).
871
872 direct=bool     If value is true, use non-buffered io. This is usually
873                 O_DIRECT. Note that ZFS on Solaris doesn't support direct io.
874                 On Windows the synchronous ioengines don't support direct io.
875
876 atomic=bool     If value is true, attempt to use atomic direct IO. Atomic
877                 writes are guaranteed to be stable once acknowledged by
878                 the operating system. Only Linux supports O_ATOMIC right
879                 now.
880
881 buffered=bool   If value is true, use buffered io. This is the opposite
882                 of the 'direct' option. Defaults to true.
883
884 offset=int      Start io at the given offset in the file. The data before
885                 the given offset will not be touched. This effectively
886                 caps the file size at real_size - offset.
887
888 offset_increment=int    If this is provided, then the real offset becomes
889                 offset + offset_increment * thread_number, where the thread
890                 number is a counter that starts at 0 and is incremented for
891                 each sub-job (i.e. when numjobs option is specified). This
892                 option is useful if there are several jobs which are intended
893                 to operate on a file in parallel disjoint segments, with
894                 even spacing between the starting points.
895
896 number_ios=int  Fio will normally perform IOs until it has exhausted the size
897                 of the region set by size=, or if it exhaust the allocated
898                 time (or hits an error condition). With this setting, the
899                 range/size can be set independently of the number of IOs to
900                 perform. When fio reaches this number, it will exit normally
901                 and report status. Note that this does not extend the amount
902                 of IO that will be done, it will only stop fio if this
903                 condition is met before other end-of-job criteria.
904
905 fsync=int       If writing to a file, issue a sync of the dirty data
906                 for every number of blocks given. For example, if you give
907                 32 as a parameter, fio will sync the file for every 32
908                 writes issued. If fio is using non-buffered io, we may
909                 not sync the file. The exception is the sg io engine, which
910                 synchronizes the disk cache anyway.
911
912 fdatasync=int   Like fsync= but uses fdatasync() to only sync data and not
913                 metadata blocks.
914                 In FreeBSD and Windows there is no fdatasync(), this falls back
915                 to using fsync()
916
917 sync_file_range=str:val Use sync_file_range() for every 'val' number of
918                 write operations. Fio will track range of writes that
919                 have happened since the last sync_file_range() call. 'str'
920                 can currently be one or more of:
921
922                 wait_before     SYNC_FILE_RANGE_WAIT_BEFORE
923                 write           SYNC_FILE_RANGE_WRITE
924                 wait_after      SYNC_FILE_RANGE_WAIT_AFTER
925
926                 So if you do sync_file_range=wait_before,write:8, fio would
927                 use SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE for
928                 every 8 writes. Also see the sync_file_range(2) man page.
929                 This option is Linux specific.
930
931 overwrite=bool  If true, writes to a file will always overwrite existing
932                 data. If the file doesn't already exist, it will be
933                 created before the write phase begins. If the file exists
934                 and is large enough for the specified write phase, nothing
935                 will be done.
936
937 end_fsync=bool  If true, fsync file contents when a write stage has completed.
938
939 fsync_on_close=bool     If true, fio will fsync() a dirty file on close.
940                 This differs from end_fsync in that it will happen on every
941                 file close, not just at the end of the job.
942
943 rwmixread=int   How large a percentage of the mix should be reads.
944
945 rwmixwrite=int  How large a percentage of the mix should be writes. If both
946                 rwmixread and rwmixwrite is given and the values do not add
947                 up to 100%, the latter of the two will be used to override
948                 the first. This may interfere with a given rate setting,
949                 if fio is asked to limit reads or writes to a certain rate.
950                 If that is the case, then the distribution may be skewed.
951
952 random_distribution=str:float   By default, fio will use a completely uniform
953                 random distribution when asked to perform random IO. Sometimes
954                 it is useful to skew the distribution in specific ways,
955                 ensuring that some parts of the data is more hot than others.
956                 fio includes the following distribution models:
957
958                 random          Uniform random distribution
959                 zipf            Zipf distribution
960                 pareto          Pareto distribution
961
962                 When using a zipf or pareto distribution, an input value
963                 is also needed to define the access pattern. For zipf, this
964                 is the zipf theta. For pareto, it's the pareto power. Fio
965                 includes a test program, genzipf, that can be used visualize
966                 what the given input values will yield in terms of hit rates.
967                 If you wanted to use zipf with a theta of 1.2, you would use
968                 random_distribution=zipf:1.2 as the option. If a non-uniform
969                 model is used, fio will disable use of the random map.
970
971 percentage_random=int   For a random workload, set how big a percentage should
972                 be random. This defaults to 100%, in which case the workload
973                 is fully random. It can be set from anywhere from 0 to 100.
974                 Setting it to 0 would make the workload fully sequential. Any
975                 setting in between will result in a random mix of sequential
976                 and random IO, at the given percentages. It is possible to
977                 set different values for reads, writes, and trim. To do so,
978                 simply use a comma separated list. See blocksize.
979         
980 norandommap     Normally fio will cover every block of the file when doing
981                 random IO. If this option is given, fio will just get a
982                 new random offset without looking at past io history. This
983                 means that some blocks may not be read or written, and that
984                 some blocks may be read/written more than once. If this option
985                 is used with verify= and multiple blocksizes (via bsrange=),
986                 only intact blocks are verified, i.e., partially-overwritten
987                 blocks are ignored.
988
989 softrandommap=bool See norandommap. If fio runs with the random block map
990                 enabled and it fails to allocate the map, if this option is
991                 set it will continue without a random block map. As coverage
992                 will not be as complete as with random maps, this option is
993                 disabled by default.
994
995 random_generator=str    Fio supports the following engines for generating
996                 IO offsets for random IO:
997
998                 tausworthe      Strong 2^88 cycle random number generator
999                 lfsr            Linear feedback shift register generator
1000                 tausworthe64    Strong 64-bit 2^258 cycle random number
1001                                 generator
1002
1003                 Tausworthe is a strong random number generator, but it
1004                 requires tracking on the side if we want to ensure that
1005                 blocks are only read or written once. LFSR guarantees
1006                 that we never generate the same offset twice, and it's
1007                 also less computationally expensive. It's not a true
1008                 random generator, however, though for IO purposes it's
1009                 typically good enough. LFSR only works with single
1010                 block sizes, not with workloads that use multiple block
1011                 sizes. If used with such a workload, fio may read or write
1012                 some blocks multiple times.
1013
1014 nice=int        Run the job with the given nice value. See man nice(2).
1015
1016 prio=int        Set the io priority value of this job. Linux limits us to
1017                 a positive value between 0 and 7, with 0 being the highest.
1018                 See man ionice(1).
1019
1020 prioclass=int   Set the io priority class. See man ionice(1).
1021
1022 thinktime=int   Stall the job x microseconds after an io has completed before
1023                 issuing the next. May be used to simulate processing being
1024                 done by an application. See thinktime_blocks and
1025                 thinktime_spin.
1026
1027 thinktime_spin=int
1028                 Only valid if thinktime is set - pretend to spend CPU time
1029                 doing something with the data received, before falling back
1030                 to sleeping for the rest of the period specified by
1031                 thinktime.
1032
1033 thinktime_blocks=int
1034                 Only valid if thinktime is set - control how many blocks
1035                 to issue, before waiting 'thinktime' usecs. If not set,
1036                 defaults to 1 which will make fio wait 'thinktime' usecs
1037                 after every block. This effectively makes any queue depth
1038                 setting redundant, since no more than 1 IO will be queued
1039                 before we have to complete it and do our thinktime. In
1040                 other words, this setting effectively caps the queue depth
1041                 if the latter is larger.
1042
1043 rate=int        Cap the bandwidth used by this job. The number is in bytes/sec,
1044                 the normal suffix rules apply. You can use rate=500k to limit
1045                 reads and writes to 500k each, or you can specify read and
1046                 writes separately. Using rate=1m,500k would limit reads to
1047                 1MB/sec and writes to 500KB/sec. Capping only reads or
1048                 writes can be done with rate=,500k or rate=500k,. The former
1049                 will only limit writes (to 500KB/sec), the latter will only
1050                 limit reads.
1051
1052 rate_min=int    Tell fio to do whatever it can to maintain at least this
1053                 bandwidth. Failing to meet this requirement, will cause
1054                 the job to exit. The same format as rate is used for
1055                 read vs write separation.
1056
1057 rate_iops=int   Cap the bandwidth to this number of IOPS. Basically the same
1058                 as rate, just specified independently of bandwidth. If the
1059                 job is given a block size range instead of a fixed value,
1060                 the smallest block size is used as the metric. The same format
1061                 as rate is used for read vs write separation.
1062
1063 rate_iops_min=int If fio doesn't meet this rate of IO, it will cause
1064                 the job to exit. The same format as rate is used for read vs
1065                 write separation.
1066
1067 rate_process=str        This option controls how fio manages rated IO
1068                 submissions. The default is 'linear', which submits IO in a
1069                 linear fashion with fixed delays between IOs that gets
1070                 adjusted based on IO completion rates. If this is set to
1071                 'poisson', fio will submit IO based on a more real world
1072                 random request flow, known as the Poisson process
1073                 (https://en.wikipedia.org/wiki/Poisson_process). The lambda
1074                 will be 10^6 / IOPS for the given workload.
1075
1076 latency_target=int      If set, fio will attempt to find the max performance
1077                 point that the given workload will run at while maintaining a
1078                 latency below this target. The values is given in microseconds.
1079                 See latency_window and latency_percentile
1080
1081 latency_window=int      Used with latency_target to specify the sample window
1082                 that the job is run at varying queue depths to test the
1083                 performance. The value is given in microseconds.
1084
1085 latency_percentile=float        The percentage of IOs that must fall within the
1086                 criteria specified by latency_target and latency_window. If not
1087                 set, this defaults to 100.0, meaning that all IOs must be equal
1088                 or below to the value set by latency_target.
1089
1090 max_latency=int If set, fio will exit the job if it exceeds this maximum
1091                 latency. It will exit with an ETIME error.
1092
1093 rate_cycle=int  Average bandwidth for 'rate' and 'rate_min' over this number
1094                 of milliseconds.
1095
1096 cpumask=int     Set the CPU affinity of this job. The parameter given is a
1097                 bitmask of allowed CPU's the job may run on. So if you want
1098                 the allowed CPUs to be 1 and 5, you would pass the decimal
1099                 value of (1 << 1 | 1 << 5), or 34. See man
1100                 sched_setaffinity(2). This may not work on all supported
1101                 operating systems or kernel versions. This option doesn't
1102                 work well for a higher CPU count than what you can store in
1103                 an integer mask, so it can only control cpus 1-32. For
1104                 boxes with larger CPU counts, use cpus_allowed.
1105
1106 cpus_allowed=str Controls the same options as cpumask, but it allows a text
1107                 setting of the permitted CPUs instead. So to use CPUs 1 and
1108                 5, you would specify cpus_allowed=1,5. This options also
1109                 allows a range of CPUs. Say you wanted a binding to CPUs
1110                 1, 5, and 8-15, you would set cpus_allowed=1,5,8-15.
1111
1112 cpus_allowed_policy=str Set the policy of how fio distributes the CPUs
1113                 specified by cpus_allowed or cpumask. Two policies are
1114                 supported:
1115
1116                 shared  All jobs will share the CPU set specified.
1117                 split   Each job will get a unique CPU from the CPU set.
1118
1119                 'shared' is the default behaviour, if the option isn't
1120                 specified. If split is specified, then fio will will assign
1121                 one cpu per job. If not enough CPUs are given for the jobs
1122                 listed, then fio will roundrobin the CPUs in the set.
1123
1124 numa_cpu_nodes=str Set this job running on spcified NUMA nodes' CPUs. The
1125                 arguments allow comma delimited list of cpu numbers,
1126                 A-B ranges, or 'all'. Note, to enable numa options support,
1127                 fio must be built on a system with libnuma-dev(el) installed.
1128
1129 numa_mem_policy=str Set this job's memory policy and corresponding NUMA
1130                 nodes. Format of the argements:
1131                         <mode>[:<nodelist>]
1132                 `mode' is one of the following memory policy:
1133                         default, prefer, bind, interleave, local
1134                 For `default' and `local' memory policy, no node is
1135                 needed to be specified.
1136                 For `prefer', only one node is allowed.
1137                 For `bind' and `interleave', it allow comma delimited
1138                 list of numbers, A-B ranges, or 'all'.
1139
1140 startdelay=time Start this job the specified number of seconds after fio
1141                 has started. Only useful if the job file contains several
1142                 jobs, and you want to delay starting some jobs to a certain
1143                 time.
1144
1145 runtime=time    Tell fio to terminate processing after the specified number
1146                 of seconds. It can be quite hard to determine for how long
1147                 a specified job will run, so this parameter is handy to
1148                 cap the total runtime to a given time.
1149
1150 time_based      If set, fio will run for the duration of the runtime
1151                 specified even if the file(s) are completely read or
1152                 written. It will simply loop over the same workload
1153                 as many times as the runtime allows.
1154
1155 ramp_time=time  If set, fio will run the specified workload for this amount
1156                 of time before logging any performance numbers. Useful for
1157                 letting performance settle before logging results, thus
1158                 minimizing the runtime required for stable results. Note
1159                 that the ramp_time is considered lead in time for a job,
1160                 thus it will increase the total runtime if a special timeout
1161                 or runtime is specified.
1162
1163 invalidate=bool Invalidate the buffer/page cache parts for this file prior
1164                 to starting io. Defaults to true.
1165
1166 sync=bool       Use sync io for buffered writes. For the majority of the
1167                 io engines, this means using O_SYNC.
1168
1169 iomem=str
1170 mem=str         Fio can use various types of memory as the io unit buffer.
1171                 The allowed values are:
1172
1173                         malloc  Use memory from malloc(3) as the buffers.
1174
1175                         shm     Use shared memory as the buffers. Allocated
1176                                 through shmget(2).
1177
1178                         shmhuge Same as shm, but use huge pages as backing.
1179
1180                         mmap    Use mmap to allocate buffers. May either be
1181                                 anonymous memory, or can be file backed if
1182                                 a filename is given after the option. The
1183                                 format is mem=mmap:/path/to/file.
1184
1185                         mmaphuge Use a memory mapped huge file as the buffer
1186                                 backing. Append filename after mmaphuge, ala
1187                                 mem=mmaphuge:/hugetlbfs/file
1188
1189                         mmapshared      Same as mmap, but use a MMAP_SHARED
1190                                 mapping.
1191
1192                 The area allocated is a function of the maximum allowed
1193                 bs size for the job, multiplied by the io depth given. Note
1194                 that for shmhuge and mmaphuge to work, the system must have
1195                 free huge pages allocated. This can normally be checked
1196                 and set by reading/writing /proc/sys/vm/nr_hugepages on a
1197                 Linux system. Fio assumes a huge page is 4MB in size. So
1198                 to calculate the number of huge pages you need for a given
1199                 job file, add up the io depth of all jobs (normally one unless
1200                 iodepth= is used) and multiply by the maximum bs set. Then
1201                 divide that number by the huge page size. You can see the
1202                 size of the huge pages in /proc/meminfo. If no huge pages
1203                 are allocated by having a non-zero number in nr_hugepages,
1204                 using mmaphuge or shmhuge will fail. Also see hugepage-size.
1205
1206                 mmaphuge also needs to have hugetlbfs mounted and the file
1207                 location should point there. So if it's mounted in /huge,
1208                 you would use mem=mmaphuge:/huge/somefile.
1209
1210 iomem_align=int This indiciates the memory alignment of the IO memory buffers.
1211                 Note that the given alignment is applied to the first IO unit
1212                 buffer, if using iodepth the alignment of the following buffers
1213                 are given by the bs used. In other words, if using a bs that is
1214                 a multiple of the page sized in the system, all buffers will
1215                 be aligned to this value. If using a bs that is not page
1216                 aligned, the alignment of subsequent IO memory buffers is the
1217                 sum of the iomem_align and bs used.
1218
1219 hugepage-size=int
1220                 Defines the size of a huge page. Must at least be equal
1221                 to the system setting, see /proc/meminfo. Defaults to 4MB.
1222                 Should probably always be a multiple of megabytes, so using
1223                 hugepage-size=Xm is the preferred way to set this to avoid
1224                 setting a non-pow-2 bad value.
1225
1226 exitall         When one job finishes, terminate the rest. The default is
1227                 to wait for each job to finish, sometimes that is not the
1228                 desired action.
1229
1230 exitall_on_error        When one job finishes in error, terminate the rest. The
1231                 default is to wait for each job to finish.
1232
1233 bwavgtime=int   Average the calculated bandwidth over the given time. Value
1234                 is specified in milliseconds.
1235
1236 iopsavgtime=int Average the calculated IOPS over the given time. Value
1237                 is specified in milliseconds.
1238
1239 create_serialize=bool   If true, serialize the file creating for the jobs.
1240                         This may be handy to avoid interleaving of data
1241                         files, which may greatly depend on the filesystem
1242                         used and even the number of processors in the system.
1243
1244 create_fsync=bool       fsync the data file after creation. This is the
1245                         default.
1246
1247 create_on_open=bool     Don't pre-setup the files for IO, just create open()
1248                         when it's time to do IO to that file.
1249
1250 create_only=bool        If true, fio will only run the setup phase of the job.
1251                         If files need to be laid out or updated on disk, only
1252                         that will be done. The actual job contents are not
1253                         executed.
1254
1255 allow_file_create=bool  If true, fio is permitted to create files as part
1256                 of its workload. This is the default behavior. If this
1257                 option is false, then fio will error out if the files it
1258                 needs to use don't already exist. Default: true.
1259
1260 allow_mounted_write=bool        If this isn't set, fio will abort jobs that
1261                 are destructive (eg that write) to what appears to be a
1262                 mounted device or partition. This should help catch creating
1263                 inadvertently destructive tests, not realizing that the test
1264                 will destroy data on the mounted file system. Default: false.
1265
1266 pre_read=bool   If this is given, files will be pre-read into memory before
1267                 starting the given IO operation. This will also clear
1268                 the 'invalidate' flag, since it is pointless to pre-read
1269                 and then drop the cache. This will only work for IO engines
1270                 that are seekable, since they allow you to read the same data
1271                 multiple times. Thus it will not work on eg network or splice
1272                 IO.
1273
1274 unlink=bool     Unlink the job files when done. Not the default, as repeated
1275                 runs of that job would then waste time recreating the file
1276                 set again and again.
1277
1278 loops=int       Run the specified number of iterations of this job. Used
1279                 to repeat the same workload a given number of times. Defaults
1280                 to 1.
1281
1282 verify_only     Do not perform specified workload---only verify data still
1283                 matches previous invocation of this workload. This option
1284                 allows one to check data multiple times at a later date
1285                 without overwriting it. This option makes sense only for
1286                 workloads that write data, and does not support workloads
1287                 with the time_based option set.
1288
1289 do_verify=bool  Run the verify phase after a write phase. Only makes sense if
1290                 verify is set. Defaults to 1.
1291
1292 verify=str      If writing to a file, fio can verify the file contents
1293                 after each iteration of the job. Each verification method also implies
1294                 verification of special header, which is written to the beginning of
1295                 each block. This header also includes meta information, like offset
1296                 of the block, block number, timestamp when block was written, etc.
1297                 verify=str can be combined with verify_pattern=str option.
1298                 The allowed values are:
1299
1300                         md5     Use an md5 sum of the data area and store
1301                                 it in the header of each block.
1302
1303                         crc64   Use an experimental crc64 sum of the data
1304                                 area and store it in the header of each
1305                                 block.
1306
1307                         crc32c  Use a crc32c sum of the data area and store
1308                                 it in the header of each block.
1309
1310                         crc32c-intel Use hardware assisted crc32c calcuation
1311                                 provided on SSE4.2 enabled processors. Falls
1312                                 back to regular software crc32c, if not
1313                                 supported by the system.
1314
1315                         crc32   Use a crc32 sum of the data area and store
1316                                 it in the header of each block.
1317
1318                         crc16   Use a crc16 sum of the data area and store
1319                                 it in the header of each block.
1320
1321                         crc7    Use a crc7 sum of the data area and store
1322                                 it in the header of each block.
1323
1324                         xxhash  Use xxhash as the checksum function. Generally
1325                                 the fastest software checksum that fio
1326                                 supports.
1327
1328                         sha512  Use sha512 as the checksum function.
1329
1330                         sha256  Use sha256 as the checksum function.
1331
1332                         sha1    Use optimized sha1 as the checksum function.
1333
1334                         meta    This option is deprecated, since now meta information is
1335                                 included in generic verification header and meta verification
1336                                 happens by default. For detailed information see the description
1337                                 of the verify=str setting. This option is kept because of
1338                                 compatibility's sake with old configurations. Do not use it.
1339
1340                         pattern Verify a strict pattern. Normally fio includes
1341                                 a header with some basic information and
1342                                 checksumming, but if this option is set, only
1343                                 the specific pattern set with 'verify_pattern'
1344                                 is verified.
1345
1346                         null    Only pretend to verify. Useful for testing
1347                                 internals with ioengine=null, not for much
1348                                 else.
1349
1350                 This option can be used for repeated burn-in tests of a
1351                 system to make sure that the written data is also
1352                 correctly read back. If the data direction given is
1353                 a read or random read, fio will assume that it should
1354                 verify a previously written file. If the data direction
1355                 includes any form of write, the verify will be of the
1356                 newly written data.
1357
1358 verifysort=bool If set, fio will sort written verify blocks when it deems
1359                 it faster to read them back in a sorted manner. This is
1360                 often the case when overwriting an existing file, since
1361                 the blocks are already laid out in the file system. You
1362                 can ignore this option unless doing huge amounts of really
1363                 fast IO where the red-black tree sorting CPU time becomes
1364                 significant.
1365
1366 verify_offset=int       Swap the verification header with data somewhere else
1367                         in the block before writing. Its swapped back before
1368                         verifying.
1369
1370 verify_interval=int     Write the verification header at a finer granularity
1371                         than the blocksize. It will be written for chunks the
1372                         size of header_interval. blocksize should divide this
1373                         evenly.
1374
1375 verify_pattern=str      If set, fio will fill the io buffers with this
1376                 pattern. Fio defaults to filling with totally random
1377                 bytes, but sometimes it's interesting to fill with a known
1378                 pattern for io verification purposes. Depending on the
1379                 width of the pattern, fio will fill 1/2/3/4 bytes of the
1380                 buffer at the time(it can be either a decimal or a hex number).
1381                 The verify_pattern if larger than a 32-bit quantity has to
1382                 be a hex number that starts with either "0x" or "0X". Use
1383                 with verify=str. Also, verify_pattern supports %o format,
1384                 which means that for each block offset will be written and
1385                 then verifyied back, e.g.:
1386
1387                 verify_pattern=%o
1388
1389                 Or use combination of everything:
1390                 verify_pattern=0xff%o"abcd"-12
1391
1392 verify_fatal=bool       Normally fio will keep checking the entire contents
1393                 before quitting on a block verification failure. If this
1394                 option is set, fio will exit the job on the first observed
1395                 failure.
1396
1397 verify_dump=bool        If set, dump the contents of both the original data
1398                 block and the data block we read off disk to files. This
1399                 allows later analysis to inspect just what kind of data
1400                 corruption occurred. Off by default.
1401
1402 verify_async=int        Fio will normally verify IO inline from the submitting
1403                 thread. This option takes an integer describing how many
1404                 async offload threads to create for IO verification instead,
1405                 causing fio to offload the duty of verifying IO contents
1406                 to one or more separate threads. If using this offload
1407                 option, even sync IO engines can benefit from using an
1408                 iodepth setting higher than 1, as it allows them to have
1409                 IO in flight while verifies are running.
1410
1411 verify_async_cpus=str   Tell fio to set the given CPU affinity on the
1412                 async IO verification threads. See cpus_allowed for the
1413                 format used.
1414
1415 verify_backlog=int      Fio will normally verify the written contents of a
1416                 job that utilizes verify once that job has completed. In
1417                 other words, everything is written then everything is read
1418                 back and verified. You may want to verify continually
1419                 instead for a variety of reasons. Fio stores the meta data
1420                 associated with an IO block in memory, so for large
1421                 verify workloads, quite a bit of memory would be used up
1422                 holding this meta data. If this option is enabled, fio
1423                 will write only N blocks before verifying these blocks.
1424
1425 verify_backlog_batch=int        Control how many blocks fio will verify
1426                 if verify_backlog is set. If not set, will default to
1427                 the value of verify_backlog (meaning the entire queue
1428                 is read back and verified).  If verify_backlog_batch is
1429                 less than verify_backlog then not all blocks will be verified,
1430                 if verify_backlog_batch is larger than verify_backlog, some
1431                 blocks will be verified more than once.
1432
1433 verify_state_save=bool  When a job exits during the write phase of a verify
1434                 workload, save its current state. This allows fio to replay
1435                 up until that point, if the verify state is loaded for the
1436                 verify read phase. The format of the filename is, roughly,
1437                 <type>-<jobname>-<jobindex>-verify.state. <type> is "local"
1438                 for a local run, "sock" for a client/server socket connection,
1439                 and "ip" (192.168.0.1, for instance) for a networked
1440                 client/server connection.
1441
1442 verify_state_load=bool  If a verify termination trigger was used, fio stores
1443                 the current write state of each thread. This can be used at
1444                 verification time so that fio knows how far it should verify.
1445                 Without this information, fio will run a full verification
1446                 pass, according to the settings in the job file used.
1447
1448 stonewall
1449 wait_for_previous Wait for preceding jobs in the job file to exit, before
1450                 starting this one. Can be used to insert serialization
1451                 points in the job file. A stone wall also implies starting
1452                 a new reporting group.
1453
1454 new_group       Start a new reporting group. See: group_reporting.
1455
1456 numjobs=int     Create the specified number of clones of this job. May be
1457                 used to setup a larger number of threads/processes doing
1458                 the same thing. Each thread is reported separately; to see
1459                 statistics for all clones as a whole, use group_reporting in
1460                 conjunction with new_group.
1461
1462 group_reporting It may sometimes be interesting to display statistics for
1463                 groups of jobs as a whole instead of for each individual job.
1464                 This is especially true if 'numjobs' is used; looking at
1465                 individual thread/process output quickly becomes unwieldy.
1466                 To see the final report per-group instead of per-job, use
1467                 'group_reporting'. Jobs in a file will be part of the same
1468                 reporting group, unless if separated by a stonewall, or by
1469                 using 'new_group'.
1470
1471 thread          fio defaults to forking jobs, however if this option is
1472                 given, fio will use pthread_create(3) to create threads
1473                 instead.
1474
1475 zonesize=int    Divide a file into zones of the specified size. See zoneskip.
1476
1477 zoneskip=int    Skip the specified number of bytes when zonesize data has
1478                 been read. The two zone options can be used to only do
1479                 io on zones of a file.
1480
1481 write_iolog=str Write the issued io patterns to the specified file. See
1482                 read_iolog.  Specify a separate file for each job, otherwise
1483                 the iologs will be interspersed and the file may be corrupt.
1484
1485 read_iolog=str  Open an iolog with the specified file name and replay the
1486                 io patterns it contains. This can be used to store a
1487                 workload and replay it sometime later. The iolog given
1488                 may also be a blktrace binary file, which allows fio
1489                 to replay a workload captured by blktrace. See blktrace
1490                 for how to capture such logging data. For blktrace replay,
1491                 the file needs to be turned into a blkparse binary data
1492                 file first (blkparse <device> -o /dev/null -d file_for_fio.bin).
1493
1494 replay_no_stall=int When replaying I/O with read_iolog the default behavior
1495                 is to attempt to respect the time stamps within the log and
1496                 replay them with the appropriate delay between IOPS.  By
1497                 setting this variable fio will not respect the timestamps and
1498                 attempt to replay them as fast as possible while still
1499                 respecting ordering.  The result is the same I/O pattern to a
1500                 given device, but different timings.
1501
1502 replay_redirect=str While replaying I/O patterns using read_iolog the
1503                 default behavior is to replay the IOPS onto the major/minor
1504                 device that each IOP was recorded from.  This is sometimes
1505                 undesirable because on a different machine those major/minor
1506                 numbers can map to a different device.  Changing hardware on
1507                 the same system can also result in a different major/minor
1508                 mapping.  Replay_redirect causes all IOPS to be replayed onto
1509                 the single specified device regardless of the device it was
1510                 recorded from. i.e. replay_redirect=/dev/sdc would cause all
1511                 IO in the blktrace to be replayed onto /dev/sdc.  This means
1512                 multiple devices will be replayed onto a single, if the trace
1513                 contains multiple devices.  If you want multiple devices to be
1514                 replayed concurrently to multiple redirected devices you must
1515                 blkparse your trace into separate traces and replay them with
1516                 independent fio invocations.  Unfortuantely this also breaks
1517                 the strict time ordering between multiple device accesses.
1518
1519 replay_align=int        Force alignment of IO offsets and lengths in a trace
1520                 to this power of 2 value.
1521
1522 replay_scale=int        Scale sector offsets down by this factor when
1523                 replaying traces.
1524
1525 per_job_logs=bool       If set, this generates bw/clat/iops log with per
1526                 file private filenames. If not set, jobs with identical names
1527                 will share the log filename. Default: true.
1528
1529 write_bw_log=str If given, write a bandwidth log of the jobs in this job
1530                 file. Can be used to store data of the bandwidth of the
1531                 jobs in their lifetime. The included fio_generate_plots
1532                 script uses gnuplot to turn these text files into nice
1533                 graphs. See write_lat_log for behaviour of given
1534                 filename. For this option, the suffix is _bw.x.log, where
1535                 x is the index of the job (1..N, where N is the number of
1536                 jobs). If 'per_job_logs' is false, then the filename will not
1537                 include the job index.
1538
1539 write_lat_log=str Same as write_bw_log, except that this option stores io
1540                 submission, completion, and total latencies instead. If no
1541                 filename is given with this option, the default filename of
1542                 "jobname_type.log" is used. Even if the filename is given,
1543                 fio will still append the type of log. So if one specifies
1544
1545                 write_lat_log=foo
1546
1547                 The actual log names will be foo_slat.x.log, foo_clat.x.log,
1548                 and foo_lat.x.log, where x is the index of the job (1..N,
1549                 where N is the number of jobs). This helps fio_generate_plot
1550                 fine the logs automatically. If 'per_job_logs' is false, then
1551                 the filename will not include the job index.
1552
1553
1554 write_iops_log=str Same as write_bw_log, but writes IOPS. If no filename is
1555                 given with this option, the default filename of
1556                 "jobname_type.x.log" is used,where x is the index of the job
1557                 (1..N, where N is the number of jobs). Even if the filename
1558                 is given, fio will still append the type of log. If
1559                 'per_job_logs' is false, then the filename will not include
1560                 the job index.
1561
1562 log_avg_msec=int By default, fio will log an entry in the iops, latency,
1563                 or bw log for every IO that completes. When writing to the
1564                 disk log, that can quickly grow to a very large size. Setting
1565                 this option makes fio average the each log entry over the
1566                 specified period of time, reducing the resolution of the log.
1567                 Defaults to 0.
1568
1569 log_offset=int  If this is set, the iolog options will include the byte
1570                 offset for the IO entry as well as the other data values.
1571
1572 log_compression=int     If this is set, fio will compress the IO logs as
1573                 it goes, to keep the memory footprint lower. When a log
1574                 reaches the specified size, that chunk is removed and
1575                 compressed in the background. Given that IO logs are
1576                 fairly highly compressible, this yields a nice memory
1577                 savings for longer runs. The downside is that the
1578                 compression will consume some background CPU cycles, so
1579                 it may impact the run. This, however, is also true if
1580                 the logging ends up consuming most of the system memory.
1581                 So pick your poison. The IO logs are saved normally at the
1582                 end of a run, by decompressing the chunks and storing them
1583                 in the specified log file. This feature depends on the
1584                 availability of zlib.
1585
1586 log_compression_cpus=str        Define the set of CPUs that are allowed to
1587                 handle online log compression for the IO jobs. This can
1588                 provide better isolation between performance sensitive jobs,
1589                 and background compression work.
1590
1591 log_store_compressed=bool       If set, fio will store the log files in a
1592                 compressed format. They can be decompressed with fio, using
1593                 the --inflate-log command line parameter. The files will be
1594                 stored with a .fz suffix.
1595
1596 block_error_percentiles=bool    If set, record errors in trim block-sized
1597                 units from writes and trims and output a histogram of
1598                 how many trims it took to get to errors, and what kind
1599                 of error was encountered.
1600
1601 lockmem=int     Pin down the specified amount of memory with mlock(2). Can
1602                 potentially be used instead of removing memory or booting
1603                 with less memory to simulate a smaller amount of memory.
1604                 The amount specified is per worker.
1605
1606 exec_prerun=str Before running this job, issue the command specified
1607                 through system(3). Output is redirected in a file called
1608                 jobname.prerun.txt.
1609
1610 exec_postrun=str After the job completes, issue the command specified
1611                  though system(3). Output is redirected in a file called
1612                  jobname.postrun.txt.
1613
1614 ioscheduler=str Attempt to switch the device hosting the file to the specified
1615                 io scheduler before running.
1616
1617 disk_util=bool  Generate disk utilization statistics, if the platform
1618                 supports it. Defaults to on.
1619
1620 disable_lat=bool Disable measurements of total latency numbers. Useful
1621                 only for cutting back the number of calls to gettimeofday,
1622                 as that does impact performance at really high IOPS rates.
1623                 Note that to really get rid of a large amount of these
1624                 calls, this option must be used with disable_slat and
1625                 disable_bw as well.
1626
1627 disable_clat=bool Disable measurements of completion latency numbers. See
1628                 disable_lat.
1629
1630 disable_slat=bool Disable measurements of submission latency numbers. See
1631                 disable_slat.
1632
1633 disable_bw=bool Disable measurements of throughput/bandwidth numbers. See
1634                 disable_lat.
1635
1636 clat_percentiles=bool Enable the reporting of percentiles of
1637                  completion latencies.
1638
1639 percentile_list=float_list Overwrite the default list of percentiles
1640                 for completion latencies and the block error histogram.
1641                 Each number is a floating number in the range (0,100],
1642                 and the maximum length of the list is 20. Use ':'
1643                 to separate the numbers, and list the numbers in ascending
1644                 order. For example, --percentile_list=99.5:99.9 will cause
1645                 fio to report the values of completion latency below which
1646                 99.5% and 99.9% of the observed latencies fell, respectively.
1647
1648 clocksource=str Use the given clocksource as the base of timing. The
1649                 supported options are:
1650
1651                         gettimeofday    gettimeofday(2)
1652
1653                         clock_gettime   clock_gettime(2)
1654
1655                         cpu             Internal CPU clock source
1656
1657                 cpu is the preferred clocksource if it is reliable, as it
1658                 is very fast (and fio is heavy on time calls). Fio will
1659                 automatically use this clocksource if it's supported and
1660                 considered reliable on the system it is running on, unless
1661                 another clocksource is specifically set. For x86/x86-64 CPUs,
1662                 this means supporting TSC Invariant.
1663
1664 gtod_reduce=bool Enable all of the gettimeofday() reducing options
1665                 (disable_clat, disable_slat, disable_bw) plus reduce
1666                 precision of the timeout somewhat to really shrink
1667                 the gettimeofday() call count. With this option enabled,
1668                 we only do about 0.4% of the gtod() calls we would have
1669                 done if all time keeping was enabled.
1670
1671 gtod_cpu=int    Sometimes it's cheaper to dedicate a single thread of
1672                 execution to just getting the current time. Fio (and
1673                 databases, for instance) are very intensive on gettimeofday()
1674                 calls. With this option, you can set one CPU aside for
1675                 doing nothing but logging current time to a shared memory
1676                 location. Then the other threads/processes that run IO
1677                 workloads need only copy that segment, instead of entering
1678                 the kernel with a gettimeofday() call. The CPU set aside
1679                 for doing these time calls will be excluded from other
1680                 uses. Fio will manually clear it from the CPU mask of other
1681                 jobs.
1682
1683 continue_on_error=str   Normally fio will exit the job on the first observed
1684                 failure. If this option is set, fio will continue the job when
1685                 there is a 'non-fatal error' (EIO or EILSEQ) until the runtime
1686                 is exceeded or the I/O size specified is completed. If this
1687                 option is used, there are two more stats that are appended,
1688                 the total error count and the first error. The error field
1689                 given in the stats is the first error that was hit during the
1690                 run.
1691
1692                 The allowed values are:
1693
1694                         none    Exit on any IO or verify errors.
1695
1696                         read    Continue on read errors, exit on all others.
1697
1698                         write   Continue on write errors, exit on all others.
1699
1700                         io      Continue on any IO error, exit on all others.
1701
1702                         verify  Continue on verify errors, exit on all others.
1703
1704                         all     Continue on all errors.
1705
1706                         0               Backward-compatible alias for 'none'.
1707
1708                         1               Backward-compatible alias for 'all'.
1709
1710 ignore_error=str Sometimes you want to ignore some errors during test
1711                  in that case you can specify error list for each error type.
1712                  ignore_error=READ_ERR_LIST,WRITE_ERR_LIST,VERIFY_ERR_LIST
1713                  errors for given error type is separated with ':'. Error
1714                  may be symbol ('ENOSPC', 'ENOMEM') or integer.
1715                  Example:
1716                         ignore_error=EAGAIN,ENOSPC:122
1717                  This option will ignore EAGAIN from READ, and ENOSPC and
1718                  122(EDQUOT) from WRITE.
1719
1720 error_dump=bool If set dump every error even if it is non fatal, true
1721                 by default. If disabled only fatal error will be dumped
1722
1723 cgroup=str      Add job to this control group. If it doesn't exist, it will
1724                 be created. The system must have a mounted cgroup blkio
1725                 mount point for this to work. If your system doesn't have it
1726                 mounted, you can do so with:
1727
1728                 # mount -t cgroup -o blkio none /cgroup
1729
1730 cgroup_weight=int       Set the weight of the cgroup to this value. See
1731                 the documentation that comes with the kernel, allowed values
1732                 are in the range of 100..1000.
1733
1734 cgroup_nodelete=bool Normally fio will delete the cgroups it has created after
1735                 the job completion. To override this behavior and to leave
1736                 cgroups around after the job completion, set cgroup_nodelete=1.
1737                 This can be useful if one wants to inspect various cgroup
1738                 files after job completion. Default: false
1739
1740 uid=int         Instead of running as the invoking user, set the user ID to
1741                 this value before the thread/process does any work.
1742
1743 gid=int         Set group ID, see uid.
1744
1745 flow_id=int     The ID of the flow. If not specified, it defaults to being a
1746                 global flow. See flow.
1747
1748 flow=int        Weight in token-based flow control. If this value is used, then
1749                 there is a 'flow counter' which is used to regulate the
1750                 proportion of activity between two or more jobs. fio attempts
1751                 to keep this flow counter near zero. The 'flow' parameter
1752                 stands for how much should be added or subtracted to the flow
1753                 counter on each iteration of the main I/O loop. That is, if
1754                 one job has flow=8 and another job has flow=-1, then there
1755                 will be a roughly 1:8 ratio in how much one runs vs the other.
1756
1757 flow_watermark=int      The maximum value that the absolute value of the flow
1758                 counter is allowed to reach before the job must wait for a
1759                 lower value of the counter.
1760
1761 flow_sleep=int  The period of time, in microseconds, to wait after the flow
1762                 watermark has been exceeded before retrying operations
1763
1764 In addition, there are some parameters which are only valid when a specific
1765 ioengine is in use. These are used identically to normal parameters, with the
1766 caveat that when used on the command line, they must come after the ioengine
1767 that defines them is selected.
1768
1769 [libaio] userspace_reap Normally, with the libaio engine in use, fio will use
1770                 the io_getevents system call to reap newly returned events.
1771                 With this flag turned on, the AIO ring will be read directly
1772                 from user-space to reap events. The reaping mode is only
1773                 enabled when polling for a minimum of 0 events (eg when
1774                 iodepth_batch_complete=0).
1775
1776 [cpu] cpuload=int Attempt to use the specified percentage of CPU cycles.
1777
1778 [cpu] cpuchunks=int Split the load into cycles of the given time. In
1779                 microseconds.
1780
1781 [cpu] exit_on_io_done=bool Detect when IO threads are done, then exit.
1782
1783 [netsplice] hostname=str
1784 [net] hostname=str The host name or IP address to use for TCP or UDP based IO.
1785                 If the job is a TCP listener or UDP reader, the hostname is not
1786                 used and must be omitted unless it is a valid UDP multicast
1787                 address.
1788
1789 [netsplice] port=int
1790 [net] port=int  The TCP or UDP port to bind to or connect to. If this is used
1791 with numjobs to spawn multiple instances of the same job type, then this will
1792 be the starting port number since fio will use a range of ports.
1793
1794 [netsplice] interface=str
1795 [net] interface=str  The IP address of the network interface used to send or
1796                 receive UDP multicast
1797
1798 [netsplice] ttl=int
1799 [net] ttl=int   Time-to-live value for outgoing UDP multicast packets.
1800                 Default: 1
1801
1802 [netsplice] nodelay=bool
1803 [net] nodelay=bool      Set TCP_NODELAY on TCP connections.
1804
1805 [netsplice] protocol=str
1806 [netsplice] proto=str
1807 [net] protocol=str
1808 [net] proto=str The network protocol to use. Accepted values are:
1809
1810                         tcp     Transmission control protocol
1811                         tcpv6   Transmission control protocol V6
1812                         udp     User datagram protocol
1813                         udpv6   User datagram protocol V6
1814                         unix    UNIX domain socket
1815
1816                 When the protocol is TCP or UDP, the port must also be given,
1817                 as well as the hostname if the job is a TCP listener or UDP
1818                 reader. For unix sockets, the normal filename option should be
1819                 used and the port is invalid.
1820
1821 [net] listen    For TCP network connections, tell fio to listen for incoming
1822                 connections rather than initiating an outgoing connection. The
1823                 hostname must be omitted if this option is used.
1824
1825 [net] pingpong  Normaly a network writer will just continue writing data, and
1826                 a network reader will just consume packages. If pingpong=1
1827                 is set, a writer will send its normal payload to the reader,
1828                 then wait for the reader to send the same payload back. This
1829                 allows fio to measure network latencies. The submission
1830                 and completion latencies then measure local time spent
1831                 sending or receiving, and the completion latency measures
1832                 how long it took for the other end to receive and send back.
1833                 For UDP multicast traffic pingpong=1 should only be set for a
1834                 single reader when multiple readers are listening to the same
1835                 address.
1836
1837 [net] window_size       Set the desired socket buffer size for the connection.
1838
1839 [net] mss       Set the TCP maximum segment size (TCP_MAXSEG).
1840
1841 [e4defrag] donorname=str
1842                 File will be used as a block donor(swap extents between files)
1843 [e4defrag] inplace=int
1844                 Configure donor file blocks allocation strategy
1845                 0(default): Preallocate donor's file on init
1846                 1         : allocate space immidietly inside defragment event,
1847                             and free right after event
1848
1849 [mtd] skip_bad=bool     Skip operations against known bad blocks.
1850
1851
1852 6.0 Interpreting the output
1853 ---------------------------
1854
1855 fio spits out a lot of output. While running, fio will display the
1856 status of the jobs created. An example of that would be:
1857
1858 Threads: 1: [_r] [24.8% done] [ 13509/  8334 kb/s] [eta 00h:01m:31s]
1859
1860 The characters inside the square brackets denote the current status of
1861 each thread. The possible values (in typical life cycle order) are:
1862
1863 Idle    Run
1864 ----    ---
1865 P               Thread setup, but not started.
1866 C               Thread created.
1867 I               Thread initialized, waiting or generating necessary data.
1868         p       Thread running pre-reading file(s).
1869         R       Running, doing sequential reads.
1870         r       Running, doing random reads.
1871         W       Running, doing sequential writes.
1872         w       Running, doing random writes.
1873         M       Running, doing mixed sequential reads/writes.
1874         m       Running, doing mixed random reads/writes.
1875         F       Running, currently waiting for fsync()
1876         f       Running, finishing up (writing IO logs, etc)
1877         V       Running, doing verification of written data.
1878 E               Thread exited, not reaped by main thread yet.
1879 _               Thread reaped, or
1880 X               Thread reaped, exited with an error.
1881 K               Thread reaped, exited due to signal.
1882
1883 Fio will condense the thread string as not to take up more space on the
1884 command line as is needed. For instance, if you have 10 readers and 10
1885 writers running, the output would look like this:
1886
1887 Jobs: 20 (f=20): [R(10),W(10)] [4.0% done] [2103MB/0KB/0KB /s] [538K/0/0 iops] [eta 57m:36s]
1888
1889 Fio will still maintain the ordering, though. So the above means that jobs
1890 1..10 are readers, and 11..20 are writers.
1891
1892 The other values are fairly self explanatory - number of threads
1893 currently running and doing io, rate of io since last check (read speed
1894 listed first, then write speed), and the estimated completion percentage
1895 and time for the running group. It's impossible to estimate runtime of
1896 the following groups (if any). Note that the string is displayed in order,
1897 so it's possible to tell which of the jobs are currently doing what. The
1898 first character is the first job defined in the job file, and so forth.
1899
1900 When fio is done (or interrupted by ctrl-c), it will show the data for
1901 each thread, group of threads, and disks in that order. For each data
1902 direction, the output looks like:
1903
1904 Client1 (g=0): err= 0:
1905   write: io=    32MB, bw=   666KB/s, iops=89 , runt= 50320msec
1906     slat (msec): min=    0, max=  136, avg= 0.03, stdev= 1.92
1907     clat (msec): min=    0, max=  631, avg=48.50, stdev=86.82
1908     bw (KB/s) : min=    0, max= 1196, per=51.00%, avg=664.02, stdev=681.68
1909   cpu        : usr=1.49%, sys=0.25%, ctx=7969, majf=0, minf=17
1910   IO depths    : 1=0.1%, 2=0.3%, 4=0.5%, 8=99.0%, 16=0.0%, 32=0.0%, >32=0.0%
1911      submit    : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0%
1912      complete  : 0=0.0%, 4=100.0%, 8=0.0%, 16=0.0%, 32=0.0%, 64=0.0%, >=64=0.0%
1913      issued r/w: total=0/32768, short=0/0
1914      lat (msec): 2=1.6%, 4=0.0%, 10=3.2%, 20=12.8%, 50=38.4%, 100=24.8%,
1915      lat (msec): 250=15.2%, 500=0.0%, 750=0.0%, 1000=0.0%, >=2048=0.0%
1916
1917 The client number is printed, along with the group id and error of that
1918 thread. Below is the io statistics, here for writes. In the order listed,
1919 they denote:
1920
1921 io=             Number of megabytes io performed
1922 bw=             Average bandwidth rate
1923 iops=           Average IOs performed per second
1924 runt=           The runtime of that thread
1925         slat=   Submission latency (avg being the average, stdev being the
1926                 standard deviation). This is the time it took to submit
1927                 the io. For sync io, the slat is really the completion
1928                 latency, since queue/complete is one operation there. This
1929                 value can be in milliseconds or microseconds, fio will choose
1930                 the most appropriate base and print that. In the example
1931                 above, milliseconds is the best scale. Note: in --minimal mode
1932                 latencies are always expressed in microseconds.
1933         clat=   Completion latency. Same names as slat, this denotes the
1934                 time from submission to completion of the io pieces. For
1935                 sync io, clat will usually be equal (or very close) to 0,
1936                 as the time from submit to complete is basically just
1937                 CPU time (io has already been done, see slat explanation).
1938         bw=     Bandwidth. Same names as the xlat stats, but also includes
1939                 an approximate percentage of total aggregate bandwidth
1940                 this thread received in this group. This last value is
1941                 only really useful if the threads in this group are on the
1942                 same disk, since they are then competing for disk access.
1943 cpu=            CPU usage. User and system time, along with the number
1944                 of context switches this thread went through, usage of
1945                 system and user time, and finally the number of major
1946                 and minor page faults.
1947 IO depths=      The distribution of io depths over the job life time. The
1948                 numbers are divided into powers of 2, so for example the
1949                 16= entries includes depths up to that value but higher
1950                 than the previous entry. In other words, it covers the
1951                 range from 16 to 31.
1952 IO submit=      How many pieces of IO were submitting in a single submit
1953                 call. Each entry denotes that amount and below, until
1954                 the previous entry - eg, 8=100% mean that we submitted
1955                 anywhere in between 5-8 ios per submit call.
1956 IO complete=    Like the above submit number, but for completions instead.
1957 IO issued=      The number of read/write requests issued, and how many
1958                 of them were short.
1959 IO latencies=   The distribution of IO completion latencies. This is the
1960                 time from when IO leaves fio and when it gets completed.
1961                 The numbers follow the same pattern as the IO depths,
1962                 meaning that 2=1.6% means that 1.6% of the IO completed
1963                 within 2 msecs, 20=12.8% means that 12.8% of the IO
1964                 took more than 10 msecs, but less than (or equal to) 20 msecs.
1965
1966 After each client has been listed, the group statistics are printed. They
1967 will look like this:
1968
1969 Run status group 0 (all jobs):
1970    READ: io=64MB, aggrb=22178, minb=11355, maxb=11814, mint=2840msec, maxt=2955msec
1971   WRITE: io=64MB, aggrb=1302, minb=666, maxb=669, mint=50093msec, maxt=50320msec
1972
1973 For each data direction, it prints:
1974
1975 io=             Number of megabytes io performed.
1976 aggrb=          Aggregate bandwidth of threads in this group.
1977 minb=           The minimum average bandwidth a thread saw.
1978 maxb=           The maximum average bandwidth a thread saw.
1979 mint=           The smallest runtime of the threads in that group.
1980 maxt=           The longest runtime of the threads in that group.
1981
1982 And finally, the disk statistics are printed. They will look like this:
1983
1984 Disk stats (read/write):
1985   sda: ios=16398/16511, merge=30/162, ticks=6853/819634, in_queue=826487, util=100.00%
1986
1987 Each value is printed for both reads and writes, with reads first. The
1988 numbers denote:
1989
1990 ios=            Number of ios performed by all groups.
1991 merge=          Number of merges io the io scheduler.
1992 ticks=          Number of ticks we kept the disk busy.
1993 io_queue=       Total time spent in the disk queue.
1994 util=           The disk utilization. A value of 100% means we kept the disk
1995                 busy constantly, 50% would be a disk idling half of the time.
1996
1997 It is also possible to get fio to dump the current output while it is
1998 running, without terminating the job. To do that, send fio the USR1 signal.
1999 You can also get regularly timed dumps by using the --status-interval
2000 parameter, or by creating a file in /tmp named fio-dump-status. If fio
2001 sees this file, it will unlink it and dump the current output status.
2002
2003
2004 7.0 Terse output
2005 ----------------
2006
2007 For scripted usage where you typically want to generate tables or graphs
2008 of the results, fio can output the results in a semicolon separated format.
2009 The format is one long line of values, such as:
2010
2011 2;card0;0;0;7139336;121836;60004;1;10109;27.932460;116.933948;220;126861;3495.446807;1085.368601;226;126864;3523.635629;1089.012448;24063;99944;50.275485%;59818.274627;5540.657370;7155060;122104;60004;1;8338;29.086342;117.839068;388;128077;5032.488518;1234.785715;391;128085;5061.839412;1236.909129;23436;100928;50.287926%;59964.832030;5644.844189;14.595833%;19.394167%;123706;0;7313;0.1%;0.1%;0.1%;0.1%;0.1%;0.1%;100.0%;0.00%;0.00%;0.00%;0.00%;0.00%;0.00%;0.01%;0.02%;0.05%;0.16%;6.04%;40.40%;52.68%;0.64%;0.01%;0.00%;0.01%;0.00%;0.00%;0.00%;0.00%;0.00%
2012 A description of this job goes here.
2013
2014 The job description (if provided) follows on a second line.
2015
2016 To enable terse output, use the --minimal command line option. The first
2017 value is the version of the terse output format. If the output has to
2018 be changed for some reason, this number will be incremented by 1 to
2019 signify that change.
2020
2021 Split up, the format is as follows:
2022
2023         terse version, fio version, jobname, groupid, error
2024         READ status:
2025                 Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)
2026                 Submission latency: min, max, mean, stdev (usec)
2027                 Completion latency: min, max, mean, stdev (usec)
2028                 Completion latency percentiles: 20 fields (see below)
2029                 Total latency: min, max, mean, stdev (usec)
2030                 Bw (KB/s): min, max, aggregate percentage of total, mean, stdev
2031         WRITE status:
2032                 Total IO (KB), bandwidth (KB/sec), IOPS, runtime (msec)
2033                 Submission latency: min, max, mean, stdev (usec)
2034                 Completion latency: min, max, mean, stdev(usec)
2035                 Completion latency percentiles: 20 fields (see below)
2036                 Total latency: min, max, mean, stdev (usec)
2037                 Bw (KB/s): min, max, aggregate percentage of total, mean, stdev
2038         CPU usage: user, system, context switches, major faults, minor faults
2039         IO depths: <=1, 2, 4, 8, 16, 32, >=64
2040         IO latencies microseconds: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000
2041         IO latencies milliseconds: <=2, 4, 10, 20, 50, 100, 250, 500, 750, 1000, 2000, >=2000
2042         Disk utilization: Disk name, Read ios, write ios,
2043                           Read merges, write merges,
2044                           Read ticks, write ticks,
2045                           Time spent in queue, disk utilization percentage
2046         Additional Info (dependent on continue_on_error, default off): total # errors, first error code
2047
2048         Additional Info (dependent on description being set): Text description
2049
2050 Completion latency percentiles can be a grouping of up to 20 sets, so
2051 for the terse output fio writes all of them. Each field will look like this:
2052
2053         1.00%=6112
2054
2055 which is the Xth percentile, and the usec latency associated with it.
2056
2057 For disk utilization, all disks used by fio are shown. So for each disk
2058 there will be a disk utilization section.
2059
2060
2061 8.0 Trace file format
2062 ---------------------
2063 There are two trace file format that you can encounter. The older (v1) format
2064 is unsupported since version 1.20-rc3 (March 2008). It will still be described
2065 below in case that you get an old trace and want to understand it.
2066
2067 In any case the trace is a simple text file with a single action per line.
2068
2069
2070 8.1 Trace file format v1
2071 ------------------------
2072 Each line represents a single io action in the following format:
2073
2074 rw, offset, length
2075
2076 where rw=0/1 for read/write, and the offset and length entries being in bytes.
2077
2078 This format is not supported in Fio versions => 1.20-rc3.
2079
2080
2081 8.2 Trace file format v2
2082 ------------------------
2083 The second version of the trace file format was added in Fio version 1.17.
2084 It allows to access more then one file per trace and has a bigger set of
2085 possible file actions.
2086
2087 The first line of the trace file has to be:
2088
2089 fio version 2 iolog
2090
2091 Following this can be lines in two different formats, which are described below.
2092
2093 The file management format:
2094
2095 filename action
2096
2097 The filename is given as an absolute path. The action can be one of these:
2098
2099 add          Add the given filename to the trace
2100 open         Open the file with the given filename. The filename has to have
2101              been added with the add action before.
2102 close        Close the file with the given filename. The file has to have been
2103              opened before.
2104
2105
2106 The file io action format:
2107
2108 filename action offset length
2109
2110 The filename is given as an absolute path, and has to have been added and opened
2111 before it can be used with this format. The offset and length are given in
2112 bytes. The action can be one of these:
2113
2114 wait       Wait for 'offset' microseconds. Everything below 100 is discarded.
2115            The time is relative to the previous wait statement.
2116 read       Read 'length' bytes beginning from 'offset'
2117 write      Write 'length' bytes beginning from 'offset'
2118 sync       fsync() the file
2119 datasync   fdatasync() the file
2120 trim       trim the given file from the given 'offset' for 'length' bytes
2121
2122
2123 9.0 CPU idleness profiling
2124 --------------------------
2125 In some cases, we want to understand CPU overhead in a test. For example,
2126 we test patches for the specific goodness of whether they reduce CPU usage.
2127 fio implements a balloon approach to create a thread per CPU that runs at
2128 idle priority, meaning that it only runs when nobody else needs the cpu.
2129 By measuring the amount of work completed by the thread, idleness of each
2130 CPU can be derived accordingly.
2131
2132 An unit work is defined as touching a full page of unsigned characters. Mean
2133 and standard deviation of time to complete an unit work is reported in "unit
2134 work" section. Options can be chosen to report detailed percpu idleness or
2135 overall system idleness by aggregating percpu stats.
2136
2137
2138 10.0 Verification and triggers
2139 ------------------------------
2140 Fio is usually run in one of two ways, when data verification is done. The
2141 first is a normal write job of some sort with verify enabled. When the
2142 write phase has completed, fio switches to reads and verifies everything
2143 it wrote. The second model is running just the write phase, and then later
2144 on running the same job (but with reads instead of writes) to repeat the
2145 same IO patterns and verify the contents. Both of these methods depend
2146 on the write phase being completed, as fio otherwise has no idea how much
2147 data was written.
2148
2149 With verification triggers, fio supports dumping the current write state
2150 to local files. Then a subsequent read verify workload can load this state
2151 and know exactly where to stop. This is useful for testing cases where
2152 power is cut to a server in a managed fashion, for instance.
2153
2154 A verification trigger consists of two things:
2155
2156 1) Storing the write state of each job
2157 2) Executing a trigger command
2158
2159 The write state is relatively small, on the order of hundreds of bytes
2160 to single kilobytes. It contains information on the number of completions
2161 done, the last X completions, etc.
2162
2163 A trigger is invoked either through creation ('touch') of a specified
2164 file in the system, or through a timeout setting. If fio is run with
2165 --trigger-file=/tmp/trigger-file, then it will continually check for
2166 the existence of /tmp/trigger-file. When it sees this file, it will
2167 fire off the trigger (thus saving state, and executing the trigger
2168 command).
2169
2170 For client/server runs, there's both a local and remote trigger. If
2171 fio is running as a server backend, it will send the job states back
2172 to the client for safe storage, then execute the remote trigger, if
2173 specified. If a local trigger is specified, the server will still send
2174 back the write state, but the client will then execute the trigger.
2175
2176 10.1 Verification trigger example
2177 ---------------------------------
2178 Lets say we want to run a powercut test on the remote machine 'server'.
2179 Our write workload is in write-test.fio. We want to cut power to 'server'
2180 at some point during the run, and we'll run this test from the safety
2181 or our local machine, 'localbox'. On the server, we'll start the fio
2182 backend normally:
2183
2184 server# fio --server
2185
2186 and on the client, we'll fire off the workload:
2187
2188 localbox$ fio --client=server --trigger-file=/tmp/my-trigger --trigger-remote="bash -c \"echo b > /proc/sysrq-triger\""
2189
2190 We set /tmp/my-trigger as the trigger file, and we tell fio to execute
2191
2192 echo b > /proc/sysrq-trigger
2193
2194 on the server once it has received the trigger and sent us the write
2195 state. This will work, but it's not _really_ cutting power to the server,
2196 it's merely abruptly rebooting it. If we have a remote way of cutting
2197 power to the server through IPMI or similar, we could do that through
2198 a local trigger command instead. Lets assume we have a script that does
2199 IPMI reboot of a given hostname, ipmi-reboot. On localbox, we could
2200 then have run fio with a local trigger instead:
2201
2202 localbox$ fio --client=server --trigger-file=/tmp/my-trigger --trigger="ipmi-reboot server"
2203
2204 For this case, fio would wait for the server to send us the write state,
2205 then execute 'ipmi-reboot server' when that happened.
2206
2207 10.1 Loading verify state
2208 -------------------------
2209 To load store write state, read verification job file must contain
2210 the verify_state_load option. If that is set, fio will load the previously
2211 stored state. For a local fio run this is done by loading the files directly,
2212 and on a client/server run, the server backend will ask the client to send
2213 the files over and load them from there.