README

   1 fio
   2 ---
   3
   4 fio is a tool that will spawn a number of threads or processes doing a
   5 particular type of io action as specified by the user. fio takes a
   6 number of global parameters, each inherited by the thread unless
   7 otherwise parameters given to them overriding that setting is given.
   8 The typical use of fio is to write a job file matching the io load
   9 one wants to simulate.
  10
  11
  12 Source
  13 ------
  14
  15 fio resides in a git repo, the canonical place is:
  16
  17 git://git.kernel.dk/fio.git
  18
  19 If you are inside a corporate firewall, git:// may not always work for
  20 you. In that case you can use the http protocol, path is the same:
  21
  22 http://git.kernel.dk/fio.git
  23
  24 Snapshots are frequently generated and they include the git meta data as
  25 well. You can download them here:
  26
  27 http://brick.kernel.dk/snaps/
  28
  29
  30 Binary packages
  31 ---------------
  32
  33 Debian:
  34 Starting with Debian "Squeeze", fio packages are part of the official
  35 Debian repository. http://packages.debian.org/search?keywords=fio
  36
  37 Ubuntu:
  38 Starting with Ubuntu 10.04 LTS (aka "Lucid Lynx"), fio packages are part
  39 of the Ubuntu "universe" repository.
  40 http://packages.ubuntu.com/search?keywords=fio
  41
  42 Red Hat, CentOS & Co:
  43 Dag Wieërs has RPMs for Red Hat related distros, find them here:
  44 http://dag.wieers.com/rpm/packages/fio/
  45
  46 Mandriva:
  47 Mandriva has integrated fio into their package repository, so installing
  48 on that distro should be as easy as typing 'urpmi fio'.
  49
  50 Solaris:
  51 Packages for Solaris are available from OpenCSW. Install their pkgutil
  52 tool (http://www.opencsw.org/get-it/pkgutil/) and then install fio via
  53 'pkgutil -i fio'.
  54
  55 Windows:
  56 Bruce Cran <bruce@cran.org.uk> has fio packages for Windows at
  57 http://www.bluestop.org/fio/ .
  58
  59
  60 Mailing list
  61 ------------
  62
  63 There's a mailing list associated with fio. It's meant for general
  64 discussion, bug reporting, questions, and development - basically anything
  65 that has to do with fio. An automated mail detailing recent commits is
  66 automatically sent to the list at most daily. The list address is
  67 fio@vger.kernel.org, subscribe by sending an email to
  68 majordomo@vger.kernel.org with
  69
  70 subscribe fio
  71
  72 in the body of the email. Archives can be found here:
  73
  74 http://www.spinics.net/lists/fio/
  75
  76 and archives for the old list can be found here:
  77
  78 http://maillist.kernel.dk/fio-devel/
  79
  80
  81 Building
  82 --------
  83
  84 Just type 'make' and 'make install'.
  85
  86 Note that GNU make is required. On BSD it's available from devel/gmake;
  87 on Solaris it's in the SUNWgmake package. On platforms where GNU make
  88 isn't the default, type 'gmake' instead of 'make'.
  89
  90 If your compile fails with an error like this:
  91
  92     CC gettime.o
  93 In file included from fio.h:23,
  94                  from gettime.c:8:
  95 os/os.h:15:20: error: libaio.h: No such file or directory
  96 In file included from gettime.c:8:
  97 fio.h:119: error: field 'iocb' has incomplete type
  98 make: *** [gettime.o] Error 1
  99
 100 Check that you have the libaio development package installed. On RPM
 101 based distros, it's typically called libaio-devel.
 102
 103
 104 Windows
 105 -------
 106
 107 On Windows Cygwin (http://www.cygwin.com/) is required in order to
 108 build fio. To create an MSI installer package install WiX 3.7 from
 109 http://wixtoolset.org and run dobuild.cmd from the
 110 os/windows directory.
 111
 112 How to compile FIO on 64-bit Windows:
 113
 114  1. Install Cygwin (http://www.cygwin.com/setup.exe). Install 'make' and all
 115     packages starting with 'mingw64-i686' and 'mingw64-x86_64'.
 116  2. Download ftp://sourceware.org/pub/pthreads-win32/prebuilt-dll-2-9-1-release/dll/x64/pthreadGC2.dll
 117     and copy to the fio source directory.
 118  3. Open the Cygwin Terminal.
 119  4. Go to the fio directory (source files).
 120  5. Run 'make clean'.
 121  6. Run 'make'.
 122
 123 To build fio on 32-bit Windows, download x86/pthreadGC2.dll instead and do
 124 './configure --build-32bit-win=yes' before 'make'.
 125
 126 It's recommended that once built or installed, fio be run in a Command Prompt
 127 or other 'native' console such as console2, since there are known to be display
 128 and signal issues when running it under a Cygwin shell
 129 (see http://code.google.com/p/mintty/issues/detail?id=56 for details).
 130
 131
 132 Command line
 133 ------------
 134
 135 $ fio
 136         --debug                 Enable some debugging options (see below)
 137         --parse-only            Parse options only, don't start any IO
 138         --output                Write output to file
 139         --runtime               Runtime in seconds
 140         --latency-log           Generate per-job latency logs
 141         --bandwidth-log         Generate per-job bandwidth logs
 142         --minimal               Minimal (terse) output
 143         --output-format=type    Output format (terse,json,normal)
 144         --terse-version=type    Terse version output format (default 3, or 2 or 4).
 145         --version               Print version info and exit
 146         --help                  Print this page
 147         --cpuclock-test         Perform test/validation of CPU clock
 148         --cmdhelp=cmd           Print command help, "all" for all of them
 149         --enghelp=engine        Print ioengine help, or list available ioengines
 150         --enghelp=engine,cmd    Print help for an ioengine cmd
 151         --showcmd               Turn a job file into command line options
 152         --readonly              Turn on safety read-only checks, preventing
 153                                 writes
 154         --eta=when              When ETA estimate should be printed
 155                                 May be "always", "never" or "auto"
 156         --eta-newline=time      Force a new line for every 'time' period passed
 157         --section=name          Only run specified section in job file.
 158                                 Multiple sections can be specified.
 159         --alloc-size=kb         Set smalloc pool to this size in kb (def 1024)
 160         --warnings-fatal        Fio parser warnings are fatal
 161         --max-jobs              Maximum number of threads/processes to support
 162         --server=args           Start backend server. See Client/Server section.
 163         --client=host           Connect to specified backend.
 164         --idle-prof=option      Report cpu idleness on a system or percpu basis
 165                                 (option=system,percpu) or run unit work
 166                                 calibration only (option=calibrate).
 167
 168
 169 Any parameters following the options will be assumed to be job files,
 170 unless they match a job file parameter. You can add as many as you want,
 171 each job file will be regarded as a separate group and fio will stonewall
 172 its execution.
 173
 174 The --readonly switch is an extra safety guard to prevent accidentally
 175 turning on a write setting when that is not desired. Fio will only write
 176 if rw=write/randwrite/rw/randrw is given, but this extra safety net can
 177 be used as an extra precaution. It will also enable a write check in the
 178 io engine core to prevent an accidental write due to a fio bug.
 179
 180 The debug switch allows adding options that trigger certain logging
 181 options in fio. Currently the options are:
 182
 183         process         Dump info related to processes
 184         file            Dump info related to file actions
 185         io              Dump info related to IO queuing
 186         mem             Dump info related to memory allocations
 187         blktrace        Dump info related to blktrace setup
 188         verify          Dump info related to IO verification
 189         all             Enable all debug options
 190         random          Dump info related to random offset generation
 191         parse           Dump info related to option matching and parsing
 192         diskutil        Dump info related to disk utilization updates
 193         job:x           Dump info only related to job number x
 194         mutex           Dump info only related to mutex up/down ops
 195         profile         Dump info related to profile extensions
 196         time            Dump info related to internal time keeping
 197         ? or help       Show available debug options.
 198
 199 You can specify as many as you want, eg --debug=file,mem will enable
 200 file and memory debugging.
 201
 202 The section switch is meant to make it easier to ship a bigger job file
 203 instead of several smaller ones. Say you define a job file with light,
 204 moderate, and heavy parts. Then you can ask fio to run the given part
 205 only by giving it a --section=heavy command line option. The section
 206 option only applies to job sections, the reserved 'global' section is
 207 always parsed and taken into account.
 208
 209 Fio has an internal allocator for shared memory called smalloc. It
 210 allocates shared structures from this pool. The pool defaults to 1024k
 211 in size, and can grow to 128 pools. If running large jobs with randommap
 212 enabled it can run out of memory, in which case the --alloc-size switch
 213 is handy for starting with a larger pool size. The backing store is
 214 files in /tmp. Fio cleans up after itself, while it is running you
 215 may see .fio_smalloc.* files in /tmp.
 216
 217
 218 Job file
 219 --------
 220
 221 See the HOWTO file for a more detailed description of parameters and what
 222 they mean. This file contains the terse version. You can describe big and
 223 complex setups with the command line, but generally it's a lot easier to
 224 just write a simple job file to describe the workload. The job file format
 225 is in the ini style format, as that is easy to read and write for the user.
 226
 227 The HOWTO or man page has a full list of all options, along with
 228 descriptions, etc. The --cmdhelp option also lists all options. If
 229 used with an option argument, it will detail that particular option.
 230
 231
 232 Client/server
 233 ------------
 234
 235 Normally you would run fio as a stand-alone application on the machine
 236 where the IO workload should be generated. However, it is also possible to
 237 run the frontend and backend of fio separately. This makes it possible to
 238 have a fio server running on the machine(s) where the IO workload should
 239 be running, while controlling it from another machine.
 240
 241 To start the server, you would do:
 242
 243 fio --server=args
 244
 245 on that machine, where args defines what fio listens to. The arguments
 246 are of the form 'type,hostname or IP,port'. 'type' is either 'ip' (or ip4)
 247 for TCP/IP v4, 'ip6' for TCP/IP v6, or 'sock' for a local unix domain socket.
 248 'hostname' is either a hostname or IP address, and 'port' is the port to
 249 listen to (only valid for TCP/IP, not a local socket). Some examples:
 250
 251 1) fio --server
 252
 253    Start a fio server, listening on all interfaces on the default port (8765).
 254
 255 2) fio --server=ip:hostname,4444
 256
 257    Start a fio server, listening on IP belonging to hostname and on port 4444.
 258
 259 3) fio --server=ip6:::1,4444
 260
 261    Start a fio server, listening on IPv6 localhost ::1 and on port 4444.
 262
 263 4) fio --server=,4444
 264
 265    Start a fio server, listening on all interfaces on port 4444.
 266
 267 5) fio --server=1.2.3.4
 268
 269    Start a fio server, listening on IP 1.2.3.4 on the default port.
 270
 271 6) fio --server=sock:/tmp/fio.sock
 272
 273    Start a fio server, listening on the local socket /tmp/fio.sock.
 274
 275 When a server is running, you can connect to it from a client. The client
 276 is run with:
 277
 278 fio --local-args --client=server --remote-args <job file(s)>
 279
 280 where --local-args are arguments that are local to the client where it is
 281 running, 'server' is the connect string, and --remote-args and <job file(s)>
 282 are sent to the server. The 'server' string follows the same format as it
 283 does on the server side, to allow IP/hostname/socket and port strings.
 284 You can connect to multiple clients as well, to do that you could run:
 285
 286 fio --client=server2 <job file(s)> --client=server2 <job file(s)>
 287
 288
 289 Platforms
 290 ---------
 291
 292 Fio works on (at least) Linux, Solaris, AIX, HP-UX, OSX, NetBSD, Windows
 293 and FreeBSD.  Some features and/or options may only be available on some of
 294 the platforms, typically because those features only apply to that platform
 295 (like the solarisaio engine, or the splice engine on Linux).
 296
 297 Some features are not available on FreeBSD/Solaris even if they could be
 298 implemented, I'd be happy to take patches for that. An example of that is
 299 disk utility statistics and (I think) huge page support, support for that
 300 does exist in FreeBSD/Solaris.
 301
 302 Fio uses pthread mutexes for signalling and locking and FreeBSD does not
 303 support process shared pthread mutexes. As a result, only threads are
 304 supported on FreeBSD. This could be fixed with sysv ipc locking or
 305 other locking alternatives.
 306
 307 Other *BSD platforms are untested, but fio should work there almost out
 308 of the box. Since I don't do test runs or even compiles on those platforms,
 309 your mileage may vary. Sending me patches for other platforms is greatly
 310 appreciated. There's a lot of value in having the same test/benchmark tool
 311 available on all platforms.
 312
 313 Note that POSIX aio is not enabled by default on AIX. If you get messages like:
 314
 315     Symbol resolution failed for /usr/lib/libc.a(posix_aio.o) because:
 316         Symbol _posix_kaio_rdwr (number 2) is not exported from dependent module /unix.
 317
 318 you need to enable POSIX aio. Run the following commands as root:
 319
 320     # lsdev -C -l posix_aio0
 321         posix_aio0 Defined  Posix Asynchronous I/O
 322     # cfgmgr -l posix_aio0
 323     # lsdev -C -l posix_aio0
 324         posix_aio0 Available  Posix Asynchronous I/O
 325
 326 POSIX aio should work now. To make the change permanent:
 327
 328     # chdev -l posix_aio0 -P -a autoconfig='available'
 329         posix_aio0 changed
 330
 331
 332 Author
 333 ------
 334
 335 Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing
 336 of the Linux IO subsystem and schedulers. He got tired of writing
 337 specific test applications to simulate a given workload, and found that
 338 the existing io benchmark/test tools out there weren't flexible enough
 339 to do what he wanted.
 340
 341 Jens Axboe <axboe@kernel.dk> 20060905
 342