Talk:NewNfsManPage

From Linux NFS

Revision as of 20:10, 7 September 2007

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

cel

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 bold / nobold 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

cel 16:10, 7 September 2007 (EDT)