xfs
[Top] [All Lists]

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

To: Dave Chinner <david@xxxxxxxxxxxxx>
Subject: Re: [PATCH 1/3] xfs: update mount options documentation
From: Ben Myers <bpm@xxxxxxx>
Date: Tue, 9 Jul 2013 16:37:03 -0500
Cc: xfs@xxxxxxxxxxx
Delivered-to: xfs@xxxxxxxxxxx
In-reply-to: <1373403841-16612-2-git-send-email-david@xxxxxxxxxxxxx>
References: <1373403841-16612-1-git-send-email-david@xxxxxxxxxxxxx> <1373403841-16612-2-git-send-email-david@xxxxxxxxxxxxx>
User-agent: Mutt/1.5.20 (2009-06-14)
On Wed, Jul 10, 2013 at 07:03:59AM +1000, 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.
> 
> Signed-off-by: Dave Chinner <dchinner@xxxxxxxxxx>
> Reviewed-by: Mark Tinguely <tinguely@xxxxxxx>
> ---
>  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

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