INTRODUCTION

Please DO NOT run iorate program without setting the input (*.ior) files
correctly, or ** CATASTOPHIC DATA LOSS ** can occur.

Iorate is designed as a storage performance benchmakring tool. It can be
used to model a wide variety of potential workloads.


INSTRUCTIONS

For usage, run iorate -h. The man page attempts to be more complete. Best
would be to download the User Guide from http://iorate.org. It is also a
good idea to check for new code there before starting testing. New bugs
are found and fixed, though not always in a timely manner. The latest
release should have the fewest old bugs - though there is always the
chance for some new ones. Please report any problems you have to
vince.westin@emc.com, and we will work to resolve the issue.

There is no installation procedure needed. This tool is designed to be
run as a part of a testing effort. The tool is dangerous enough that it
should not be installed into general use directories like
/usr/local/bin. Note that root access is usually needed to write to the
raw deivce files, and on many systems to read from them. Having a
version of iorate with seduid to root to allow this from more general
users is also not recommended, again due to the risk of the tool being
used incorrectly.

In general, there are input files for the devices to run I/O against (in
devices.ior), patterns for the I/O (in patterns.ior), and test made up
of groups of patterns (in tests.ior). All devices in the devices file
will be tested against, and if the patterns contain writes, the
contents of those files/devices will be damaged. This is similar to
handling a fully automatic weapon --  be careful where you point it.

With the 3.0 code base, the ability to have the test hit areas of each
device unevenly has been introduced. This is designed to help in
testing the automated tiering code within storage arrays. There are
some example files provided to help build sub-LUN skew tests.

SAMPLE FILES

Samples of each of the default files have been provided with the
distribution. The devices included are not valid, so the program cannot
accidentaly be run against local devices without reading through the
files and making some changes. An early release had more useful default
names, and at least one poor user wiped out their operating system
before modifying the files. Each of the default files also has some
comments to help with file syntax, in addition to the example values.

The devices.ior file provided has examples of both a device file and a
file on a file system. Both types of devices can be used in the same
test. Note that file systems usually provide buffering, which can change
the number of I/Os going to the storage array.

The patterns.ior file provided has examples of the basic patterns for
random and sequential I/O at various block sizes. It also has some
examples of more advanced patterns.

The tests.ior file provided has a set of read-only tests. These are
called bus bandwith tests because they are specifically designed to move
data from array cache to host cache and not drive any physical I/O. This
provides a method of ensuring that the connections between the test
server and the array are working as planned. It also provides an easy
test to check that buffering is not happening on the host. These default
tests are read-only.

The tests-fx.ior file has a model of the array profiling tests that led
to the creation of iorate. These can be interesting for understanding
the boundaries of performance at differrent read/write and sequential/
random ratios. Note that it may be necessary to flood the read and/or
write cache of the array to help these tests achieve a steady state 
before a true profile of the array or drives can be obtained.

The tests-ast.ior file is included as a start on testing storage arrays
with automated tiering. Automated storage tiering became somewhat common
by 2011, and many customers are looking at how to compare the
effectiveness of the various vendor options. Hopefully this will help.
The tests-var.ior file is a variation on the storage tiering file, with
a limit on the IOPS target for the test. This is for the scripts that
use it to generata a variable workload over time.

TOOLS

Compiled versions for multiple operating systems are usually available
on http://iorate.org. The source code for each version is also
available there. While the GNU compiler is used most often in the
creation of the binary distributions, the native compilers should be
fairly compatible. Adjustments to the complier flags may be needed.

In addition to the iorate program, ior_rand is a compiled random number
generator. This program is used my some scripts to randomize some of the
decisions.

The gen_devices script uses syminq to create a list of all of the
devices visible on the host. These devices are formatted for use in the
devices.ior file. The results can be edited to refine the devices to
test against. Customers without EMC Solutions Enabler installed can
download a static binary of this inquiry tool from
ftp://ftp.emc.com/pub/elab/inquiry. The script will then need to be
updated to use the downloaded binary.

The gen_sums script creates a summary of the results of an iorate test.
It runs against the resulting .perf file, reducing the results from all
the devices to a single test summary. If the sub-LUN testing is active,
a summary of that data is included.

The gen_totals script creates a quick sumamry total for test data in the
./data directory. It makes use of the gen_sums script to get to the
underlying test summaries.

The gen_stats script is specifically designed to help make performance
data with sub-LUN skew active more readable. It splits these values out
onto separate lines with variable indentation to help readability. Note
that these layouts will break the 'all data on one line' model for the
.perf file, and will make the data difficult to import into other
applications. It is focused on making this human readable.

As a note, turing on debugging (-d) with sub-LUN testing active will
generate additional information in the resulting .perf file. This
creates more than 100 records per device. As many versions of AWK cannot
deal with more than 99 records per line, several of the tools will not
operate on these resulting files.

The run_test script is designed to run a single test. Variables in the
script can be updated to run the tests in various iterations and at
different target IOPS rates. It uses the gen_iops script to generate
an IOPS target file to use for testing at less than 100% workload
levels.

The run_ast script is designed to run a test against an array with
automated storage tiering active. It can easily be modified to alter the
shift in the skew to cause changes in where the sub-LUN activity is
focused.

The run_var script is designed to prvide a variable workload against an
array. It uses the sub-LUN skew shift to move the focus areas of the
test over time. It also varies the overall I/O level between the limits
set in the script.


PORTABILITY

We have succeeded in porting IORATE to a variety of UNIX-derived
platforms with minimal change.  Some platforms present a larger
challenge.  Since some systems do not have yacc (or bison) installed,
the source distribution includes parser output. However, without these
tools installed, the needed libraries are likely to be missing anway...

Windows has a vastly different process structure. As such, there is no
simple way to port this code. Perhaps someone with experience in dealing
with Microsoft Windows process threads would be willing to offer some
sample code dealing with a master process, forking child threads, and
monitoring those threads for completion. Until then, such a port is
unlikely to be seriously attempted. (There was a port done with Cygwin
a while back, but with only one testing process it was rather
pointless.)

It is possible that iorate could be rebuilt as a back-end testing
structure under iometer, since iometer has the GUI and the cross-system
scaling design completed. It also has real-time monitoring of results.
This is a project that is under consideration. And volunteers to help
would be welcome.

