xfs
[Top] [All Lists]

Re: [PATCH 01/27] xfs: update mount options documentation

To: Dave Chinner <david@xxxxxxxxxxxxx>
Subject: Re: [PATCH 01/27] xfs: update mount options documentation
From: Eric Sandeen <sandeen@xxxxxxxxxxx>
Date: Thu, 13 Jun 2013 08:34:17 -0500
Cc: xfs@xxxxxxxxxxx
Delivered-to: xfs@xxxxxxxxxxx
In-reply-to: <1371032567-21772-2-git-send-email-david@xxxxxxxxxxxxx>
References: <1371032567-21772-1-git-send-email-david@xxxxxxxxxxxxx> <1371032567-21772-2-git-send-email-david@xxxxxxxxxxxxx>
User-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:17.0) Gecko/20130509 Thunderbird/17.0.6
On 6/12/13 5:22 AM, Dave Chinner wrote:
> From: Dave Chinner <dchinner@xxxxxxxxxx>
> 
> Because it's horribly out of date.
> 
> And mark various deprecated options as deprecated and give them a
> removal date.

thanks for doing this.  some nitpicks below.

> Signed-off-by: Dave Chinner <dchinner@xxxxxxxxxx>
> ---
>  Documentation/filesystems/xfs.txt |  282 
> +++++++++++++++++++++++++------------
>  1 file changed, 192 insertions(+), 90 deletions(-)
> 
> diff --git a/Documentation/filesystems/xfs.txt 
> b/Documentation/filesystems/xfs.txt
> index 83577f0..28afbd1 100644
> --- a/Documentation/filesystems/xfs.txt
> +++ b/Documentation/filesystems/xfs.txt
> @@ -25,6 +25,13 @@ When mounting an XFS filesystem, the following options are 
> accepted.
>       Valid values for this option are page size (typically 4KiB)
>       through to 1GiB, inclusive, in power-of-2 increments.
>  
> +     The default behaviour is for dynamic end-of-file
> +     preallocation size, which uses a set of heuristics to
> +     optimise the preallocation size based on the current
> +     allocation patterns within the file and the access patterns
> +     to the file. Specifying a fixed allocsize value turns off
> +     the dynamic behaviour.
> +
>    attr2/noattr2
>       The options enable/disable (default is disabled for backward
>       compatibility on-disk) an "opportunistic" improvement to be
> @@ -36,86 +43,108 @@ When mounting an XFS filesystem, the following options 
> are accepted.
>       CRC enabled filesystems always use the attr2 format, and so
>       will reject the noattr2 mount option if it is set.
>  
> -  barrier
> -     Enables the use of block layer write barriers for writes into
> -     the journal and unwritten extent conversion.  This allows for
> -     drive level write caching to be enabled, for devices that
> -     support write barriers.
> +  barrier/nobarrier
> +     Enables/disables the use of block layer write barriers for
> +     writes into the journal and for data integrity operations.
> +     This allows for drive level write caching to be enabled, for
> +     devices that support write barriers.
>  
> -  discard
> -     Issue command to let the block device reclaim space freed by the
> -     filesystem.  This is useful for SSD devices, thinly provisioned
> -     LUNs and virtual machine images, but may have a performance
> -     impact.
> +     The default behaviour is to enable barriers.
>  
> -  dmapi
> -     Enable the DMAPI (Data Management API) event callouts.
> -     Use with the "mtpt" option.
> +  discard/nodiscard
>  
> -  grpid/bsdgroups and nogrpid/sysvgroups
> -     These options define what group ID a newly created file gets.
> -     When grpid is set, it takes the group ID of the directory in
> -     which it is created; otherwise (the default) it takes the fsgid
> -     of the current process, unless the directory has the setgid bit
> -     set, in which case it takes the gid from the parent directory,
> -     and also gets the setgid bit set if it is a directory itself.
> +     Enable/disable the issuing of commands to let the block
> +     device reclaim space freed by the filesystem.  This is
> +     useful for SSD devices, thinly provisioned LUNs and virtual
> +     machine images, but may have a performance impact.

should we talk about fstrim as an alternative here?

> -  ihashsize=value
> -     In memory inode hashes have been removed, so this option has
> -     no function as of August 2007. Option is deprecated.
> +     The default behaviour is disable discard commands.
> +
> +     Note: It is currently recommended that you use the fstrim
> +     application to discard unused blocks rather than the discard
> +     mount option because the performance impact of this option
> +     is quite severe.

oh right!

