fio howto (2) job file format

• fio HOWTO

fio accepts one or more job files describing what it is supposed to do.

The job file format is the classic ini file, where the names
enclosed in [] brackets define the job name. You are free to use any ASCII name you want, except global which has special meaning.

Following the job name is a sequence of zero or more parameters, one per line, that define the behavior of the job. If the first character in a line is a ';' or a '#', the entire line is discarded as a comment.

A global section sets defaults for the jobs described in that file. A job may override a global section parameter, and a job file may even have several global sections if so desired. A job is only affected by a global section residing above it.

The --cmdhelp option also lists all options. If used with a command argument, --cmdhelp will detail the given command.

See the examples/ directory for inspiration on how to write job files. Note the copyright and license requirements currently apply to examples/ files.

So let's look at a really simple job file that defines two processes, each
randomly reading from a 128MiB file:

        ; -- start job file --
        [global]
        rw=randread
        size=128m

        [job1]

        [job2]

        ; -- end job file --

As you can see, the job file sections themselves are empty as all the described parameters are shared. As no filename option is given, fio makes up a filename for each of the jobs as it sees fit. On the command line, this job would look as follows::

    $ fio --name=global --rw=randread --size=128m --name=job1 --name=job2

Let's look at an example that has a number of processes writing randomly to files:

        ; -- start job file --
        [random-writers]
        ioengine=libaio
        iodepth=4
        rw=randwrite
        bs=32k
        direct=0
        size=64m
        numjobs=4
        ; -- end job file --

Here we have no global section, as we only have one job defined anyway. We want to use async I/O here, with a depth of 4 for each file. We also increased the buffer size used to 32KiB and define numjobs to 4 to fork 4 identical jobs. The result is 4 processes each randomly writing to their own 64MiB file. Instead of using the above job file, you could have given the parameters on the command line. For this case, you would specify:

    $ fio --name=random-writers --ioengine=libaio --iodepth=4 
          --rw=randwrite --bs=32k --direct=0 --size=64m --numjobs=4

include

When fio is utilized as a basis of any reasonably large test suite, it might be desirable to share a set of standardized settings across multiple job files. Instead of copy/pasting such settings, any section may pull in an external filename.fio file with include filename directive, as in the following example:

        ; -- start job file glob-include.fio --
        thread=1
        group_reporting=1
        ; -- end job file glob-include.fio --

        ; -- start job file test-include.fio --
        ioengine=libaio
        iodepth=4
        ; -- end job file test-include.fio --

        ; -- start job file including.fio --
        [global]
        filename=/tmp/test
        filesize=1m
        include glob-include.fio

        [test]
        rw=randread
        bs=4k
        time_based=1
        runtime=10
        include test-include.fio
        ; -- end job file including.fio --

Settings pulled into a section apply to that section only (except global
section). Include directives may be nested in that any included file may contain further include directive(s). Include files may not contain [] sections.