| 1 | Overview and history |
| 2 | -------------------- |
| 3 | |
| 4 | Fio was originally written to save me the hassle of writing special test case |
| 5 | programs when I wanted to test a specific workload, either for performance |
| 6 | reasons or to find/reproduce a bug. The process of writing such a test app can |
| 7 | be tiresome, especially if you have to do it often. Hence I needed a tool that |
| 8 | would be able to simulate a given I/O workload without resorting to writing a |
| 9 | tailored test case again and again. |
| 10 | |
| 11 | A test work load is difficult to define, though. There can be any number of |
| 12 | processes or threads involved, and they can each be using their own way of |
| 13 | generating I/O. You could have someone dirtying large amounts of memory in a |
| 14 | memory mapped file, or maybe several threads issuing reads using asynchronous |
| 15 | I/O. fio needed to be flexible enough to simulate both of these cases, and many |
| 16 | more. |
| 17 | |
| 18 | Fio spawns a number of threads or processes doing a particular type of I/O |
| 19 | action as specified by the user. fio takes a number of global parameters, each |
| 20 | inherited by the thread unless otherwise parameters given to them overriding |
| 21 | that setting is given. The typical use of fio is to write a job file matching |
| 22 | the I/O load one wants to simulate. |
| 23 | |
| 24 | |
| 25 | Source |
| 26 | ------ |
| 27 | |
| 28 | Fio resides in a git repo, the canonical place is: |
| 29 | |
| 30 | git://git.kernel.dk/fio.git |
| 31 | |
| 32 | When inside a corporate firewall, git:// URL sometimes does not work. |
| 33 | If git:// does not work, use the http protocol instead: |
| 34 | |
| 35 | http://git.kernel.dk/fio.git |
| 36 | |
| 37 | Snapshots are frequently generated and :file:`fio-git-*.tar.gz` include the git |
| 38 | meta data as well. Other tarballs are archives of official fio releases. |
| 39 | Snapshots can download from: |
| 40 | |
| 41 | http://brick.kernel.dk/snaps/ |
| 42 | |
| 43 | There are also two official mirrors. Both of these are automatically synced with |
| 44 | the main repository, when changes are pushed. If the main repo is down for some |
| 45 | reason, either one of these is safe to use as a backup: |
| 46 | |
| 47 | git://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git |
| 48 | |
| 49 | https://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git |
| 50 | |
| 51 | or |
| 52 | |
| 53 | git://github.com/axboe/fio.git |
| 54 | |
| 55 | https://github.com/axboe/fio.git |
| 56 | |
| 57 | |
| 58 | Mailing list |
| 59 | ------------ |
| 60 | |
| 61 | The fio project mailing list is meant for anything related to fio including |
| 62 | general discussion, bug reporting, questions, and development. For bug reporting, |
| 63 | see REPORTING-BUGS. |
| 64 | |
| 65 | An automated mail detailing recent commits is automatically sent to the list at |
| 66 | most daily. The list address is fio@vger.kernel.org, subscribe by sending an |
| 67 | email to majordomo@vger.kernel.org with |
| 68 | |
| 69 | subscribe fio |
| 70 | |
| 71 | in the body of the email. Archives can be found here: |
| 72 | |
| 73 | http://www.spinics.net/lists/fio/ |
| 74 | |
| 75 | or here: |
| 76 | |
| 77 | https://lore.kernel.org/fio/ |
| 78 | |
| 79 | and archives for the old list can be found here: |
| 80 | |
| 81 | http://maillist.kernel.dk/fio-devel/ |
| 82 | |
| 83 | |
| 84 | Author |
| 85 | ------ |
| 86 | |
| 87 | Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing of |
| 88 | the Linux I/O subsystem and schedulers. He got tired of writing specific test |
| 89 | applications to simulate a given workload, and found that the existing I/O |
| 90 | benchmark/test tools out there weren't flexible enough to do what he wanted. |
| 91 | |
| 92 | Jens Axboe <axboe@kernel.dk> 20060905 |
| 93 | |
| 94 | |
| 95 | Binary packages |
| 96 | --------------- |
| 97 | |
| 98 | Debian: |
| 99 | Starting with Debian "Squeeze", fio packages are part of the official |
| 100 | Debian repository. http://packages.debian.org/search?keywords=fio . |
| 101 | |
| 102 | Ubuntu: |
| 103 | Starting with Ubuntu 10.04 LTS (aka "Lucid Lynx"), fio packages are part |
| 104 | of the Ubuntu "universe" repository. |
| 105 | http://packages.ubuntu.com/search?keywords=fio . |
| 106 | |
| 107 | Red Hat, Fedora, CentOS & Co: |
| 108 | Starting with Fedora 9/Extra Packages for Enterprise Linux 4, fio |
| 109 | packages are part of the Fedora/EPEL repositories. |
| 110 | https://apps.fedoraproject.org/packages/fio . |
| 111 | |
| 112 | Mandriva: |
| 113 | Mandriva has integrated fio into their package repository, so installing |
| 114 | on that distro should be as easy as typing ``urpmi fio``. |
| 115 | |
| 116 | Arch Linux: |
| 117 | An Arch Linux package is provided under the Community sub-repository: |
| 118 | https://www.archlinux.org/packages/?sort=&q=fio |
| 119 | |
| 120 | Solaris: |
| 121 | Packages for Solaris are available from OpenCSW. Install their pkgutil |
| 122 | tool (http://www.opencsw.org/get-it/pkgutil/) and then install fio via |
| 123 | ``pkgutil -i fio``. |
| 124 | |
| 125 | Windows: |
| 126 | Rebecca Cran <rebecca@bsdio.com> has fio packages for Windows at |
| 127 | https://bsdio.com/fio/ . The latest builds for Windows can also |
| 128 | be grabbed from https://ci.appveyor.com/project/axboe/fio by clicking |
| 129 | the latest x86 or x64 build, then selecting the ARTIFACTS tab. |
| 130 | |
| 131 | BSDs: |
| 132 | Packages for BSDs may be available from their binary package repositories. |
| 133 | Look for a package "fio" using their binary package managers. |
| 134 | |
| 135 | |
| 136 | Building |
| 137 | -------- |
| 138 | |
| 139 | Just type:: |
| 140 | |
| 141 | $ ./configure |
| 142 | $ make |
| 143 | $ make install |
| 144 | |
| 145 | Note that GNU make is required. On BSDs it's available from devel/gmake within |
| 146 | ports directory; on Solaris it's in the SUNWgmake package. On platforms where |
| 147 | GNU make isn't the default, type ``gmake`` instead of ``make``. |
| 148 | |
| 149 | Configure will print the enabled options. Note that on Linux based platforms, |
| 150 | the libaio development packages must be installed to use the libaio |
| 151 | engine. Depending on distro, it is usually called libaio-devel or libaio-dev. |
| 152 | |
| 153 | For gfio, gtk 2.18 (or newer), associated glib threads, and cairo are required |
| 154 | to be installed. gfio isn't built automatically and can be enabled with a |
| 155 | ``--enable-gfio`` option to configure. |
| 156 | |
| 157 | To build fio with a cross-compiler:: |
| 158 | |
| 159 | $ make clean |
| 160 | $ make CROSS_COMPILE=/path/to/toolchain/prefix |
| 161 | |
| 162 | Configure will attempt to determine the target platform automatically. |
| 163 | |
| 164 | It's possible to build fio for ESX as well, use the ``--esx`` switch to |
| 165 | configure. |
| 166 | |
| 167 | |
| 168 | Windows |
| 169 | ~~~~~~~ |
| 170 | |
| 171 | The minimum versions of Windows for building/runing fio are Windows 7/Windows |
| 172 | Server 2008 R2. On Windows, Cygwin (https://www.cygwin.com/) is required in |
| 173 | order to build fio. To create an MSI installer package install WiX from |
| 174 | https://wixtoolset.org and run :file:`dobuild.cmd` from the :file:`os/windows` |
| 175 | directory. |
| 176 | |
| 177 | How to compile fio on 64-bit Windows: |
| 178 | |
| 179 | 1. Install Cygwin (http://www.cygwin.com/). Install **make** and all |
| 180 | packages starting with **mingw64-x86_64**. Ensure |
| 181 | **mingw64-x86_64-zlib** are installed if you wish |
| 182 | to enable fio's log compression functionality. |
| 183 | 2. Open the Cygwin Terminal. |
| 184 | 3. Go to the fio directory (source files). |
| 185 | 4. Run ``make clean && make -j``. |
| 186 | |
| 187 | To build fio for 32-bit Windows, ensure the -i686 versions of the previously |
| 188 | mentioned -x86_64 packages are installed and run ``./configure |
| 189 | --build-32bit-win`` before ``make``. |
| 190 | |
| 191 | It's recommended that once built or installed, fio be run in a Command Prompt or |
| 192 | other 'native' console such as console2, since there are known to be display and |
| 193 | signal issues when running it under a Cygwin shell (see |
| 194 | https://github.com/mintty/mintty/issues/56 and |
| 195 | https://github.com/mintty/mintty/wiki/Tips#inputoutput-interaction-with-alien-programs |
| 196 | for details). |
| 197 | |
| 198 | |
| 199 | Documentation |
| 200 | ~~~~~~~~~~~~~ |
| 201 | |
| 202 | Fio uses Sphinx_ to generate documentation from the reStructuredText_ files. |
| 203 | To build HTML formatted documentation run ``make -C doc html`` and direct your |
| 204 | browser to :file:`./doc/output/html/index.html`. To build manual page run |
| 205 | ``make -C doc man`` and then ``man doc/output/man/fio.1``. To see what other |
| 206 | output formats are supported run ``make -C doc help``. |
| 207 | |
| 208 | .. _reStructuredText: http://www.sphinx-doc.org/rest.html |
| 209 | .. _Sphinx: http://www.sphinx-doc.org |
| 210 | |
| 211 | |
| 212 | Platforms |
| 213 | --------- |
| 214 | |
| 215 | Fio works on (at least) Linux, Solaris, AIX, HP-UX, OSX, NetBSD, OpenBSD, |
| 216 | Windows, FreeBSD, and DragonFly. Some features and/or options may only be |
| 217 | available on some of the platforms, typically because those features only apply |
| 218 | to that platform (like the solarisaio engine, or the splice engine on Linux). |
| 219 | |
| 220 | Some features are not available on FreeBSD/Solaris even if they could be |
| 221 | implemented, I'd be happy to take patches for that. An example of that is disk |
| 222 | utility statistics and (I think) huge page support, support for that does exist |
| 223 | in FreeBSD/Solaris. |
| 224 | |
| 225 | Fio uses pthread mutexes for signalling and locking and some platforms do not |
| 226 | support process shared pthread mutexes. As a result, on such platforms only |
| 227 | threads are supported. This could be fixed with sysv ipc locking or other |
| 228 | locking alternatives. |
| 229 | |
| 230 | Other \*BSD platforms are untested, but fio should work there almost out of the |
| 231 | box. Since I don't do test runs or even compiles on those platforms, your |
| 232 | mileage may vary. Sending me patches for other platforms is greatly |
| 233 | appreciated. There's a lot of value in having the same test/benchmark tool |
| 234 | available on all platforms. |
| 235 | |
| 236 | Note that POSIX aio is not enabled by default on AIX. Messages like these:: |
| 237 | |
| 238 | Symbol resolution failed for /usr/lib/libc.a(posix_aio.o) because: |
| 239 | Symbol _posix_kaio_rdwr (number 2) is not exported from dependent module /unix. |
| 240 | |
| 241 | indicate one needs to enable POSIX aio. Run the following commands as root:: |
| 242 | |
| 243 | # lsdev -C -l posix_aio0 |
| 244 | posix_aio0 Defined Posix Asynchronous I/O |
| 245 | # cfgmgr -l posix_aio0 |
| 246 | # lsdev -C -l posix_aio0 |
| 247 | posix_aio0 Available Posix Asynchronous I/O |
| 248 | |
| 249 | POSIX aio should work now. To make the change permanent:: |
| 250 | |
| 251 | # chdev -l posix_aio0 -P -a autoconfig='available' |
| 252 | posix_aio0 changed |
| 253 | |
| 254 | |
| 255 | Running fio |
| 256 | ----------- |
| 257 | |
| 258 | Running fio is normally the easiest part - you just give it the job file |
| 259 | (or job files) as parameters:: |
| 260 | |
| 261 | $ fio [options] [jobfile] ... |
| 262 | |
| 263 | and it will start doing what the *jobfile* tells it to do. You can give more |
| 264 | than one job file on the command line, fio will serialize the running of those |
| 265 | files. Internally that is the same as using the :option:`stonewall` parameter |
| 266 | described in the parameter section. |
| 267 | |
| 268 | If the job file contains only one job, you may as well just give the parameters |
| 269 | on the command line. The command line parameters are identical to the job |
| 270 | parameters, with a few extra that control global parameters. For example, for |
| 271 | the job file parameter :option:`iodepth=2 <iodepth>`, the mirror command line |
| 272 | option would be :option:`--iodepth 2 <iodepth>` or :option:`--iodepth=2 |
| 273 | <iodepth>`. You can also use the command line for giving more than one job |
| 274 | entry. For each :option:`--name <name>` option that fio sees, it will start a |
| 275 | new job with that name. Command line entries following a |
| 276 | :option:`--name <name>` entry will apply to that job, until there are no more |
| 277 | entries or a new :option:`--name <name>` entry is seen. This is similar to the |
| 278 | job file options, where each option applies to the current job until a new [] |
| 279 | job entry is seen. |
| 280 | |
| 281 | fio does not need to run as root, except if the files or devices specified in |
| 282 | the job section requires that. Some other options may also be restricted, such |
| 283 | as memory locking, I/O scheduler switching, and decreasing the nice value. |
| 284 | |
| 285 | If *jobfile* is specified as ``-``, the job file will be read from standard |
| 286 | input. |