> +  grpid/bsdgroups and nogrpid/sysvgroups
> +     These options define what group ID a newly created file
> +     gets.  When grpid is set, it takes the group ID of the
> +     directory in which it is created; otherwise (the default) it
> +     takes the fsgid of the current process, unless the directory
> +     has the setgid bit set, in which case it takes the gid from
> +     the parent directory, and also gets the setgid bit set if it
> +     is a directory itself.
> +
> +  filestreams
> +     Make the data allocator use the filestreams allocation mode
> +     across the entire filesystem rather than just on directories
> +     configured to use it.
>  
>    ikeep/noikeep
> -     When ikeep is specified, XFS does not delete empty inode clusters
> -     and keeps them around on disk. ikeep is the traditional XFS
> -     behaviour. When noikeep is specified, empty inode clusters
> -     are returned to the free space pool. The default is noikeep for
> -     non-DMAPI mounts, while ikeep is the default when DMAPI is in use.
> +     When ikeep is specified, XFS does not delete empty inode
> +     clusters and keeps them around on disk.  When noikeep is
> +     specified, empty inode clusters are returned to the free
> +     space pool.
> +
> +     The default behaviour is delete inode clusters (noikeep).

is to delete inode clusters

>  
>    inode64
> -     Indicates that XFS is allowed to create inodes at any location
> -     in the filesystem, including those which will result in inode
> -     numbers occupying more than 32 bits of significance.  This is
> -     the default allocation option. Applications which do not handle
> -     inode numbers bigger than 32 bits, should use inode32 option.
> +     When inode64 is specified, it indicates that XFS is allowed
> +     to create inodes at any location in the filesystem,
> +     including those which will result in inode numbers occupying
> +     more than 32 bits of significance.  Applications which do
> +     not handle inode numbers bigger than 32 bits should use
> +     inode32 option.

While we're rewriting . . . applications don't use mount options,
not really.  So maybe:

If applications are in use which do not handle inode numbers bigger
than 32 bits, the inode32 option should be specified.

> +     This is the default allocation behaviour, even on 32 bit
> +     machines when neither inode64 or inode32 is specified.
>  
>    inode32
> -     Indicates that XFS is limited to create inodes at locations which
> -     will not result in inode numbers with more than 32 bits of
> -     significance. This is provided for backwards compatibility, since
> -     64 bits inode numbers might cause problems for some applications
> -     that cannot handle large inode numbers.
> +     When inode32 is specified, it indicates that XFS limits
> +     inode creation to locations which will not result in inode
> +     numbers with more than 32 bits of significance. This is
> +     provided for backwards compatibility with older systems and
> +     applications, since 64 bits inode numbers might cause
> +     problems for some applications that cannot handle large
> +     inode numbers.


Any point to talking about what this does to locality etc?

>    largeio/nolargeio
>       If "nolargeio" is specified, the optimal I/O reported in
> -     st_blksize by stat(2) will be as small as possible to allow user
> -     applications to avoid inefficient read/modify/write I/O.
> -     If "largeio" specified, a filesystem that has a "swidth" specified
> -     will return the "swidth" value (in bytes) in st_blksize. If the
> -     filesystem does not have a "swidth" specified but does specify
> -     an "allocsize" then "allocsize" (in bytes) will be returned
> -     instead.
> +     st_blksize by stat(2) will be as small as possible to allow
> +     user applications to avoid inefficient read/modify/write
> +     I/O.  This is typically the page size of the machine, as
> +     this is the granularity of the page cache.
> +
> +     If "largeio" specified, a filesystem that was created with a
> +     "swidth" specified will return the "swidth" value (in bytes)
> +     in st_blksize. If the filesystem does not have a "swidth"
> +     specified but does specify an "allocsize" then "allocsize"
> +     (in bytes) will be returned instead. Otherwise the behaviour
> +     is the same as if "nolargeio" was specified.
> +
>       If neither of these two options are specified, then filesystem
>       will behave as if "nolargeio" was specified.

I have to wonder when anyone would want to use largeio.  This doesn't
tell me, either.  ;)

I wonder if there's any clearer way to show defaults.  Maybe:

     largeio
     nolargeio (*)
        If "nolargeio" is specified, the optimal I/O reported in
        ...



>    logbufs=value
> -     Set the number of in-memory log buffers.  Valid numbers range
> -     from 2-8 inclusive.
> -     The default value is 8 buffers for filesystems with a
> -     blocksize of 64KiB, 4 buffers for filesystems with a blocksize
> -     of 32KiB, 3 buffers for filesystems with a blocksize of 16KiB
> -     and 2 buffers for all other configurations.  Increasing the
> -     number of buffers may increase performance on some workloads
> -     at the cost of the memory used for the additional log buffers
> -     and their associated control structures.
> +     Set the number of in-memory log buffers.  Valid numbers
> +     range from 2-8 inclusive.
> +
> +     The default value is 8 buffers.
> +
> +     If the memory cost of 8 log buffers is too high on small
> +     systems, then it may be reduced at some cost to performance
> +     on metadata intensive workloads.

        The logbsize option below controls the size of each buffer.

