| Message ID | 514DEB06.7000606@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Sat, 23 Mar 2013 12:48:54 -0500 Eric Sandeen <sandeen@redhat.com> wrote: > diff --git a/Documentation/filesystems/btrfs.txt b/Documentation/filesystems/btrfs.txt > index 7671352..02a19c8 100644 > --- a/Documentation/filesystems/btrfs.txt > +++ b/Documentation/filesystems/btrfs.txt Is anyone really going to look for them there? People expect mount options to be in "man mount".
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 3/23/13 1:33 PM, Roman Mamedov wrote: > On Sat, 23 Mar 2013 12:48:54 -0500 > Eric Sandeen <sandeen@redhat.com> wrote: > >> diff --git a/Documentation/filesystems/btrfs.txt b/Documentation/filesystems/btrfs.txt >> index 7671352..02a19c8 100644 >> --- a/Documentation/filesystems/btrfs.txt >> +++ b/Documentation/filesystems/btrfs.txt > > Is anyone really going to look for them there? > > People expect mount options to be in "man mount". It's traditional to document these options in the kernel docs: # grep -il "mount options" Documentation/filesystems/*.txt Documentation/filesystems/adfs.txt Documentation/filesystems/affs.txt Documentation/filesystems/autofs4-mount-control.txt Documentation/filesystems/befs.txt Documentation/filesystems/ceph.txt Documentation/filesystems/devpts.txt Documentation/filesystems/dlmfs.txt ... <big snip> ... Documentation/filesystems/udf.txt Documentation/filesystems/vfat.txt Documentation/filesystems/vfs.txt Documentation/filesystems/xfs.txt The mount manpage is maintained in the util-linux pkg, but it's not kernel-version specific, and the util-linux maintainer does not have specific knowledge of all filesytem options. I think kernel docs are the right place for the developers to first document these things - it's easily updated as the code change,s and is under the maintainer's direct control. From there the info can be periodically synced to the mount manpage as needed. Thanks, - -Eric -----BEGIN PGP SIGNATURE----- Version: GnuPG/MacGPG2 v2.0.17 (Darwin) Comment: GPGTools - http://gpgtools.org Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQIcBAEBAgAGBQJRTfhQAAoJECCuFpLhPd7gyk8P/iifHpQ8250Gisg9Oza64mC6 YzluQA3XIYJr5xOnTu2ZWA/9znxlg0NWKWE2v7okDrL53nrAZNntWQESQ/PuoJsM G2V+rkjRm3ojPJ3VgycaaPrlEOXW9AWsZYrYwnD3ZNYJ5e5MOxGx5LcYu5/OGvuW lOi7jD9Q3OBFmu5vhRbXnZLgqBYbtMTUlESMZvUhrA4uxKnpPOLHrBwkZ1LzX26X DIuJKqRlkyhqoJotBt+cRo8PCoR1yeremDXaT32MwdeFSEkRIXVIp78BruPATrdi jt116adux7kP5NSa2odOQsSAmnESpXZvmDOaYUzNhUrM621c8LsNbkgC5twyaegd 92+vNkwFu73BJ2sDtyfkEXc4FV9PLhf2KNBJDaIJkneX9BiuQ1WC5u1UUrrQD3lM j4j9PA2R35CTLfSTgu9bQ6Asy9YLgANtTZvKoEXrC8DGAHbaMK1d42NBg2b9mhxo AEacnQNw2dK+1O2Y5BrSBs7cKWacazd/UnGlFDze42dtXZC+J70LeRs26YeJnf6j xl6YSVY3kx62ttChMTYYzIKRh8RRQTrzVgrcflbedLhvZVchRSBIpRTUfQEXtiW+ yY8nUa7w6TdnPYa7dJ4rluhK7HdQ75cb81WOJKL4smU3HmX3uxIIa6kI5KtlWqYw bYzRwrnSpQPLEdnOepI+ =YHWK -----END PGP SIGNATURE----- -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Sat, Mar 23, 2013 at 12:48:54PM -0500, Eric Sandeen wrote: > Document all current btrfs mount options. > > Signed-off-by: Eric Sandeen <sandeen@redhat.com> > --- > > please, Please, PLEASE review this and suggest improvements. > I'm no btrfs wizard but I've done my best to get this all right > based on commit logs, code reading, and wiki reading. In cases where > any of those 3 disagreed, I've done my best to document reality, but I'm > sure it could use corrections, clarifications, etc. > > In particular, some of these mount options could really use more > description of why a user might want them, rather than simply stating > what they do. > > "notreelog" is particularly egregious, as I have nothing but self-referential > documentation. > > So this can use some iteration, I'm sure, but hopefully it's a decent > start. > > Thanks, > -Eric > > diff --git a/Documentation/filesystems/btrfs.txt b/Documentation/filesystems/btrfs.txt > index 7671352..02a19c8 100644 > --- a/Documentation/filesystems/btrfs.txt > +++ b/Documentation/filesystems/btrfs.txt > @@ -1,6 +1,6 @@ > > - BTRFS > - ===== > +BTRFS > +===== > > Btrfs is a new copy on write filesystem for Linux aimed at > implementing advanced features while focusing on fault tolerance, > @@ -34,9 +34,173 @@ The main Btrfs features include: > * Online filesystem defragmentation > > > - > - MAILING LIST > - ============ > +Mount Options > +============= > + > +When mounting a btrfs filesystem, the following option are accepted. > +Unless otherwise specified, all options default to off. > + > + alloc_start=<bytes> > + Debugging option to force all block allocations above a threshold. > + The value is specified in bytes, optionally with a K, M, or G suffix, > + case insensitive. Default is 1MB. > + > + autodefrag > + Detect small random writes into files and queue them up for the > + defrag process. Works best for small files; Not well suited for > + large database workloads. > + > + check_int > + check_int_data > + check_int_print_mask=<value> > + These debugging options control the behavior of the integrity checking > + module (the BTRFS_FS_CHECK_INTEGRITY config option required). > + > + check_int enables the integrity checker module, which examines all > + block write requests to ensure on-disk consistency, at a large > + memory and CPU cost. > + > + check_int_data includes extent data in the integrity checks, and > + implies the check_int option. > + > + check_int_print_mask takes a bitmask of BTRFSIC_PRINT_MASK_* values > + as defined in fs/btrfs/check-integrity.c, to control the integrity > + checker module behavior. > + > + See comments at the top of fs/btrfs/check-integrity.c for more info. > + > + compress > + compress=<type> > + compress-force > + compress-force=<type> > + Control BTRFS file data compression. Type may be specified as "zlib" > + "lzo" or "no" (for no compression, used for remounting). If no type > + is specified, zlib is used. If compress-force is specified, > + all files will be compressed, whether or not they compress well. > + If compression is enabled, nodatacow and nodatasum are disabled. > + > + degraded > + Allow mounts to continue with missing devices. A read-write mount may > + fail with too many devices missing, for example if a stripe member > + is completely missing. > + > + device=<devicepath> > + Specify a device during mount so that ioctls on the control device > + can be avoided. Especialy useful when trying to mount a multi-device > + setup as root. May be specified multiple times for multiple devices. > + > + 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. > + > + enospc_debug > + Debugging option to be more verbose in some ENOSPC conditions. > + > + fatal_errors=<action> > + Action to take when encountering a fatal error: > + "bug" - BUG() on a fatal error. This is the default. > + "panic" - panic() on a fatal error. > + > + flushoncommit > + The 'flushoncommit' mount option forces any data dirtied by a write in a > + prior transaction to commit as part of the current commit. This makes > + the committed state a fully consistent view of the file system from the > + application's perspective (i.e., it includes all completed file system > + operations). This was previously the behavior only when a snapshot is > + created. > + > + inode_cache > + Enable free inode number caching. Defaults to off due to an overflow > + problem when the free space crcs don't fit inside a single page. > + > + max_inline=<bytes> > + Specify the maximum amount of space, in bytes, that can be inlined in > + a metadata B-tree leaf. The value is specified in bytes, optionally > + with a K, M, or G suffix, case insensitive. In practice, this value > + is limited by the root sector size, with some space unavailable due > + to leaf headers. For a 4k sectorsize, max inline data is ~3900 bytes. > + > + metadata_ratio=<value> > + Specify that 1 metadata chunk should be allocated after every <value> > + data chunks. Off by default. > + > + noacl > + Disable support for Posix Access Control Lists (ACLs). See the > + acl(5) manual page for more information about ACLs. > + > + nobarrier > + Disables the use of block layer write barriers. Write barriers ensure > + that certain IOs make it through the device cache and are on persistent > + storage. If used on a device with a volatile (non-battery-backed) > + write-back cache, this option will lead to filesystem corruption on a > + system crash or power loss. > + > + nodatacow > + Disable data copy-on-write for newly created files. Implies nodatasum, > + and disables all compression. > + > + nodatasum > + Disable data checksumming for newly created files. > + > + notreelog > + Disable the tree logging used for fsync and O_SYNC writes. > + > + recovery > + Enable autorecovery attempts if a bad tree root is found at mount time. > + Currently this scans a list of several previous tree roots and tries to > + use the first readable. > + > + skip_balance > + Skip automatic restart of previous balance operation after mount. May resume interrupted > + be restarted with "btrfs device balance" May be resumed with "btrfs balance resume" or cancelled with "btrfs balance cancel". skip_balance simply keeps balance in paused state. Feel free to word this appropriately ;) Thanks, Ilya -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 23/03/13 10:48, Eric Sandeen wrote: > Btrfs is a new copy on write filesystem for Linux aimed at How much longer does "new" get to be there as the filesystem has been going for well over half a decade. > + autodefrag + Detect small random writes into files and queue them up > for the + defrag process. Works best for small files; Not well suited > for + large database workloads. What is "large"? One man's large database is another's trivial database! Same applies to "small". Virtual machines are also in the category of large files with small random writes. Quantification would help a lot. Suggestions are "more than 10 random writes an hour to files larger than a gigabyte". Roger -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (GNU/Linux) iEYEARECAAYFAlFOKx4ACgkQmOOfHg372QROFgCfRaaK6mlx3dn6E22Dy3c5PC2T itUAnR0WxlZ8bFtVnlD+hdJrsnc6s9gU =dkJp -----END PGP SIGNATURE----- -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On 3/23/13 5:22 PM, Roger Binns wrote: > On 23/03/13 10:48, Eric Sandeen wrote: >> Btrfs is a new copy on write filesystem for Linux aimed at > > How much longer does "new" get to be there as the filesystem has been > going for well over half a decade. ;) well, I didn't write that. Could remove it on the next round I suppose. >> + autodefrag + Detect small random writes into files and queue them up >> for the + defrag process. Works best for small files; Not well suited >> for + large database workloads. > > What is "large"? One man's large database is another's trivial database! > Same applies to "small". Virtual machines are also in the category of > large files with small random writes. > > Quantification would help a lot. Suggestions are "more than 10 random > writes an hour to files larger than a gigabyte". Fair enough. I was going by the original commitlog for that option: > Btrfs: add mount -o auto_defrag > > This will detect small random writes into files and > queue the up for an auto defrag process. It isn't well suited to > database workloads yet, but works for smaller files such as rpm, sqlite > or bdb databases. I imagine it depends on the details of the workload & storage as well. Quantifying it may be tough; it may be better to just add more description of what happens when it autodefrags, with some indication of how file size affects the process, and leave it up to the admin to determine whether it's appropriate for a given environment. Before I can do that I'll have to understand better how it works ;) Thanks, -Eric > Roger > > -- > To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in > the body of a message to majordomo@vger.kernel.org > More majordomo info at http://vger.kernel.org/majordomo-info.html > -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
On 23/03/13 15:40, Eric Sandeen wrote:
> I imagine it depends on the details of the workload & storage as well.
If the people who write btrfs can't come up with some measures to deem
appropriateness, then how can the administrators who have even less
information :-)
I suspect file size has nothing to do with it, and it is entirely about
the volume of random writes. (But as a correlator smaller files are
unlikely to get many random writes because they contain less useful
information than larger files.)
Roger
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
iEYEARECAAYFAlFOUr0ACgkQmOOfHg372QSIsgCg3D1k0dL/2bMQpzHRDdlMkUo2
TT8AoI11eLAdAv6iQPweHaeVUiJNSRf6
=OVVq
-----END PGP SIGNATURE-----
--
To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
On Sat, Mar 23, 2013 at 04:22:22PM -0600, Roger Binns wrote: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA1 > > On 23/03/13 10:48, Eric Sandeen wrote: > > Btrfs is a new copy on write filesystem for Linux aimed at > > How much longer does "new" get to be there as the filesystem has been > going for well over half a decade. > > > + autodefrag + Detect small random writes into files and queue them up > > for the + defrag process. Works best for small files; Not well suited > > for + large database workloads. > > What is "large"? One man's large database is another's trivial database! > Same applies to "small". Virtual machines are also in the category of > large files with small random writes. > Any write below i_size that is less than 64k. Josef -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Sat, Mar 23, 2013 at 06:11:26PM -0700, Roger Binns wrote: > On 23/03/13 15:40, Eric Sandeen wrote: > > I imagine it depends on the details of the workload & storage as well. > > If the people who write btrfs can't come up with some measures to deem > appropriateness, then how can the administrators who have even less > information :-) > > I suspect file size has nothing to do with it, and it is entirely about > the volume of random writes. (But as a correlator smaller files are > unlikely to get many random writes because they contain less useful > information than larger files.) I'd say not the volume but the write pattern. A single 4k write may read and rewrite the surrounding 64k when autodefrag is on. So, several rewrites close to each other may actually benefit from autodefrag, while the same number of a completely random 4k rewrites may end up rewriting 16x more data. (http://www.mail-archive.com/linux-btrfs@vger.kernel.org/msg18926.html) david -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
On Sat, Mar 23, 2013 at 01:45:36PM -0500, Eric Sandeen wrote: > The mount manpage is maintained in the util-linux pkg, > but it's not kernel-version specific, and the util-linux > maintainer does not have specific knowledge of all filesytem > options. Absolutely true. The util-linux maintainer is not happy that we don't have filesystem specific man pages for many filesystems. The goal is to have in mount.8 only links to another man pages, for example see smart NFS guys: Mount options for nfs and nfs4: See the options section of the nfs(5) man page (nfs-utils package must be installed). > I think kernel docs are the right place for the developers > to first document these things Definitely. Karel
diff --git a/Documentation/filesystems/btrfs.txt b/Documentation/filesystems/btrfs.txt index 7671352..02a19c8 100644 --- a/Documentation/filesystems/btrfs.txt +++ b/Documentation/filesystems/btrfs.txt @@ -1,6 +1,6 @@ - BTRFS - ===== +BTRFS +===== Btrfs is a new copy on write filesystem for Linux aimed at implementing advanced features while focusing on fault tolerance, @@ -34,9 +34,173 @@ The main Btrfs features include: * Online filesystem defragmentation - - MAILING LIST - ============ +Mount Options +============= + +When mounting a btrfs filesystem, the following option are accepted. +Unless otherwise specified, all options default to off. + + alloc_start=<bytes> + Debugging option to force all block allocations above a threshold. + The value is specified in bytes, optionally with a K, M, or G suffix, + case insensitive. Default is 1MB. + + autodefrag + Detect small random writes into files and queue them up for the + defrag process. Works best for small files; Not well suited for + large database workloads. + + check_int + check_int_data + check_int_print_mask=<value> + These debugging options control the behavior of the integrity checking + module (the BTRFS_FS_CHECK_INTEGRITY config option required). + + check_int enables the integrity checker module, which examines all + block write requests to ensure on-disk consistency, at a large + memory and CPU cost. + + check_int_data includes extent data in the integrity checks, and + implies the check_int option. + + check_int_print_mask takes a bitmask of BTRFSIC_PRINT_MASK_* values + as defined in fs/btrfs/check-integrity.c, to control the integrity + checker module behavior. + + See comments at the top of fs/btrfs/check-integrity.c for more info. + + compress + compress=<type> + compress-force + compress-force=<type> + Control BTRFS file data compression. Type may be specified as "zlib" + "lzo" or "no" (for no compression, used for remounting). If no type + is specified, zlib is used. If compress-force is specified, + all files will be compressed, whether or not they compress well. + If compression is enabled, nodatacow and nodatasum are disabled. + + degraded + Allow mounts to continue with missing devices. A read-write mount may + fail with too many devices missing, for example if a stripe member + is completely missing. + + device=<devicepath> + Specify a device during mount so that ioctls on the control device + can be avoided. Especialy useful when trying to mount a multi-device + setup as root. May be specified multiple times for multiple devices. + + 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. + + enospc_debug + Debugging option to be more verbose in some ENOSPC conditions. + + fatal_errors=<action> + Action to take when encountering a fatal error: + "bug" - BUG() on a fatal error. This is the default. + "panic" - panic() on a fatal error. + + flushoncommit + The 'flushoncommit' mount option forces any data dirtied by a write in a + prior transaction to commit as part of the current commit. This makes + the committed state a fully consistent view of the file system from the + application's perspective (i.e., it includes all completed file system + operations). This was previously the behavior only when a snapshot is + created. + + inode_cache + Enable free inode number caching. Defaults to off due to an overflow + problem when the free space crcs don't fit inside a single page. + + max_inline=<bytes> + Specify the maximum amount of space, in bytes, that can be inlined in + a metadata B-tree leaf. The value is specified in bytes, optionally + with a K, M, or G suffix, case insensitive. In practice, this value + is limited by the root sector size, with some space unavailable due + to leaf headers. For a 4k sectorsize, max inline data is ~3900 bytes. + + metadata_ratio=<value> + Specify that 1 metadata chunk should be allocated after every <value> + data chunks. Off by default. + + noacl + Disable support for Posix Access Control Lists (ACLs). See the + acl(5) manual page for more information about ACLs. + + nobarrier + Disables the use of block layer write barriers. Write barriers ensure + that certain IOs make it through the device cache and are on persistent + storage. If used on a device with a volatile (non-battery-backed) + write-back cache, this option will lead to filesystem corruption on a + system crash or power loss. + + nodatacow + Disable data copy-on-write for newly created files. Implies nodatasum, + and disables all compression. + + nodatasum + Disable data checksumming for newly created files. + + notreelog + Disable the tree logging used for fsync and O_SYNC writes. + + recovery + Enable autorecovery attempts if a bad tree root is found at mount time. + Currently this scans a list of several previous tree roots and tries to + use the first readable. + + skip_balance + Skip automatic restart of previous balance operation after mount. May + be restarted with "btrfs device balance" + + space_cache (*) + Enable the on-disk freespace cache. + nospace_cache + Disable freespace cache loading without clearing the cache. + clear_cache + Force clearing and rebuilding of the disk space cache if something + has gone wrong. + + ssd + nossd + ssd_spread + Options to control ssd allocation schemes. By default, BTRFS will + enable or disable ssd allocation heuristics depending on whether a + rotational or nonrotational disk is in use. The ssd and nossd options + can override this autodetection. + + The ssd_spread mount option attempts to allocate into big chunks + of unused space, and may perform better on low-end ssds. ssd_spread + implies ssd, enabling all other ssd heuristics as well. + + subvol=<path> + Mount subvolume at <path> rather than the root subvolume. <path> is + relative to the top level subvolume. + + subvolid=<ID> + Mount subvolume specified by an ID number rather than the root subvolume. + This allows mounting of subvolumes which are not in the root of the mounted + filesystem. + You can use "btrfs subvolume list" to see subvolume ID numbers. + + subvolrootid=<objectid> (deprecated) + Mount subvolume specified by <objectid> rather than the root subvolume. + This allows mounting of subvolumes which are not in the root of the mounted + filesystem. + You can use "btrfs subvolume show " to see the object ID for a subvolume. + + thread_pool=<number> + The number of worker threads to allocate. The default number is equal + to the number of CPUs + 2, or 8, whichever is smaller. + + user_subvol_rm_allowed + Allow subvolumes to be deleted by a non-root user. Use with caution. + +MAILING LIST +============ There is a Btrfs mailing list hosted on vger.kernel.org. You can find details on how to subscribe here: @@ -49,8 +213,8 @@ http://dir.gmane.org/gmane.comp.file-systems.btrfs - IRC - === +IRC +=== Discussion of Btrfs also occurs on the #btrfs channel of the Freenode IRC network.
Document all current btrfs mount options. Signed-off-by: Eric Sandeen <sandeen@redhat.com> --- please, Please, PLEASE review this and suggest improvements. I'm no btrfs wizard but I've done my best to get this all right based on commit logs, code reading, and wiki reading. In cases where any of those 3 disagreed, I've done my best to document reality, but I'm sure it could use corrections, clarifications, etc. In particular, some of these mount options could really use more description of why a user might want them, rather than simply stating what they do. "notreelog" is particularly egregious, as I have nothing but self-referential documentation. So this can use some iteration, I'm sure, but hopefully it's a decent start. Thanks, -Eric -- To unsubscribe from this list: send the line "unsubscribe linux-btrfs" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html