Re: [PATCH 1/3] xfs: update mount options documentation

Ben Myers
2013-07-09T21:37:04Z

On Wed, Jul 10, 2013 at 07:03:59AM +1000, Dave Chinner wrote:
> From: Dave Chinner <dchinner@redhat.com>
>
> Because it's horribly out of date.
>
> And mark various deprecated options as deprecated and give them a
> removal date.
>
> Signed-off-by: Dave Chinner <dchinner@redhat.com>
> Reviewed-by: Mark Tinguely <tinguely@sgi.com>
> ---
> Documentation/filesystems/xfs.txt | 317 +++++++++++++++++++++++++-------------
> 1 file changed, 209 insertions(+), 108 deletions(-)
>
> diff --git a/Documentation/filesystems/xfs.txt b/Documentation/filesystems/xfs.txt
> index 83577f0..12525b1 100644
> --- a/Documentation/filesystems/xfs.txt
> +++ b/Documentation/filesystems/xfs.txt
> @@ -18,6 +18,8 @@ Mount Options
> =============
>
> When mounting an XFS filesystem, the following options are accepted.
> +For boolean mount options, the names with the (*) suffix is the
> +default behaviour.
>
> allocsize=size
> Sets the buffered I/O end-of-file preallocation size when
> @@ -25,97 +27,128 @@ 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.
>
> - attr2/noattr2
> - The options enable/disable (default is disabled for backward
> - compatibility on-disk) an "opportunistic" improvement to be
> - made in the way inline extended attributes are stored on-disk.
> - When the new form is used for the first time (by setting or
> - removing extended attributes) the on-disk superblock feature
> - bit field will be updated to reflect this format being in use.
> + 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 an "opportunistic" improvement to
> + be made in the way inline extended attributes are stored
> + on-disk. When the new form is used for the first time when
> + attr2 is selected (either when setting or removing extended
> + attributes) the on-disk superblock feature bit field will be
> + updated to reflect this format being in use.
> +
> + The default behaviour is determined by the on-disk feature
> + bit indicating that attr2 behaviour is active. If either
> + mount option it set, then that becomes the new default used
> + by the filesystem.
>
> 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.
> -
> - dmapi
> - Enable the DMAPI (Data Management API) event callouts.
> - Use with the "mtpt" option.
> -
> - 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.
> -
> - ihashsize=value
> - In memory inode hashes have been removed, so this option has
> - no function as of August 2007. Option is deprecated.
> -
> - 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.
> -
> - 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.
> + nodiscard (*)
> + 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.
> +
> + 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.
> +
> + grpid/bsdgroups
> + 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 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. When noikeep is
> + specified, empty inode clusters are returned to the free
> + space pool.
>
> 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.
> -
> - largeio/nolargeio
> + inode64 (*)
> + 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.
> +
> + 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.
> +
> + inode32 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. If applications are in use which do
> + not handle inode numbers bigger than 32 bits, the inode32
> + option should be specified.
> +
> +
> + 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.
> - If neither of these two options are specified, then filesystem
> - will behave as if "nolargeio" was specified.
> + 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.
>
> 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 and so is also relevent to
> + this case.
>
> 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
> + logbsize must be an integer multiple of the log
> + stripe unit configured at mkfs time.
> +
> + 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 +157,11 @@ 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.
>
> norecovery
> The filesystem will be mounted without running log recovery.
> @@ -144,8 +172,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 +194,64 @@ 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.
> +
> + The sunit and swidth parameters specified must be compatible
> + with the existing filesystem alignment characteristics. 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.
> +
> + Typically the only time these mount options are necessary if
> + after an underlying RAID device has had it's geometry
> + modified, such as adding a new disk to a RAID5 lun and
> + reshaping it.
>
> 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.

I finally read through Documentation/ABI/README, and I agree this all seems
fairly reasonable with respect to that doc.

I do agree that it would be good to add these into the
Documentation/ABI/obsolete directory. The only other concern that I have is
that the doc is saying that they want two years notice. 3.12 might be a little
short for that timeframe. Anyway we can cross that bridge when we come to it.

Applied.

-Ben