iogen(8) - Linux man page

Name

iogen - I/O generator

Synopsis

iogen [-kr] [-b max-io-size] [-d target-directory] [-f result-directory] [-n nr-forks] [-p read-percentage] [-s max-file-size] [-t update-time]

Description

iogen is a lightweight tool that generates heavily fragmented I/O. It accomplishes this by forking a number of children that run I/O to a filesystem.

This tool is intended to test storage stacks under stress and worst case scenarios. However due to heavy fragmentation of the I/O files, it tends to bypass caching algorithms in storage stacks.

The options are as follows:

       -b max-io-size

This is the fixed I/O size unless the -r flag is set. The default is 64KB.

-d target-directory
This is the directory where the I/O file will be written to. The default is the current working directory.

-f result-directory
This is the directory where the result file will be written to. The result file is updated every update-time seconds with statistics. The default is the current working directory.

-k' Kill all running iogen processes.

-n nr-forks
This will determine how many identical processes will be forked to run I/O. The default is 1.

-p read-percentage
This determins the read vs write distribution. The range is from 10% to 90%. The default is 50.

-P pattern
Pattern is a whole number that designates the IO pattern. The default is a text pattern that is human readable. Use ? to print out the available patterns.

-r' Randomize I/O size between 1 and max-io-size. Enabling this flag will disable data verification. The default is disabled.

-s max-file-size
The file where the I/O is run to and from will grow sequentially until it is bigger or equal to this value. At that point all write I/O will also become random. The default is 1GB.

-t update-time
This determines the minimal amount of time between updates. Under heavy I/O this value can be skewed due to the asynchronous nature of alarm(3). The default is 60 seconds.

-T I/O timeout
This determines the maximum time an I/O run is allowed to take to complete. If the timeout is reached all iogen processes will be terminated. The default is disabled.

Although the algorithm for I/O generation is incredibly simple, it has proven to be very effective at bringing out issues in storage stacks. It first grows the initial file a minimal amount to be able to start running I/O in it. After the initial growth, it reads randomly within the current file size. Every run is a distribution between reads and writes which is governed by the read percentage value. The file is grown sequentially until it reaches maximum file size. Whenever this happens a message is logged to syslogd(8) and all writes become random.

To monitor progress one can tail(1) the result file which is updated every update-time interval or send the process a HUP signal. Whenever an I/O process receives a HUP signal, it prints statistical values to stderr(4) at its earliest convenience.

Whenever iogen runs into data corruption or a failed read or write it will terminate all child processes.

Examples

Run iogen with all defaults in the current working directory:

$ iogen

Run iogen with all defaults and a 1 second result file update:

$ iogen -t 1

Run iogen with a 2GB max file, 128KB I/O size, and result file in /tmp:

$ iogen -s 2g -b 128k -t 1 -f /tmp

History

The first version of iogen was written in 2005.

Authors

Marco Peereboom <marco@peereboom.us>

Caveats

This tool is capable of running extremely heavy I/O. It is known to have broken hardware before so please use caution and don't complain if something bad happens.

BSD December 6, 2005 BSD