>    logbsize=value
> -     Set the size of each in-memory log buffer.
> -     Size may be specified in bytes, or in kilobytes with a "k" suffix.
> -     Valid sizes for version 1 and version 2 logs are 16384 (16k) and
> -     32768 (32k).  Valid sizes for version 2 logs also include
> -     65536 (64k), 131072 (128k) and 262144 (256k).
> -     The default value for machines with more than 32MiB of memory
> -     is 32768, machines with less memory use 16384 by default.
> +     Set the size of each in-memory log buffer.  The size may be
> +     specified in bytes, or in kilobytes with a "k" suffix.
> +     Valid sizes for version 1 and version 2 logs are 16384 (16k)
> +     and 32768 (32k).  Valid sizes for version 2 logs also
> +     include 65536 (64k), 131072 (128k) and 262144 (256k). The
> +     version 2 log size must be an integer multiple of the log
> +     stripe unit configured at mkfs time.

the version 2 log size, or logbsize?

> +     The default value for for version 1 logs is 32768, while the
> +     default value for version 2 logs is MAX(32768, log_sunit).
>  
>    logdev=device and rtdev=device
>       Use an external log (metadata journal) and/or real-time device.
> @@ -124,16 +153,12 @@ When mounting an XFS filesystem, the following options 
> are accepted.
>       optional, and the log section can be separate from the data
>       section or contained within it.
>  
> -  mtpt=mountpoint
> -     Use with the "dmapi" option.  The value specified here will be
> -     included in the DMAPI mount event, and should be the path of
> -     the actual mountpoint that is used.
> -
>    noalign
> -     Data allocations will not be aligned at stripe unit boundaries.
>  
> -  noatime
> -     Access timestamps are not updated when a file is read.
> +     Data allocations will not be aligned at stripe unit
> +     boundaries. This is only relevant to filesystems created
> +     with non-zero data alignment parameters (sunit, swidth) by
> +     mkfs.

why would I use this?

>    norecovery
>       The filesystem will be mounted without running log recovery.
> @@ -144,8 +169,14 @@ When mounting an XFS filesystem, the following options 
> are accepted.
>       the mount will fail.
>  
>    nouuid
> -     Don't check for double mounted file systems using the file system uuid.
> -     This is useful to mount LVM snapshot volumes.
> +     Don't check for double mounted file systems using the file
> +     system uuid.  This is useful to mount LVM snapshot volumes,
> +     and often used in combination with "norecovery" for mounting
> +     read-only snapshots.
> +
> +  noquota
> +     Forcibly turns off all quota accounting and enforcement
> +     within the filesystem.
>  
>    uquota/usrquota/uqnoenforce/quota
>       User disk quota accounting enabled, and limits (optionally)
> @@ -160,24 +191,68 @@ When mounting an XFS filesystem, the following options 
> are accepted.
>       enforced.  Refer to xfs_quota(8) for further details.
>  
>    sunit=value and swidth=value
> -     Used to specify the stripe unit and width for a RAID device or
> -     a stripe volume.  "value" must be specified in 512-byte block
> -     units.
> -     If this option is not specified and the filesystem was made on
> -     a stripe volume or the stripe width or unit were specified for
> -     the RAID device at mkfs time, then the mount system call will
> -     restore the value from the superblock.  For filesystems that
> -     are made directly on RAID devices, these options can be used
> -     to override the information in the superblock if the underlying
> -     disk layout changes after the filesystem has been created.
> -     The "swidth" option is required if the "sunit" option has been
> -     specified, and must be a multiple of the "sunit" value.
> +     Used to specify the stripe unit and width for a RAID device
> +     or a stripe volume.  "value" must be specified in 512-byte
> +     block units. These options are only relevant to filesystems
> +     that were created with non-zero data alignment parameters.

(i.e. su/sw or sunit/swidth was specified at mkfs time).

> +
> +     The sunit and swidth parameters specified must be compatible
> +     with the existing filesystem alignment characteristics. If
> +     the filesystem was not created with data alignment
> +     constraints, then it may be impossible to set a valid sunit
> +     (and hence swidth) value.  In general, that means the only
> +     valid changes to sunit are increasing it by a power-of-2
> +     multiple. Valid swidth values are any integer multiple of a
> +     valid sunit value.

now I'm confused.  It's only relevant to a filesystem w/ geometry
specified, but if it wasn't specified, it may be possible . . . ?

And if nothing was specified (i.e. 0 su/sw) then we can only increase
that 0 by a power of 2?


> +     For filesystems that have existing data alignment values on
> +     disk (i.e. specified by mkfs), any new valid values passed
> +     in as mount options will overwrite the values stored on
> +     disk. Hence this mount option does not need to be specified
> +     for every mount operation in this case.

