Talk:NewNfsManPage

From Linux NFS

(Difference between revisions)
Jump to: navigation, search
(New page: Let's try hashing out changes here before they go into the new nfs(5) man page. ~~~)
(→The real man page reference)
 
(21 intermediate revisions not shown)
Line 2: Line 2:
[[User:Chucklever|cel]]
[[User:Chucklever|cel]]
 +
 +
== To Do ==
 +
 +
# Expand the SECURITY CONSIDERATIONS section
 +
# Add more useful examples, such as mounting /usr with ro,nolock,nocto
 +
# Refine the discussion of various options
 +
# Check for spelling, grammar, punctuation, style, and typography
 +
# Review with mailing list
 +
# Review with LDP
 +
 +
== Things that might be hard to add ==
 +
 +
Gbarazer suggests adding details on starting and stopping NFS services.  I'm not sure how to incorporate details on starting and stopping NFS services.  The initscripts that manage this are in a totally different package, and often differ among the various distributions.  Another area of weak documentation that arguably belongs in nfs(5) is the use of /etc/sysconfig/nfs, but I think that is a Red Hat specific configuration file.
 +
 +
What is the scope of this man page?  I don't think it's all of NFS.  The SYNOPSIS suggests it is only for describing the format of /etc/fstab; thus we should probably leave out server-related items.
 +
 +
It would be a good idea to locate the remaining pieces of user-land NFS documentation to help understand where some of this belongs.
 +
 +
=== Possible additions ===
 +
 +
* Add a section discussing NFSROOT
 +
** within scope if NFSROOT mounts are also described in /etc/fstab; are they discussed outside of linux/Documentation/ ?
 +
* Add some information about /etc/mtab and how it is used by umount.nfs
 +
** possibly better added to '''umount.nfs'''(8)
 +
* Add a section discussing how to mount through a firewall
 +
** I can't think of a better place to add this than '''nfs'''(5)
 +
* Add a section discussing "-o remount" -- which options don't work as expected over a remount
 +
** not sure where to place this information
 +
* Add a section or two covering NFS server configuration (/etc/exports, exportfs)
 +
** not within the scope of '''nfs'''(5)
 +
 +
[[User:Chucklever|cel]]
 +
 +
== The noac, intr, and nocto options ==
 +
 +
I moved these options again because:
 +
 +
1.  I don't think nfs4 supports the nocto option, so I moved it out of the "all versions" section into the "nfs only section"
 +
 +
2.  The default behavior of "intr" is currently different between "nfs" and "nfs4", so I moved it out of the "all versions" section and into both the "nfs only section" and the "nfs4 only section"
 +
 +
3.  I moved the "noac" option initially, but it should work for both "nfs and "nfs4" so I moved it back to the "all versions" section and reworked the description a bit.
 +
 +
[[User:Chucklever|cel]]
 +
 +
== Format for individual options ==
 +
 +
Although other people don't have an issue with this, I don't like defining these options in their "no" form.
 +
 +
How should the options definitions be described in the web page?
 +
 +
# option
 +
# nooption
 +
# option / nooption
 +
# option | nooption
 +
 +
Solaris chooses the last form, but '''mount'''(8) on Linux uses the first three forms.
 +
 +
Also, should the whole option title be italicized, or just the value part of keyword=''value''?  Solaris chooses the latter.
 +
 +
Should check with the LDP to find out.  The Linux '''mount'''(8) man page uses bold roman for each option title, and for keyword=value options, it uses bold for the keyword, and underlined (italicized) for the value descriptor.
 +
 +
[[User:Chucklever|cel]] 15:44, 4 September 2007 (EDT)
 +
 +
== Suggestions from bfields ==
 +
 +
* Perhaps remove generic description of /etc/fstab entirely, or replace it with a one sentence reference to '''fstab'''(5)
 +
 +
* Add a sentence or two to "soft|hard" about why "soft" should be avoided; maybe copy a word or two from the NFS FAQ
 +
 +
* Restore to the "options" section intro a brief discussion of how NFS and RPC are related
 +
 +
* (cel) Sort the options either alphabetically or keyword=value followed by boolean, or list the most frequently used options first
 +
 +
* Consider a BUGS section that talks about historical behavior of the Linux client and mount option defaults
 +
 +
* (cel) Fix the typography of the option titles
 +
 +
* (cel) Use '''keyword''' / '''nokeyword''' and '''keyword'''=''value''
 +
 +
* Add another use case to '''bg''' / '''fg''' : client boots before server; alternatively these issues can be solved using the automounter ('''automount'''(8))
 +
 +
* Add a TRANSPORT section that discusses that advantages and disadvantages of UDP and TCP, and provides some space for adding discussion about NFS/RDMA; reference this in the proto= subsection
 +
 +
* (cel) Add a subsection discussing the special NFS behavior of '''async''' / '''sync'''
 +
 +
* Should we deprecate namlen, posix, mounthost and nfsprog with this revision of the man page?
 +
 +
* Refer to DATA AND METADATA COHERENCY section in '''nocto''' and '''noac''' subsections
 +
 +
* Discuss idmapd and gssd in the SECURITY CONSIDERATIONS section
 +
 +
* Where should we discuss ACLs?  SECURITY CONSIDERATIONS needs a reference to the get/setacl man pages
 +
 +
* (cel) Add example of using actimeo=7200 for /usr
 +
 +
[[User:Chucklever|cel]] 16:10, 7 September 2007 (EDT)
 +
 +
== The real man page reference ==
 +
 +
I finally found the [http://www.faqs.org/docs/Linux-mini/Man-Page.html correct reference] for writing man pages for Linux.
 +
 +
It turns out the [http://tldp.org Linux Documentation Project] produces everything in DocBook, thus it doesn't have a set of conventions for man pages.
 +
 +
[[User:Chucklever|cel]] 11:52, 18 September 2007 (EDT)
 +
 +
== NLM locking ==
 +
 +
Is it worth providing a section that explains locking on NFS?  It could cover the NLM side protocol and how NFSv4 uses in-band locking.
 +
 +
 +
== Comments from [[User:Trondmy|trondmy]] ==
 +
 +
* Yes. NFSv4 does support nocto, but it applies only to directories.
 +
* posix/noposix are no-ops in most kernels
 +
* nfsprog is a no-op.
 +
* how about a discussion of proto=rdma?
 +
* Please note that the NFSACL sideband protocol is the same as that used by Solaris. There is no industry-wide standard for ACL support prior to NFSv4

Latest revision as of 17:04, 12 September 2010

Let's try hashing out changes here before they go into the new nfs(5) man page.

cel

Contents

To Do

  1. Expand the SECURITY CONSIDERATIONS section
  2. Add more useful examples, such as mounting /usr with ro,nolock,nocto
  3. Refine the discussion of various options
  4. Check for spelling, grammar, punctuation, style, and typography
  5. Review with mailing list
  6. Review with LDP

Things that might be hard to add

Gbarazer suggests adding details on starting and stopping NFS services. I'm not sure how to incorporate details on starting and stopping NFS services. The initscripts that manage this are in a totally different package, and often differ among the various distributions. Another area of weak documentation that arguably belongs in nfs(5) is the use of /etc/sysconfig/nfs, but I think that is a Red Hat specific configuration file.

What is the scope of this man page? I don't think it's all of NFS. The SYNOPSIS suggests it is only for describing the format of /etc/fstab; thus we should probably leave out server-related items.

It would be a good idea to locate the remaining pieces of user-land NFS documentation to help understand where some of this belongs.

Possible additions

  • Add a section discussing NFSROOT
    • within scope if NFSROOT mounts are also described in /etc/fstab; are they discussed outside of linux/Documentation/ ?
  • Add some information about /etc/mtab and how it is used by umount.nfs
    • possibly better added to umount.nfs(8)
  • Add a section discussing how to mount through a firewall
    • I can't think of a better place to add this than nfs(5)
  • Add a section discussing "-o remount" -- which options don't work as expected over a remount
    • not sure where to place this information
  • Add a section or two covering NFS server configuration (/etc/exports, exportfs)
    • not within the scope of nfs(5)

cel

The noac, intr, and nocto options

I moved these options again because:

1. I don't think nfs4 supports the nocto option, so I moved it out of the "all versions" section into the "nfs only section"

2. The default behavior of "intr" is currently different between "nfs" and "nfs4", so I moved it out of the "all versions" section and into both the "nfs only section" and the "nfs4 only section"

3. I moved the "noac" option initially, but it should work for both "nfs and "nfs4" so I moved it back to the "all versions" section and reworked the description a bit.

cel

Format for individual options

Although other people don't have an issue with this, I don't like defining these options in their "no" form.

How should the options definitions be described in the web page?

  1. option
  2. nooption
  3. option / nooption
  4. option | nooption

Solaris chooses the last form, but mount(8) on Linux uses the first three forms.

Also, should the whole option title be italicized, or just the value part of keyword=value? Solaris chooses the latter.

Should check with the LDP to find out. The Linux mount(8) man page uses bold roman for each option title, and for keyword=value options, it uses bold for the keyword, and underlined (italicized) for the value descriptor.

cel 15:44, 4 September 2007 (EDT)

Suggestions from bfields

  • Perhaps remove generic description of /etc/fstab entirely, or replace it with a one sentence reference to fstab(5)
  • Add a sentence or two to "soft|hard" about why "soft" should be avoided; maybe copy a word or two from the NFS FAQ
  • Restore to the "options" section intro a brief discussion of how NFS and RPC are related
  • (cel) Sort the options either alphabetically or keyword=value followed by boolean, or list the most frequently used options first
  • Consider a BUGS section that talks about historical behavior of the Linux client and mount option defaults
  • (cel) Fix the typography of the option titles
  • (cel) Use keyword / nokeyword and keyword=value
  • Add another use case to bg / fg : client boots before server; alternatively these issues can be solved using the automounter (automount(8))
  • Add a TRANSPORT section that discusses that advantages and disadvantages of UDP and TCP, and provides some space for adding discussion about NFS/RDMA; reference this in the proto= subsection
  • (cel) Add a subsection discussing the special NFS behavior of async / sync
  • Should we deprecate namlen, posix, mounthost and nfsprog with this revision of the man page?
  • Refer to DATA AND METADATA COHERENCY section in nocto and noac subsections
  • Discuss idmapd and gssd in the SECURITY CONSIDERATIONS section
  • Where should we discuss ACLs? SECURITY CONSIDERATIONS needs a reference to the get/setacl man pages
  • (cel) Add example of using actimeo=7200 for /usr

cel 16:10, 7 September 2007 (EDT)

The real man page reference

I finally found the correct reference for writing man pages for Linux.

It turns out the Linux Documentation Project produces everything in DocBook, thus it doesn't have a set of conventions for man pages.

cel 11:52, 18 September 2007 (EDT)

NLM locking

Is it worth providing a section that explains locking on NFS? It could cover the NLM side protocol and how NFSv4 uses in-band locking.


Comments from trondmy

  • Yes. NFSv4 does support nocto, but it applies only to directories.
  • posix/noposix are no-ops in most kernels
  • nfsprog is a no-op.
  • how about a discussion of proto=rdma?
  • Please note that the NFSACL sideband protocol is the same as that used by Solaris. There is no industry-wide standard for ACL support prior to NFSv4
Retrieved from "http://wiki.linux-nfs.org/wiki/index.php/Talk:NewNfsManPage"
Personal tools