Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  IOGEN (8)


iogen - I/O generator




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


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.


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


The first version of iogen was written in 2005.


.An Marco Peereboom Aq


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.
Search for    or go to Top of page |  Section 8 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.