so I think this all needs to clarify whether it works on filesystems
w/o existing geometry, or not.  And "why you might want this" would
be helpful too.

>    swalloc
>       Data allocations will be rounded up to stripe width boundaries
>       when the current end of file is being extended and the file
>       size is larger than the stripe width size.
>  
> +  wsync
> +     When specified, all filesystem namespace operations are
> +     executed synchronously. This ensures that when the namespace
> +     operation (create, unlink, etc) completes, the change to the
> +     namespace is on stable storage. This is useful in HA setups
> +     where failover must not result in clients seeing
> +     inconsistent namespace presentation during or after a
> +     failover event.
> +
> +
> +Deprecated Mount Options
> +========================
> +
> +  delaylog/nodelaylog
> +     Delayed logging is the only logging method that XFS supports
> +     now, so these mount options are now ignored.
> +
> +     Due for removal in 3.12.
> +
> +  ihashsize=value
> +     In memory inode hashes have been removed, so this option has
> +     no function as of August 2007. Option is deprecated.
> +
> +     Due for removal in 3.12.
> +
> +  irixsgid
> +     This behaviour is now controlled by a sysctl, so the mount
> +     option is ignored.
> +
> +     Due for removal in 3.12.
> +
> +  osyncisdsync
> +  osyncisosync
> +     O_SYNC and O_DSYNC are fully supported, so there is no need
> +     for these options any more.
> +
> +     Due for removal in 3.12.

>  sysctls
>  =======
> @@ -189,15 +264,20 @@ The following sysctls are available for the XFS 
> filesystem:
>       in /proc/fs/xfs/stat.  It then immediately resets to "0".
>  
>    fs.xfs.xfssyncd_centisecs  (Min: 100  Default: 3000  Max: 720000)
> -     The interval at which the xfssyncd thread flushes metadata
> -     out to disk.  This thread will flush log activity out, and
> -     do some processing on unlinked inodes.
> +     The interval at which the filesystem flushes metadata
> +     out to disk and runs internal cache cleanup routines.
>  
> -  fs.xfs.xfsbufd_centisecs   (Min: 50  Default: 100  Max: 3000)
> -     The interval at which xfsbufd scans the dirty metadata buffers list.
> +  fs.xfs.filestream_centisecs        (Min: 1  Default: 3000  Max: 360000)
> +     The interval at which the filesystem ages filestreams cache
> +     references and returns timed-out AGs back to the free stream
> +     pool.

I bet Documentation/filesystem/xfs-filestreams.txt would be handy, but *shrug*

> -  fs.xfs.age_buffer_centisecs        (Min: 100  Default: 1500  Max: 720000)
> -     The age at which xfsbufd flushes dirty metadata buffers to disk.
> +  fs.xfs.speculative_prealloc_lifetime
> +             (Units: seconds   Min: 1  Default: 300  Max: 86400)
> +     The interval at which the background scanning for inodes
> +     with unused speculative preallocation runs at. The scan

The interval at which the background scanning . . . runs.  (no at.)

> +     removes unused preallocation from clean inodes and releases
> +     the unused space back to the free pool.
>  
>    fs.xfs.error_level         (Min: 0  Default: 3  Max: 11)
>       A volume knob for error reporting when internal errors occur.
> @@ -254,9 +334,31 @@ The following sysctls are available for the XFS 
> filesystem:
>       by the xfs_io(8) chattr command on a directory to be
>       inherited by files in that directory.
>  
> +  fs.xfs.inherit_nodefrag    (Min: 0  Default: 1  Max: 1)
> +     Setting this to "1" will cause the "nodefrag" flag set
> +     by the xfs_io(8) chattr command on a directory to be
> +     inherited by files in that directory.
> +
>    fs.xfs.rotorstep           (Min: 1  Default: 1  Max: 256)
>       In "inode32" allocation mode, this option determines how many
>       files the allocator attempts to allocate in the same allocation
>       group before moving to the next allocation group.  The intent
>       is to control the rate at which the allocator moves between
>       allocation groups when allocating extents for new files.
> +
> +Deprecated Sysctls
> +==================
> +
> +  fs.xfs.xfsbufd_centisecs   (Min: 50  Default: 100  Max: 3000)
> +     Dirty metadata is now tracked by the log subsystem and
> +     flushing is driven by log space and idling demands. The
> +     xfsbufd no longer exists, so this syctl does nothing.
> +
> +     Due for removal in 3.14.
> +
> +  fs.xfs.age_buffer_centisecs        (Min: 100  Default: 1500  Max: 720000)
> +     Dirty metadata is now tracked by the log subsystem and
> +     flushing is driven by log space and idling demands. The
> +     xfsbufd no longer exists, so this syctl does nothing.
> +
> +     Due for removal in 3.14.
> 

<Prev in Thread] Current Thread [Next in Thread>