X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=a0fadcbbd52359c24d65f3641d09c4fa5697b069;hp=804d93e4c578bfdb7d47058d177cce34420bb380;hb=7b865a2f23d22f82ffcc25756b1eeea55e57f1e3;hpb=3740cfc89440001e393dee1a6abae41ec89bec27 diff --git a/HOWTO b/HOWTO index 804d93e4..a0fadcbb 100644 --- a/HOWTO +++ b/HOWTO @@ -283,7 +283,8 @@ Command line options .. option:: --aux-path=path - Use this `path` for fio state generated files. + Use the directory specified by `path` for generated state files instead + of the current working directory. Any parameters following the options will be assumed to be job files, unless they match a job file parameter. Multiple job files can be listed and each job @@ -748,12 +749,15 @@ Target file/device assigned equally distributed to job clones created by :option:`numjobs` as long as they are using generated filenames. If specific `filename(s)` are set fio will use the first listed directory, and thereby matching the - `filename` semantic which generates a file each clone if not specified, but - let all clones use the same if set. + `filename` semantic (which generates a file for each clone if not + specified, but lets all clones use the same file if set). See the :option:`filename` option for information on how to escape "``:``" and "``\``" characters within the directory path itself. + Note: To control the directory fio will use for internal state files + use :option:`--aux-path`. + .. option:: filename=str Fio normally makes up a `filename` based on the job name, thread number, and @@ -948,18 +952,50 @@ Target file/device Unlink job files after each iteration or loop. Default: false. -.. option:: zonesize=int +.. option:: zonemode=str - Divide a file into zones of the specified size. See :option:`zoneskip`. + Accepted values are: + + **none** + The :option:`zonerange`, :option:`zonesize` and + :option:`zoneskip` parameters are ignored. + **strided** + I/O happens in a single zone until + :option:`zonesize` bytes have been transferred. + After that number of bytes has been + transferred processing of the next zone + starts. + **zbd** + Zoned block device mode. I/O happens + sequentially in each zone, even if random I/O + has been selected. Random I/O happens across + all zones instead of being restricted to a + single zone. The :option:`zoneskip` parameter + is ignored. :option:`zonerange` and + :option:`zonesize` must be identical. .. option:: zonerange=int - Give size of an I/O zone. See :option:`zoneskip`. + Size of a single zone. See also :option:`zonesize` and + :option:`zoneskip`. + +.. option:: zonesize=int + + For :option:`zonemode` =strided, this is the number of bytes to + transfer before skipping :option:`zoneskip` bytes. If this parameter + is smaller than :option:`zonerange` then only a fraction of each zone + with :option:`zonerange` bytes will be accessed. If this parameter is + larger than :option:`zonerange` then each zone will be accessed + multiple times before skipping to the next zone. + + For :option:`zonemode` =zbd, this is the size of a single zone. The + :option:`zonerange` parameter is ignored in this mode. .. option:: zoneskip=int - Skip the specified number of bytes when :option:`zonesize` data has been - read. The two zone options can be used to only do I/O on zones of a file. + For :option:`zonemode` =strided, the number of bytes to skip after + :option:`zonesize` bytes of data have been transferred. This parameter + must be zero for :option:`zonemode` =zbd. I/O type @@ -1825,6 +1861,15 @@ I/O engine (RBD) via librbd without the need to use the kernel rbd driver. This ioengine defines engine specific options. + **http** + I/O engine supporting GET/PUT requests over HTTP(S) with libcurl to + a WebDAV or S3 endpoint. This ioengine defines engine specific options. + + This engine only supports direct IO of iodepth=1; you need to scale this + via numjobs. blocksize defines the size of the objects to be created. + + TRIM is translated to object deletion. + **gfapi** Using GlusterFS libgfapi sync interface to direct access to GlusterFS volumes without having to go through FUSE. This ioengine @@ -1882,6 +1927,22 @@ I/O engine mounted with DAX on a persistent memory device through the PMDK libpmem library. + **ime_psync** + Synchronous read and write using DDN's Infinite Memory Engine (IME). + This engine is very basic and issues calls to IME whenever an IO is + queued. + + **ime_psyncv** + Synchronous read and write using DDN's Infinite Memory Engine (IME). + This engine uses iovecs and will try to stack as much IOs as possible + (if the IOs are "contiguous" and the IO depth is not exceeded) + before issuing a call to IME. + + **ime_aio** + Asynchronous read and write using DDN's Infinite Memory Engine (IME). + This engine will try to stack as much IOs as possible by creating + requests for IME. FIO will then decide when to commit these requests. + I/O engine specific parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -2105,6 +2166,54 @@ with the caveat that when used on the command line, they must come after the transferred to the device. The writefua option is ignored with this selection. +.. option:: http_host=str : [http] + + Hostname to connect to. For S3, this could be the bucket hostname. + Default is **localhost** + +.. option:: http_user=str : [http] + + Username for HTTP authentication. + +.. option:: http_pass=str : [http] + + Password for HTTP authentication. + +.. option:: https=str : [http] + + Enable HTTPS instead of http. *on* enables HTTPS; *insecure* + will enable HTTPS, but disable SSL peer verification (use with + caution!). Default is **off** + +.. option:: http_mode=str : [http] + + Which HTTP access mode to use: *webdav*, *swift*, or *s3*. + Default is **webdav** + +.. option:: http_s3_region=str : [http] + + The S3 region/zone string. + Default is **us-east-1** + +.. option:: http_s3_key=str : [http] + + The S3 secret key. + +.. option:: http_s3_keyid=str : [http] + + The S3 key/access id. + +.. option:: http_swift_auth_token=str : [http] + + The Swift auth token. See the example configuration file on how + to retrieve this. + +.. option:: http_verbose=int : [http] + + Enable verbose requests from libcurl. Useful for debugging. 1 + turns on verbose logging from libcurl, 2 additionally enables + HTTP IO tracing. Default is **0** + I/O depth ~~~~~~~~~ @@ -2326,6 +2435,16 @@ I/O replay :manpage:`blktrace(8)` for how to capture such logging data. For blktrace replay, the file needs to be turned into a blkparse binary data file first (``blkparse -o /dev/null -d file_for_fio.bin``). + You can specify a number of files by separating the names with a ':' + character. See the :option:`filename` option for information on how to + escape ':' and '\' characters within the file names. These files will + be sequentially assigned to job clones created by :option:`numjobs`. + +.. option:: read_iolog_chunked=bool + + Determines how iolog is read. If false(default) entire :option:`read_iolog` + will be read at once. If selected true, input from iolog will be read + gradually. Useful when iolog is very large, or it is generated. .. option:: replay_no_stall=bool @@ -2909,9 +3028,11 @@ Measurements and reporting .. option:: write_iops_log=str Same as :option:`write_bw_log`, but writes an IOPS file (e.g. - :file:`name_iops.x.log`) instead. See :option:`write_bw_log` for - details about the filename format and `Log File Formats`_ for how data - is structured within the file. + :file:`name_iops.x.log`) instead. Because fio defaults to individual + I/O logging, the value entry in the IOPS log will be 1 unless windowed + logging (see :option:`log_avg_msec`) has been enabled. See + :option:`write_bw_log` for details about the filename format and `Log + File Formats`_ for how data is structured within the file. .. option:: log_avg_msec=int @@ -3796,17 +3917,16 @@ on the type of log, it will be one of the following: **2** I/O is a TRIM -The entry's *block size* is always in bytes. The *offset* is the offset, in bytes, -from the start of the file, for that particular I/O. The logging of the offset can be +The entry's *block size* is always in bytes. The *offset* is the position in bytes +from the start of the file for that particular I/O. The logging of the offset can be toggled with :option:`log_offset`. -Fio defaults to logging every individual I/O. When IOPS are logged for individual -I/Os the *value* entry will always be 1. If windowed logging is enabled through -:option:`log_avg_msec`, fio logs the average values over the specified period of time. -If windowed logging is enabled and :option:`log_max_value` is set, then fio logs -maximum values in that window instead of averages. Since *data direction*, *block -size* and *offset* are per-I/O values, if windowed logging is enabled they -aren't applicable and will be 0. +Fio defaults to logging every individual I/O but when windowed logging is set +through :option:`log_avg_msec`, either the average (by default) or the maximum +(:option:`log_max_value` is set) *value* seen over the specified period of time +is recorded. Each *data direction* seen within the window period will aggregate +its values in a separate row. Further, when using windowed logging the *block +size* and *offset* entries will always contain 0. Client/Server -------------