IOGEN(8)                OpenBSD System Manager's Manual               IOGEN(8)

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 de-
             fault 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.  Un-
             der 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 se-
     quentially 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 ev-
     ery 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.

OpenBSD 4.1                    December 6, 2005                              2