Add support for compiling for ESX
[fio.git] / README
CommitLineData
ebac4655
JA
1fio
2---
3
79809113
JA
4fio is a tool that will spawn a number of threads or processes doing a
5particular type of io action as specified by the user. fio takes a
6number of global parameters, each inherited by the thread unless
7otherwise parameters given to them overriding that setting is given.
8The typical use of fio is to write a job file matching the io load
9one wants to simulate.
ebac4655 10
2b02b546
JA
11
12Source
13------
14
15fio resides in a git repo, the canonical place is:
16
4649b352 17 git://git.kernel.dk/fio.git
97f049c9 18
4649b352
GG
19When inside a corporate firewall, git:// URL sometimes does not work.
20If git:// does not work, use the http protocol instead:
a9bac3f9 21
4649b352 22 http://git.kernel.dk/fio.git
2b02b546 23
4649b352
GG
24Snapshots are frequently generated and include the git meta data as well.
25Snapshots can download from:
2b02b546 26
4649b352 27 http://brick.kernel.dk/snaps/
2b02b546 28
1053a106 29
d85b1add
SK
30Binary packages
31---------------
32
33Debian:
34Starting with Debian "Squeeze", fio packages are part of the official
35Debian repository. http://packages.debian.org/search?keywords=fio
36
37Ubuntu:
38Starting with Ubuntu 10.04 LTS (aka "Lucid Lynx"), fio packages are part
39of the Ubuntu "universe" repository.
40http://packages.ubuntu.com/search?keywords=fio
41
d85b1add 42Red Hat, CentOS & Co:
a68594cb 43Dag Wieërs has RPMs for Red Hat related distros, find them here:
a68594cb
JA
44http://dag.wieers.com/rpm/packages/fio/
45
d85b1add 46Mandriva:
244e170e
JA
47Mandriva has integrated fio into their package repository, so installing
48on that distro should be as easy as typing 'urpmi fio'.
49
d85b1add
SK
50Solaris:
51Packages for Solaris are available from OpenCSW. Install their pkgutil
52tool (http://www.opencsw.org/get-it/pkgutil/) and then install fio via
53'pkgutil -i fio'.
54
ecc314ba
BC
55Windows:
56Bruce Cran <bruce@cran.org.uk> has fio packages for Windows at
78080867 57http://www.bluestop.org/fio/ .
ecc314ba 58
2b02b546 59
726f6ff0
JA
60Mailing list
61------------
62
4649b352
GG
63The fio project mailing list is meant for anything related to fio including
64general discussion, bug reporting, questions, and development.
2e8552b0 65
4649b352
GG
66An automated mail detailing recent commits is automatically sent to the
67list at most daily. The list address is fio@vger.kernel.org, subscribe
68by sending an email to majordomo@vger.kernel.org with
69
70 subscribe fio
2e8552b0 71
4f5d1526
EIB
72in the body of the email. Archives can be found here:
73
4649b352 74 http://www.spinics.net/lists/fio/
4f5d1526
EIB
75
76and archives for the old list can be found here:
2e8552b0 77
4649b352 78 http://maillist.kernel.dk/fio-devel/
726f6ff0
JA
79
80
bbfd6b00
JA
81Building
82--------
83
6e1e384e 84Just type 'configure', 'make' and 'make install'.
bbfd6b00 85
d015e398
BC
86Note that GNU make is required. On BSD it's available from devel/gmake;
87on Solaris it's in the SUNWgmake package. On platforms where GNU make
88isn't the default, type 'gmake' instead of 'make'.
bbfd6b00 89
6e1e384e 90Configure will print the enabled options. Note that on Linux based
4649b352
GG
91platforms, the libaio development packages must be installed to use
92the libaio engine. Depending on distro, it is usually called
93libaio-devel or libaio-dev.
6de43c1b 94
4649b352
GG
95For gfio, gtk 2.18 (or newer), associated glib threads, and cairo are required
96to be installed. gfio isn't built automatically and can be enabled
6e1e384e 97with a --enable-gfio option to configure.
6de43c1b 98
2382dca7
AC
99To build FIO with a cross-compiler:
100 $ make clean
101 $ make CROSS_COMPILE=/path/to/toolchain/prefix
102Configure will attempt to determine the target platform automatically.
103
c8931876
JA
104It's possible to build fio for ESX as well, use the --esx switch to
105configure.
106
bbfd6b00 107
53adf64f
BC
108Windows
109-------
110
9aa5fe32
BC
111On Windows, Cygwin (http://www.cygwin.com/) is required in order to
112build fio. To create an MSI installer package install WiX 3.8 from
f41862f7 113http://wixtoolset.org and run dobuild.cmd from the
93bcfd20 114os/windows directory.
53adf64f 115
9aa5fe32 116How to compile fio on 64-bit Windows:
f41862f7 117
9aa5fe32 118 1. Install Cygwin (http://www.cygwin.com/). Install 'make' and all
f41862f7 119 packages starting with 'mingw64-i686' and 'mingw64-x86_64'.
9aa5fe32
BC
120 2. Open the Cygwin Terminal.
121 3. Go to the fio directory (source files).
122 4. Run 'make clean && make -j'.
123
124To build fio on 32-bit Windows, run './configure --build-32bit-win' before 'make'.
7409711b 125
78080867
BC
126It's recommended that once built or installed, fio be run in a Command Prompt
127or other 'native' console such as console2, since there are known to be display
128and signal issues when running it under a Cygwin shell
129(see http://code.google.com/p/mintty/issues/detail?id=56 for details).
130
53adf64f 131
972cfd25
JA
132Command line
133------------
ebac4655
JA
134
135$ fio
1cfd036f 136 --debug Enable some debugging options (see below)
111e032d 137 --parse-only Parse options only, don't start any IO
1cfd036f 138 --output Write output to file
b2cecdc2 139 --runtime Runtime in seconds
bebe6398
JA
140 --latency-log Generate per-job latency logs
141 --bandwidth-log Generate per-job bandwidth logs
1cfd036f 142 --minimal Minimal (terse) output
f3afa57e 143 --output-format=type Output format (terse,json,normal)
3449ab8c 144 --terse-version=type Terse version output format (default 3, or 2 or 4).
f3afa57e 145 --version Print version info and exit
1cfd036f 146 --help Print this page
23893646 147 --cpuclock-test Perform test/validation of CPU clock
005f702b 148 --crctest[=test] Test speed of checksum functions
bebe6398 149 --cmdhelp=cmd Print command help, "all" for all of them
de890a1e
SL
150 --enghelp=engine Print ioengine help, or list available ioengines
151 --enghelp=engine,cmd Print help for an ioengine cmd
1cfd036f 152 --showcmd Turn a job file into command line options
ad0a2735 153 --readonly Turn on safety read-only checks, preventing
bebe6398 154 writes
1cfd036f 155 --eta=when When ETA estimate should be printed
bebe6398 156 May be "always", "never" or "auto"
e382e661 157 --eta-newline=time Force a new line for every 'time' period passed
06464907 158 --status-interval=t Force full status dump every 't' period passed
bebe6398
JA
159 --section=name Only run specified section in job file.
160 Multiple sections can be specified.
e7cb819b 161 --alloc-size=kb Set smalloc pool to this size in kb (def 1024)
162 --warnings-fatal Fio parser warnings are fatal
fca70358 163 --max-jobs Maximum number of threads/processes to support
bebe6398
JA
164 --server=args Start backend server. See Client/Server section.
165 --client=host Connect to specified backend.
f2a2ce0e
HL
166 --idle-prof=option Report cpu idleness on a system or percpu basis
167 (option=system,percpu) or run unit work
168 calibration only (option=calibrate).
e592a06b 169
b4692828
JA
170
171Any parameters following the options will be assumed to be job files,
4649b352
GG
172unless they match a job file parameter. Multiple job files can be listed
173and each job file will be regarded as a separate group. fio will stonewall
174execution between each group.
972cfd25 175
4649b352
GG
176The --readonly option is an extra safety guard to prevent users from
177accidentally starting a write workload when that is not desired. Fio
178will only write if rw=write/randwrite/rw/randrw is given. This extra
179safety net can be used as an extra precaution as --readonly will also
180enable a write check in the io engine core to prevent writes due to
181unknown user space bug(s).
724e4435 182
4649b352
GG
183The --debug option triggers additional logging by fio.
184Currently, additional logging is available for:
ee56ad50
JA
185
186 process Dump info related to processes
187 file Dump info related to file actions
e7cb819b 188 io Dump info related to IO queuing
189 mem Dump info related to memory allocations
bd6f78b2
JA
190 blktrace Dump info related to blktrace setup
191 verify Dump info related to IO verification
e7cb819b 192 all Enable all debug options
811a0d06 193 random Dump info related to random offset generation
a3d741fa 194 parse Dump info related to option matching and parsing
cd991b9e 195 diskutil Dump info related to disk utilization updates
5e1d306e 196 job:x Dump info only related to job number x
29adda3c 197 mutex Dump info only related to mutex up/down ops
c223da83
JA
198 profile Dump info related to profile extensions
199 time Dump info related to internal time keeping
3e260a46
JA
200 net Dump info related to networking connections
201 rate Dump info related to IO rate switching
bd6f78b2 202 ? or help Show available debug options.
ee56ad50 203
4649b352 204One can specify multiple debug options: e.g. --debug=file,mem will enable
bd6f78b2 205file and memory debugging.
ee56ad50 206
4649b352
GG
207The --section option allows one to combine related jobs into one file.
208E.g. one job file could define light, moderate, and heavy sections. Tell fio to
209run only the "heavy" section by giving --section=heavy command line option.
210One can also specify the "write" operations in one section and "verify"
211operation in another section. The --section option only applies to job
212sections. The reserved 'global' section is always parsed and used.
213
214The --alloc-size switch allows one to use a larger pool size for smalloc.
215If running large jobs with randommap enabled, fio can run out of memory.
216Smalloc is an internal allocator for shared structures from a fixed size
217memory pool. The pool size defaults to 1024k and can grow to 128 pools.
01f06b63 218
4649b352 219NOTE: While running .fio_smalloc.* backing store files are visible in /tmp.
2b386d25 220
79809113
JA
221
222Job file
223--------
224
4649b352
GG
225See the HOWTO file for a complete description of job file syntax and
226parameters. The --cmdhelp option also lists all options. If used with
227an option argument, --cmdhelp will detail the given option. The job file
228format is in the ini style format, as that is easy for the user to review
229and modify.
79809113 230
4649b352
GG
231This README contains the terse version. Job files can describe big and
232complex setups that are not possible with the command line. Job files
233are a good practice even for simple jobs since the file provides an
234easily accessed record of the workload and can include comments.
235
236See the examples/ directory for inspiration on how to write job files. Note
237the copyright and license requirements currently apply to examples/ files.
79809113 238
217bc04b 239
bebe6398
JA
240Client/server
241------------
242
4649b352
GG
243Normally fio is invoked as a stand-alone application on the machine
244where the IO workload should be generated. However, the frontend and
245backend of fio can be run separately. Ie the fio server can generate
246an IO workload on the "Device Under Test" while being controlled from
247another machine.
bebe6398 248
4649b352 249Start the server on the machine which has access to the storage DUT:
bebe6398
JA
250
251fio --server=args
252
4649b352
GG
253where args defines what fio listens to. The arguments are of the form
254'type,hostname or IP,port'. 'type' is either 'ip' (or ip4) for TCP/IP v4,
255'ip6' for TCP/IP v6, or 'sock' for a local unix domain socket.
811826be
JA
256'hostname' is either a hostname or IP address, and 'port' is the port to
257listen to (only valid for TCP/IP, not a local socket). Some examples:
bebe6398
JA
258
2591) fio --server
260
261 Start a fio server, listening on all interfaces on the default port (8765).
262
811826be 2632) fio --server=ip:hostname,4444
bebe6398
JA
264
265 Start a fio server, listening on IP belonging to hostname and on port 4444.
266
811826be
JA
2673) fio --server=ip6:::1,4444
268
269 Start a fio server, listening on IPv6 localhost ::1 and on port 4444.
270
2714) fio --server=,4444
bebe6398
JA
272
273 Start a fio server, listening on all interfaces on port 4444.
274
811826be 2755) fio --server=1.2.3.4
bebe6398
JA
276
277 Start a fio server, listening on IP 1.2.3.4 on the default port.
278
811826be 2796) fio --server=sock:/tmp/fio.sock
bebe6398
JA
280
281 Start a fio server, listening on the local socket /tmp/fio.sock.
282
4649b352 283Once a server is running, a "client" can connect to the fio server with:
bebe6398 284
4649b352 285fio --local-args --client=<server> --remote-args <job file(s)>
bebe6398 286
4649b352 287where --local-args are arguments for the client where it is
bebe6398
JA
288running, 'server' is the connect string, and --remote-args and <job file(s)>
289are sent to the server. The 'server' string follows the same format as it
290does on the server side, to allow IP/hostname/socket and port strings.
bebe6398 291
4649b352
GG
292Fio can connect to multiple servers this way:
293
294fio --client=<server1> <job file(s)> --client=<server2> <job file(s)>
bebe6398
JA
295
296
217bc04b
JA
297Platforms
298---------
299
1b8c5af7
JA
300Fio works on (at least) Linux, Solaris, AIX, HP-UX, OSX, NetBSD, OpenBSD,
301Windows and FreeBSD. Some features and/or options may only be available on
302some of the platforms, typically because those features only apply to that
303platform (like the solarisaio engine, or the splice engine on Linux).
217bc04b
JA
304
305Some features are not available on FreeBSD/Solaris even if they could be
306implemented, I'd be happy to take patches for that. An example of that is
307disk utility statistics and (I think) huge page support, support for that
308does exist in FreeBSD/Solaris.
309
310Fio uses pthread mutexes for signalling and locking and FreeBSD does not
311support process shared pthread mutexes. As a result, only threads are
312supported on FreeBSD. This could be fixed with sysv ipc locking or
313other locking alternatives.
314
315Other *BSD platforms are untested, but fio should work there almost out
316of the box. Since I don't do test runs or even compiles on those platforms,
317your mileage may vary. Sending me patches for other platforms is greatly
318appreciated. There's a lot of value in having the same test/benchmark tool
319available on all platforms.
320
4649b352 321Note that POSIX aio is not enabled by default on AIX. Messages like these:
bf2e821a
CC
322
323 Symbol resolution failed for /usr/lib/libc.a(posix_aio.o) because:
324 Symbol _posix_kaio_rdwr (number 2) is not exported from dependent module /unix.
325
4649b352 326indicate one needs to enable POSIX aio. Run the following commands as root:
bf2e821a
CC
327
328 # lsdev -C -l posix_aio0
329 posix_aio0 Defined Posix Asynchronous I/O
330 # cfgmgr -l posix_aio0
331 # lsdev -C -l posix_aio0
332 posix_aio0 Available Posix Asynchronous I/O
333
334POSIX aio should work now. To make the change permanent:
335
336 # chdev -l posix_aio0 -P -a autoconfig='available'
337 posix_aio0 changed
217bc04b
JA
338
339
79809113
JA
340Author
341------
342
aae22ca7 343Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing
79809113
JA
344of the Linux IO subsystem and schedulers. He got tired of writing
345specific test applications to simulate a given workload, and found that
346the existing io benchmark/test tools out there weren't flexible enough
347to do what he wanted.
348
aae22ca7 349Jens Axboe <axboe@kernel.dk> 20060905
79809113 350