IOGEN(8) BSD System Manager's Manual IOGEN(8)NAMEiogen — I/O generator
SYNOPSISiogen [-kr] [-b max-io-size] [-d target-directory] [-f result-directory]
[-n nr-forks] [-p read-percentage] [-s max-file-size]
[-t update-time]
DESCRIPTIONiogen 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 statis‐
tics. 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 cur‐
rent 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 some‐
thing bad happens.
BSD December 6, 2005 BSD
