Merge branch 'ime-support' of https://github.com/DDNStorage/fio-public into ddn-ime

[fio.git] / HOWTO

diff --git a/HOWTO b/HOWTO
index c3dd964a17b50af152f152fb808d1bffdc950c57..ff7aa096495a969aea9eddb0c8159f8054b6b0d1 100644 (file)
--- a/HOWTO
+++ b/HOWTO
@@ -283,7 +283,8 @@ Command line options
 
 .. option:: --aux-path=path
 
 
 .. 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
 
 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
        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.
 
 
        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
 .. option:: filename=str
 
        Fio normally makes up a `filename` based on the job name, thread number, and


@@ -948,18 +952,24 @@ Target file/device
 
        Unlink job files after each iteration or loop.  Default: false.
 
 
        Unlink job files after each iteration or loop.  Default: false.
 

-.. option:: zonesize=int
+.. option:: zonerange=int

 
 

-       Divide a file into zones of the specified size. See :option:`zoneskip`.
+       Size of a single zone in which I/O occurs. See also :option:`zonesize`
+       and :option:`zoneskip`.

 
 

-.. option:: zonerange=int
+.. option:: zonesize=int

 
 

-       Give size of an I/O zone.  See :option:`zoneskip`.
+       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

 
 .. option:: zoneskip=int
 
 
 .. 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.
+       Skip the specified number of bytes when :option:`zonesize` data have
+       been transferred. The three zone options can be used to do strided I/O
+       on a file.

 
 
 I/O type
 
 
 I/O type


@@ -1825,6 +1835,15 @@ I/O engine
                        (RBD) via librbd without the need to use the kernel rbd driver. This
                        ioengine defines engine specific options.
 
                        (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
                **gfapi**
                        Using GlusterFS libgfapi sync interface to direct access to
                        GlusterFS volumes without having to go through FUSE.  This ioengine


@@ -2121,6 +2140,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.
 
                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
 ~~~~~~~~~
 
 I/O depth
 ~~~~~~~~~
 


@@ -2931,9 +2998,11 @@ Measurements and reporting
 .. option:: write_iops_log=str
 
        Same as :option:`write_bw_log`, but writes an IOPS file (e.g.
 .. 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
 
 
 .. option:: log_avg_msec=int
 


@@ -3818,17 +3887,16 @@ on the type of log, it will be one of the following:
        **2**
                I/O is a TRIM
 
        **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`.
 
 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
 -------------
 
 Client/Server
 -------------