Add fscrypt man page

[tyhicks]

The fscrypt tool should have a man page so that users can easily and locally find more information on how to use fscrypt. The man page should probably live in section 8 since fscrypt is mostly a system administration tool.

[josephlr]

Is this a good place to get started on writing a man page?

Also, the ecryptfs man pages are spread throughout many sections. The root page is in section 7 but some components are in section 1 or section 8. Should I just put everything in section 8 or split things up accordingly?

[tyhicks]

On 07/13/2017 04:03 AM, Joseph Richey wrote:

Is this http://www.linuxhowtos.org/System/creatingman.htm a good place to get started on writing a man page?

That's a fine place to start if one simply wants to write raw groff. There's nothing wrong with that and it is probably the simplest solution.

There are tools that convert other formats, such as pod, Markdown, RST, etc., into man pages but most of them seem to pull in too many unrelated build dependencies (Perl for pod2man, Ruby for ronn, Python for rst2man) for a Go/C project.

Also, the ecryptfs man pages are spread throughout many sections. The root page is in section 7 https://linux.die.net/man/7/ecryptfs but some components are in section 1 https://linux.die.net/man/1/ecryptfs-add-passphrase or section 8 https://linux.die.net/man/8/pam_ecryptfs. Should I just put everything in section 8 or split things up accordingly?

The man page for the fscrypt tool should go into section 8. If you plan to write additional man pages, it'll depend on what they're documenting. The man(1) man page gives a decent summary of which sections should be used.

I wouldn't necessarily follow the lead of ecryptfs-utils man pages but they're a fairly good reference.

[josephlr]

Below is the basic plan for man page entries. After they are completed, a good amount of the documentation in README.md will be deleted and replaced with the appropriate man page links. Running fscrypt COMMAND --help will also show the man pages (if they are available). This is similar to how git COMMAND --help works currently.

• fscryptctl
  • Complete description of all functionality
  • The tool is small so this shouldn't be too bad
  • Include where to report bugs (here)
• fscrypt
  • Overview of the tool
  • Tool's purpose
  • Structures of files (/etc/fscrypt.conf, MNT/.fscrypt)
  • System requirements
  • Filesystem requirements
  • Limitations (no encrypting root, no encrypting metadata)
  • Where to report bugs (here)
  • Links to more detailed command information
• pam_fscrypt
  • Description of purpose/functionality
  • PAM services provided
  • Flags (and which services they effect)
  • Installation instructions/tips
• fscrypt-setup
  • Docs for fscrypt setup (creating /etc/fscrypt.conf)
  • Docs for fscrypt setup MOUNTPOINT (creating filesystem metadata)
• fscrypt-encrypt
  • Docs for fscrypt encrypt and fscrypt unlock
  • Notes about keyring weirdness w/ provisioning
• fscrypt-purge
  • Docs for fscrypt purge MOUNTPOINT
  • Explain dropping vs not dropping caches
  • Limitations of running as root
  • Issues w/ Kernel memory and DMA
• fscrypt-status
  • Docs for fscrypt status: the global, filesystem, and directory versions.
  • Precise format (so it can be reliably grepped)
  • Difference between "supported", "not supported", and "not enabled"
• fscrypt-metadata
  • Docs for all fscrypt metadata SUBCOMMAND
  • Examples of weird setups requiring the metadata commands.
  • Examples of damaged setups requiring the metadata commands.