Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
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 -- Karel Zak k...@redhat.com http://karelzak.blogspot.com -- To unsubscribe from this list: send the line unsubscribe linux-btrfs in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
Document all current btrfs mount options. Signed-off-by: Eric Sandeen sand...@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
Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
On Sat, 23 Mar 2013 12:48:54 -0500 Eric Sandeen sand...@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. -- With respect, Roman signature.asc Description: PGP signature
Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
-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 sand...@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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
On Sat, Mar 23, 2013 at 12:48:54PM -0500, Eric Sandeen wrote: Document all current btrfs mount options. Signed-off-by: Eric Sandeen sand...@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
Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
-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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt
-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 majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
