| Message ID | 1401933919-23608-1-git-send-email-guihc.fnst@cn.fujitsu.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
On Thu, Jun 05, 2014 at 10:05:19AM +0800, Gui Hecheng wrote: > Based on Documentation/filesystems/btrfs.txt > > Signed-off-by: Gui Hecheng <guihc.fnst@cn.fujitsu.com> > --- > sys-utils/mount.8 | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 186 insertions(+) Thanks, but I'm not sure this is the right way. It would be better to create BTRFS specific btrfs.5 man page and maintain it together with another BTRFS stuff rather then within util-linux. In the mount.8 should be only a note about btrfs.5. My long time goal is to remove all FS specific sections (at least for mainstream filesystems) from mount.8, because we duplicate effort here. The primary and well maintained is usually kernel Documentation/filesystems/ and unfortunately FS developers don't care about mount.8 at all. The ideal solution would be to generate the FS man pages from kernel docs (for example from asciidoc etc.) See 6 years old discussions: http://marc.info/?t=122767310200002&r=1&w=2 Karel
On Thu, 2014-06-05 at 10:03 +0200, Karel Zak wrote: > On Thu, Jun 05, 2014 at 10:05:19AM +0800, Gui Hecheng wrote: > > Based on Documentation/filesystems/btrfs.txt > > > > Signed-off-by: Gui Hecheng <guihc.fnst@cn.fujitsu.com> > > --- > > sys-utils/mount.8 | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 186 insertions(+) > > Thanks, but I'm not sure this is the right way. It would be better to > create BTRFS specific btrfs.5 man page and maintain it together with > another BTRFS stuff rather then within util-linux. In the mount.8 > should be only a note about btrfs.5. > > My long time goal is to remove all FS specific sections (at least for > mainstream filesystems) from mount.8, because we duplicate effort > here. The primary and well maintained is usually kernel > Documentation/filesystems/ and unfortunately FS developers don't care > about mount.8 at all. > > The ideal solution would be to generate the FS man pages from kernel > docs (for example from asciidoc etc.) > > See 6 years old discussions: http://marc.info/?t=122767310200002&r=1&w=2 > Hi Karel, Thanks your comments. I do agree that this is *not* the best way. I think that your long time goal is really exciting to the FS developers. But for now, there are btrfs *users* complaining that they cannot find any help by refering to the mount manpage when they want to mount their btrfs. Actually, not every btrfs user have the mood to check the Documentation/filesystems/btrfs.txt or anywhere else when they just want to use a simple mount cmd. I think that adding the btrfs stuff into mount.8 do a certain help to the common btrfs users. By the way, I've checked the recent commmits of util-linux tree and found that there are still enthusiastic contributers making really meaningful changes to the mount.8. So, If it does not bother you much... Our btrfs users are really looking forward to a more kind and helpful mount manpage for btrfs. And then they will feel really happy that they could mount their btrfs in various ways easily as they like *just as the ext4 users do*. And I think there are many btrfs developers who will be glad to continue helping correct the btrfs part. Thanks -Gui > Karel > -- 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 Fri, Jun 06, 2014 at 02:32:39PM +0800, Gui Hecheng wrote: > But for now, there are btrfs *users* complaining that they cannot find > any help by refering to the mount manpage when they want to mount their > btrfs. Actually, not every btrfs user have the mood to check the > Documentation/filesystems/btrfs.txt or anywhere else when they just want > to use a simple mount cmd. The kernel is the "ideal place", but it's more dream than anything else... what we use for example for NFS is to maintain FS specific man page in userspace FS package (e.g. nfs-utils). Wouldn't be possible to add the man page to btrfs-progs package? The package is maintained by btrfs guys and I guess all btrfs users have very probably installed the package. > So, If it does not bother you much... I personally have no problem to maintain information about arbitrary FS in mount.8, the problem are updates. Unfortunately, kernel FS developers don't care about the man page at all and it's very often not up to date. [My experience is very bad. Not sure why, but for many kernel devels commit into Linus' tree is end of their work, they don't care if there is usable userpsace util or docs for users, people like Eric Biederman or Lukas Czerner are rare exception.] > And I think there are many btrfs developers who will be > glad to continue helping correct the btrfs part. OK, we can try it, if you still prefer mount.8. Karel
On Fri, 2014-06-06 at 11:44 +0200, Karel Zak wrote: > On Fri, Jun 06, 2014 at 02:32:39PM +0800, Gui Hecheng wrote: > > But for now, there are btrfs *users* complaining that they cannot find > > any help by refering to the mount manpage when they want to mount their > > btrfs. Actually, not every btrfs user have the mood to check the > > Documentation/filesystems/btrfs.txt or anywhere else when they just want > > to use a simple mount cmd. > > The kernel is the "ideal place", but it's more dream than anything > else... what we use for example for NFS is to maintain FS specific > man page in userspace FS package (e.g. nfs-utils). Ah, thanks for explaining so much to me, I can't agree more. > Wouldn't be possible to add the man page to btrfs-progs package? The > package is maintained by btrfs guys and I guess all btrfs users have > very probably installed the package. Actually, we just would like to see btrfs "staying with" ext4, xfs and other fs together. We feel a bit sad that ext4 and xfs both have stuff in mount.8 but btrfs doesn't. > > So, If it does not bother you much... > > I personally have no problem to maintain information about arbitrary > FS in mount.8, the problem are updates. Unfortunately, kernel FS developers > don't care about the man page at all and it's very often not up to date. > > [My experience is very bad. Not sure why, but for many kernel devels > commit into Linus' tree is end of their work, they don't care if there > is usable userpsace util or docs for users, people like Eric Biederman > or Lukas Czerner are rare exception.] Thanks for sharing the story with me, I really get a lot. > > And I think there are many btrfs developers who will be > > glad to continue helping correct the btrfs part. > > OK, we can try it, if you still prefer mount.8. Our guys will try our best to keep the mount.8 for btrfs up-to-date. At least, you have my promise. Thanks, -Gui > Karel > -- 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 Fri, Jun 06, 2014 at 11:44:28AM +0200, Karel Zak wrote: > I personally have no problem to maintain information about arbitrary > FS in mount.8, the problem are updates. Unfortunately, kernel FS developers > don't care about the man page at all and it's very often not up to date. Hmm.. another possible way would be to create a script for util-linux that will analyze kernel Documentation/filesystems/<fsname>.txt and report changes that is necessary to make to mount.8. It should be relative simple with git. I'll try it.. Karel
On Fri, 2014-06-06 at 12:03 +0200, Karel Zak wrote: > On Fri, Jun 06, 2014 at 11:44:28AM +0200, Karel Zak wrote: > > I personally have no problem to maintain information about arbitrary > > FS in mount.8, the problem are updates. Unfortunately, kernel FS developers > > don't care about the man page at all and it's very often not up to date. > > Hmm.. another possible way would be to create a script for util-linux > that will analyze kernel Documentation/filesystems/<fsname>.txt and > report changes that is necessary to make to mount.8. It should be > relative simple with git. I'll try it.. Ah, if so, thanks very much! -Gui > Karel > -- 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 Thu, Jun 05, 2014 at 10:05:19AM +0800, Gui Hecheng wrote: > Based on Documentation/filesystems/btrfs.txt > > Signed-off-by: Gui Hecheng <guihc.fnst@cn.fujitsu.com> > --- > sys-utils/mount.8 | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 186 insertions(+) Applied, thanks. Karel
On 6/6/14, 5:03 AM, Karel Zak wrote: > On Fri, Jun 06, 2014 at 11:44:28AM +0200, Karel Zak wrote: >> I personally have no problem to maintain information about arbitrary >> FS in mount.8, the problem are updates. Unfortunately, kernel FS developers >> don't care about the man page at all and it's very often not up to date. > > Hmm.. another possible way would be to create a script for util-linux > that will analyze kernel Documentation/filesystems/<fsname>.txt and > report changes that is necessary to make to mount.8. It should be > relative simple with git. I'll try it.. I like that idea. Maybe <fsname.txt> will need a defined format, though, right? Maybe asciidoc? I've still been meaning (in theory) to produce a mount manpage just for xfs. I'm still willing to do that if the above doesn't pan out. I just need to get to it. I'd be happy to do it for extN as well. -Eric > Karel > -- 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 Fri, Jun 06, 2014 at 10:52:48AM -0500, Eric Sandeen wrote: > On 6/6/14, 5:03 AM, Karel Zak wrote: > > On Fri, Jun 06, 2014 at 11:44:28AM +0200, Karel Zak wrote: > >> I personally have no problem to maintain information about arbitrary > >> FS in mount.8, the problem are updates. Unfortunately, kernel FS developers > >> don't care about the man page at all and it's very often not up to date. > > > > Hmm.. another possible way would be to create a script for util-linux > > that will analyze kernel Documentation/filesystems/<fsname>.txt and > > report changes that is necessary to make to mount.8. It should be > > relative simple with git. I'll try it.. > > I like that idea. Maybe <fsname.txt> will need a defined format, though, > right? Maybe asciidoc? > > I've still been meaning (in theory) to produce a mount manpage just for xfs. > I'm still willing to do that if the above doesn't pan out. I just need > to get to it. I'd be happy to do it for extN as well. Autogenerating man pages from an adhoc format sounds like the wrong approach. I'd much rather have proper man paged for every filesystem. With those we could also drop all that information from the kernel Documentation directory, where users won't looks for them anyway. Eric, if you take care of xfs an extN I'll get started on man pages for the various "minor" filesystems that don't really have active maintainers. Not sure if we should go for mount.<fstype>.8 man pages or just improve the <fstype>.5 pages, but I think the second one is more obvious. -- 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 Fri, 2014-06-06 at 12:17 +0200, Karel Zak wrote: > On Thu, Jun 05, 2014 at 10:05:19AM +0800, Gui Hecheng wrote: > > Based on Documentation/filesystems/btrfs.txt > > > > Signed-off-by: Gui Hecheng <guihc.fnst@cn.fujitsu.com> > > --- > > sys-utils/mount.8 | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ > > 1 file changed, 186 insertions(+) > > Applied, thanks. Thanks very much. -Gui > Karel > -- 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 6/7/14, 8:41 AM, Christoph Hellwig wrote: > On Fri, Jun 06, 2014 at 10:52:48AM -0500, Eric Sandeen wrote: >> On 6/6/14, 5:03 AM, Karel Zak wrote: >>> On Fri, Jun 06, 2014 at 11:44:28AM +0200, Karel Zak wrote: >>>> I personally have no problem to maintain information about arbitrary >>>> FS in mount.8, the problem are updates. Unfortunately, kernel FS developers >>>> don't care about the man page at all and it's very often not up to date. >>> >>> Hmm.. another possible way would be to create a script for util-linux >>> that will analyze kernel Documentation/filesystems/<fsname>.txt and >>> report changes that is necessary to make to mount.8. It should be >>> relative simple with git. I'll try it.. >> >> I like that idea. Maybe <fsname.txt> will need a defined format, though, >> right? Maybe asciidoc? >> >> I've still been meaning (in theory) to produce a mount manpage just for xfs. >> I'm still willing to do that if the above doesn't pan out. I just need >> to get to it. I'd be happy to do it for extN as well. > > Autogenerating man pages from an adhoc format sounds like the wrong > approach. I'd much rather have proper man paged for every filesystem. > With those we could also drop all that information from the kernel > Documentation directory, where users won't looks for them anyway. Well, asciidoc wouldn't be ad-hoc, but still... > Eric, if you take care of xfs an extN I'll get started on man pages > for the various "minor" filesystems that don't really have active > maintainers. > > Not sure if we should go for mount.<fstype>.8 man pages or just improve > the <fstype>.5 pages, but I think the second one is more obvious. Since some mount.<fstype> binaries actually exist, that would probably lead to some confusion. -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
On Sat, Jun 07, 2014 at 06:41:50AM -0700, Christoph Hellwig wrote: > On Fri, Jun 06, 2014 at 10:52:48AM -0500, Eric Sandeen wrote: > > On 6/6/14, 5:03 AM, Karel Zak wrote: > > > On Fri, Jun 06, 2014 at 11:44:28AM +0200, Karel Zak wrote: > > >> I personally have no problem to maintain information about arbitrary > > >> FS in mount.8, the problem are updates. Unfortunately, kernel FS developers > > >> don't care about the man page at all and it's very often not up to date. > > > > > > Hmm.. another possible way would be to create a script for util-linux > > > that will analyze kernel Documentation/filesystems/<fsname>.txt and > > > report changes that is necessary to make to mount.8. It should be > > > relative simple with git. I'll try it.. > > > > I like that idea. Maybe <fsname.txt> will need a defined format, though, > > right? Maybe asciidoc? > > > > I've still been meaning (in theory) to produce a mount manpage just for xfs. > > I'm still willing to do that if the above doesn't pan out. I just need > > to get to it. I'd be happy to do it for extN as well. > > Autogenerating man pages from an adhoc format sounds like the wrong > approach. I'd much rather have proper man paged for every filesystem. > With those we could also drop all that information from the kernel > Documentation directory, where users won't looks for them anyway. > > Eric, if you take care of xfs an extN I'll get started on man pages > for the various "minor" filesystems that don't really have active > maintainers. > > Not sure if we should go for mount.<fstype>.8 man pages or just improve > the <fstype>.5 pages, but I think the second one is more obvious. I think <fstype>.5 provides opportunity to distribute more information about the filesystem than just mount options only. See for example nfs.5 where is complete overview about the filesystem. Karel
On 6/7/14, 8:41 AM, Christoph Hellwig wrote: > On Fri, Jun 06, 2014 at 10:52:48AM -0500, Eric Sandeen wrote: >> On 6/6/14, 5:03 AM, Karel Zak wrote: >>> On Fri, Jun 06, 2014 at 11:44:28AM +0200, Karel Zak wrote: >>>> I personally have no problem to maintain information about arbitrary >>>> FS in mount.8, the problem are updates. Unfortunately, kernel FS developers >>>> don't care about the man page at all and it's very often not up to date. >>> >>> Hmm.. another possible way would be to create a script for util-linux >>> that will analyze kernel Documentation/filesystems/<fsname>.txt and >>> report changes that is necessary to make to mount.8. It should be >>> relative simple with git. I'll try it.. >> >> I like that idea. Maybe <fsname.txt> will need a defined format, though, >> right? Maybe asciidoc? >> >> I've still been meaning (in theory) to produce a mount manpage just for xfs. >> I'm still willing to do that if the above doesn't pan out. I just need >> to get to it. I'd be happy to do it for extN as well. > > Autogenerating man pages from an adhoc format sounds like the wrong > approach. I'd much rather have proper man paged for every filesystem. > With those we could also drop all that information from the kernel > Documentation directory, where users won't looks for them anyway. > > Eric, if you take care of xfs an extN I'll get started on man pages > for the various "minor" filesystems that don't really have active > maintainers. Ok, so I've sent xfs & extN and I am about to send btrfs. But I still have the nagging feeling that it would be better to have these mount-option manpages distributed with the kernel, which is ultimately what they must match. So although I've sent them all, I'm still feeling unsure about it. :) -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
diff --git a/sys-utils/mount.8 b/sys-utils/mount.8 index efa1ae8..ec8eab3 100644 --- a/sys-utils/mount.8 +++ b/sys-utils/mount.8 @@ -671,6 +671,7 @@ currently supported include: .IR adfs , .IR affs , .IR autofs , +.IR btrfs , .IR cifs , .IR coda , .IR coherent , @@ -1245,6 +1246,191 @@ Give blocksize. Allowed values are 512, 1024, 2048, 4096. These options are accepted but ignored. (However, quota utilities may react to such strings in .IR /etc/fstab .) +.SH "Mount options for btrfs" +Btrfs is a copy on write filesystem for Linux aimed at +implementing advanced features while focusing on fault tolerance, +repair and easy administration. +.TP +.BI 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. +.TP +.B autodefrag +Disable/enable auto defragmentation. +Auto defragmentation detects 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. +.TP +\fBcheck_int\fP|\fBcheck_int_data\fP|\fBcheck_int_print_mask=\fP\,\fIvalue\fP +These debugging options control the behavior of the integrity checking +module(the BTRFS_FS_CHECK_INTEGRITY config option required). + +.B 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. + +.B check_int_data +includes extent data in the integrity checks, and +implies the check_int option. + +.B 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 +.IR fs/btrfs/check-integrity.c +for more info. +.TP +.BI commit= seconds +Set the interval of periodic commit, 30 seconds by default. Higher +values defer data being synced to permanent storage with obvious +consequences when the system crashes. The upper bound is not forced, +but a warning is printed if it's more than 300 seconds (5 minutes). +.TP +\fBcompress\fP|\fBcompress=\fP\,\fItype\fP|\fBcompress-force\fP|\fBcompress-force=\fP\,\fItype\fP +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. +.TP +.B 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. +.TP +.BI device= devicepath +Specify a device during mount so that ioctls on the control device +can be avoided. Especially useful when trying to mount a multi-device +setup as root. May be specified multiple times for multiple devices. +.TP +.B discard +Disable/enable discard mount option. +Discard issues 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). +.TP +.B enospc_debug +Disable/enable debugging option to be more verbose in some ENOSPC conditions. +.TP +.BI 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. +.TP +.B flushoncommit +The +.B 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. +.TP +.B 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. +.TP +.BI 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. +.TP +.BI metadata_ratio= value +Specify that 1 metadata chunk should be allocated after every +.IRvalue +data chunks. Off by default. +.TP +.B noacl +Enable/disable support for Posix Access Control Lists (ACLs). See the +.B acl(5) +manual page for more information about ACLs. +.TP +.B nobarrier +Enable/disable 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 disabled on a device with a volatile +(non-battery-backed) write-back cache, nobarrier option will lead to +filesystem corruption on a system crash or power loss. +.TP +.B nodatacow +Enable/disable data copy-on-write for newly created files. +Nodatacow implies nodatasum, and disables all compression. +.TP +.B nodatasum +Enable/disable data checksumming for newly created files. +Datasum implies datacow. +.TP +.B notreelog +Enable/disable the tree logging used for fsync and O_SYNC writes. +.TP +.B 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. +.TP +.B rescan_uuid_tree +Force check and rebuild procedure of the UUID tree. This should not +normally be needed. +.TP +.B skip_balance +Skip automatic resume of interrupted balance operation after mount. +May be resumed with "btrfs balance resume." +.TP +.B nospace_cache +Disable freespace cache loading without clearing the cache. +.TP +.B clear_cache +Force clearing and rebuilding of the disk space cache if something +has gone wrong. +.TP +.BR 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. +.TP +.BI subvol= path +Mount subvolume at +.IR path +rather than the root subvolume. The +.IR path +is relative to the top level subvolume. +.TP +.BI 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. +.TP +.BI subvolrootid= objectid (deprecated) +Mount subvolume specified by +.IR 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. +.TP +.BI 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. +.TP +.B user_subvol_rm_allowed +Allow subvolumes to be deleted by a non-root user. Use with caution. .SH "Mount options for cifs" See the options section of the
Based on Documentation/filesystems/btrfs.txt Signed-off-by: Gui Hecheng <guihc.fnst@cn.fujitsu.com> --- sys-utils/mount.8 | 186 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+)