Btrfs devel - Mar 2013 - [PATCH] btrfs: document mount options in Documentation/fs/btrfs.txt

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
+	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.

--
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, 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".

-- 
With respect,
Roman

-----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

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com
--
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

Document all current btrfs mount options.

Signed-off-by: Eric Sandeen <sandeen@redhat.com>
---

V2:
* reflect that btrfs is no longer "new" ;)
* make it clear that alloc_start is for each device
* highlight potential perf impacts of -o discard
* reword skip_balance docs to refer to "resume"


diff --git a/Documentation/filesystems/btrfs.txt
b/Documentation/filesystems/btrfs.txt
index 7671352..b349d57 100644
--- a/Documentation/filesystems/btrfs.txt
+++ b/Documentation/filesystems/btrfs.txt
@@ -1,8 +1,8 @@
 
-	BTRFS
-	====+BTRFS
+==== 
-Btrfs is a new copy on write filesystem for Linux aimed at
+Btrfs is a copy on write filesystem for Linux aimed at
 implementing advanced features while focusing on fault tolerance,
 repair and easy administration. Initially developed by Oracle, Btrfs
 is licensed under the GPL and open for contribution from anyone.
@@ -34,9 +34,175 @@ The main Btrfs features include:
     * Online filesystem defragmentation
 
 
+Mount Options
+============ 
-	MAILING LIST
-	===========+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 certain
+	byte threshold on each block device.  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 frequent 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 significant
+	performance impact.  (The fstrim command is also available to
+	initiate batch trims from userspace).
+
+  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 resume of interrupted balance operation after mount.
+	May be resumed with "btrfs balance resume."
+
+  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 +215,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.


--
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

Hi,

a few comments that reflect current implementation

On Tue, Mar 26, 2013 at 02:36:12PM -0500, Eric Sandeen
wrote:
> +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 certain
> +	byte threshold on each block device.  The value is specified in
> +	bytes, optionally with a K, M, or G suffix, case insensitive.
> +	Default is 1MB.
yes it is 1MB by default, and also a hardcoded minimum.
> +  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
the ''root sector size'' sounds a bit confusing, the commonly
used term is
''sectorsize''
> +	to leaf headers.  For a 4k sectorsize, max inline data is ~3900 bytes.
> +
> +  notreelog
> +	Disable the tree logging used for fsync and O_SYNC writes.
> +
> + skip_balance
> +	Skip automatic resume of interrupted balance operation after mount.
> +	May be resumed with "btrfs balance resume."
A dot inside a quotation looks confusing to non-us people, I hope nobody
will try to copypaste it :)
> +  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.
This sentence refers to the previous behaviour when subvol did not
accept full path. I suggest to drop it.
> +	You can use "btrfs subvolume list" to see subvolume ID numbers.
Please add something in the sense of "The toplevel subvolume has ID
0".
> +  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.
Not true for a long time, since subvol=/full/path time it''s a no-op.
The
patch to print a warning when the option is used has been sent not so long
ago though.
> +	You can use "btrfs subvolume show " to see the object ID for a
subvolume.
> +	
It seems to me that you probably did not count
https://btrfs.wiki.kernel.org/index.php/Mount_options into the
documentation sources. We''ve tried to keep this page up-to-date, but it
does not cover the same things you did in this patch. Ideally merging
information from both is desirable.

thanks,
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