some tweaks to the man pages

2 files changed, 78 insertions, 66 deletions

diff --git a/man/man8/monkeysphere-authentication.8 b/man/man8/monkeysphere-authentication.8
index 68a7a1b..2b0091e 100644
--- a/man/man8/monkeysphere-authentication.8
+++ b/man/man8/monkeysphere-authentication.8
@@ -20,26 +20,28 @@ authentication.
 \fBmonkeysphere-authentication\fP is a Monkeysphere server admin utility.
 
 .SH SUBCOMMANDS
-\fBmonkeysphere-authentication\fP takes various subcommands.(Users may use the
-abbreviated subcommand in parentheses):
 
+\fBmonkeysphere-authentication\fP takes various subcommands.
 .TP
-.B update-users (u) [ACCOUNT]...
-Rebuild the monkeysphere-controlled authorized_keys files.  For each specified
-account, the user ID's listed in the account's authorized_user_ids file are
-processed.  For each user ID, gpg will be queried for keys associated with that
-user ID, optionally querying a keyserver.  If an acceptable key is found (see
-KEY ACCEPTABILITY in monkeysphere(7)), the key is added to the account's
-monkeysphere-controlled authorized_keys file.  If the RAW_AUTHORIZED_KEYS
-variable is set, then a separate authorized_keys file (usually
-~USER/.ssh/authorized_keys) is appended to the monkeysphere-controlled
-authorized_keys file.  If no accounts are specified, then all accounts on the
-system are processed.  `u' may be used in place of `update-users'.
-
-\" XXX
-
+.B setup
+Setup the server for Monkeysphere user authentication.  `s' may be
+used in place of `setup'.
 .TP
-.B add-id-certifier (c+) KEYID
+.B update-users [ACCOUNT]...
+Rebuild the monkeysphere-controlled authorized_keys files.  For each
+specified account, the user ID's listed in the account's
+authorized_user_ids file are processed.  For each user ID, gpg will be
+queried for keys associated with that user ID, optionally querying a
+keyserver.  If an acceptable key is found (see KEY ACCEPTABILITY in
+monkeysphere(7)), the key is added to the account's
+monkeysphere-controlled authorized_keys file.  If the
+RAW_AUTHORIZED_KEYS variable is set, then a separate authorized_keys
+file (usually ~USER/.ssh/authorized_keys) is appended to the
+monkeysphere-controlled authorized_keys file.  If no accounts are
+specified, then all accounts on the system are processed.  `u' may be
+used in place of `update-users'.
+.TP
+.B add-id-certifier KEYID
 Instruct system to trust user identity certifications made by KEYID.
 Using the `-n' or `--domain' option allows you to indicate that you
 only trust the given KEYID to make identifications within a specific
@@ -50,11 +52,11 @@ the `-t' or `--trust' option (possible values are `marginal' and
 with the `-d' or `--depth' option (default is 1).  `c+' may be used in
 place of `add-id-certifier'.
 .TP
-.B remove-id-certifier (c-) KEYID
+.B remove-id-certifier KEYID
 Instruct system to ignore user identity certifications made by KEYID.
 `c-' may be used in place of `remove-id-certifier'.
 .TP
-.B list-id-certifiers (c)
+.B list-id-certifiers
 List key IDs trusted by the system to certify user identities.  `c'
 may be used in place of `list-id-certifiers'.
 .TP
@@ -66,11 +68,13 @@ Output a brief usage summary.  `h' or `?' may be used in place of
 show version number
 
 .SH "EXPERT" SUBCOMMANDS
+
 Some commands are very unlikely to be needed by most administrators.
-These commands must follow the word `expert'.
+These commands must prefaced by the word `expert'.
 .TP
-.B diagnostics (d)
-Review the state of the server with respect to authentication.
+.B diagnostics
+Review the state of the server with respect to authentication.  `d'
+may be used in place of `diagnostics'.
 .TP
 .B gpg-cmd
 Execute a gpg command on the gnupg-authentication keyring as the
@@ -79,7 +83,7 @@ arguments need to be quoted).  Use this command with caution, as
 modifying the gnupg-authentication keyring can affect ssh user
 authentication.
 
-.SH SETUP
+.SH SETUP USER AUTHENTICATION
 
 If the server will handle user authentication through
 monkeysphere-generated authorized_keys files, the server must be told
@@ -116,7 +120,7 @@ to grant access to user accounts for remote users.  You must also tell
 sshd to look at the monkeysphere-generated authorized_keys file for
 user authentication by setting the following in the sshd_config:
 
-AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
+AuthorizedKeysFile /var/lib/monkeysphere/authentication/authorized_keys/%u
 
 It is recommended to add "monkeysphere-authentication update-users" to a
 system crontab, so that user keys are kept up-to-date, and key
@@ -125,7 +129,7 @@ revocations and expirations can be processed in a timely manner.
 .SH ENVIRONMENT
 
 The following environment variables will override those specified in
-(defaults in parentheses):
+the config file (defaults in parentheses):
 .TP
 MONKEYSPHERE_MONKEYSPHERE_USER
 User to control authentication keychain (monkeysphere).
@@ -135,7 +139,7 @@ Set the log level (INFO).  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
 increasing order of verbosity.
 .TP
 MONKEYSPHERE_KEYSERVER
-OpenPGP keyserver to use (subkeys.pgp.net).
+OpenPGP keyserver to use (pool.sks-keyservers.net).
 .TP
 MONKEYSPHERE_AUTHORIZED_USER_IDS
 Path to user authorized_user_ids file
@@ -156,8 +160,10 @@ Monkeysphere-generated user authorized_keys files.
 
 .SH AUTHOR
 
-Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn
-Gillmor <dkg@fifthhorseman.net>
+Written by:
+Jameson Rollins <jrollins@fifthhorseman.net>,
+Daniel Kahn Gillmor <dkg@fifthhorseman.net>,
+Matthew Goins <mjgoins@openflows.com>
 
 .SH SEE ALSO
 
diff --git a/man/man8/monkeysphere-host.8 b/man/man8/monkeysphere-host.8
index fd676a4..78b6b4a 100644
--- a/man/man8/monkeysphere-host.8
+++ b/man/man8/monkeysphere-host.8
@@ -23,6 +23,10 @@ connection authentication.
 
 \fBmonkeysphere-host\fP takes various subcommands:
 .TP
+.B show-key
+Output information about host's OpenPGP and SSH keys.  `s' may be used
+in place of `show-key'.
+.TP
 .B extend-key EXPIRE
 Extend the validity of the OpenPGP key for the host until EXPIRE from
 the present.  If EXPIRE is not specified, then the user will be
@@ -36,7 +40,6 @@ does:
       <n>y = key expires in n years
 .fi
 `e' may be used in place of `extend-key'.
-
 .TP
 .B add-hostname HOSTNAME
 Add a hostname user ID to the server host key.  `n+' may be used in
@@ -47,11 +50,12 @@ Revoke a hostname user ID from the server host key.  `n-' may be used
 in place of `revoke-hostname'.
 .TP
 .B add-revoker FINGERPRINT
-
+Add a revoker to the host's OpenPGP key.  `o' may be be used in place
+of `add-revoker'.
 .TP
-.B show-key
-Output gpg information about host's OpenPGP key.  `s' may be used in
-place of `show-key'.
+.B revoke-key
+Revoke the host's OpenPGP key.  `r' may be used in place of
+`revoke-key'.
 .TP
 .B publish-key
 Publish the host's OpenPGP key to the keyserver.  `p' may be used in
@@ -63,9 +67,11 @@ Output a brief usage summary.  `h' or `?' may be used in place of
 .TP
 .B version
 show version number
+
 .SH "EXPERT" SUBCOMMANDS
+
 Some commands are very unlikely to be needed by most administrators.
-These commands must follow the word `expert'.
+These commands must prefaced by the word `expert'.
 .TP
 .B gen-key [HOSTNAME]
 Generate a OpenPGP key for the host.  If HOSTNAME is not specified,
@@ -73,18 +79,8 @@ then the system fully-qualified domain name will be user.  An
 alternate key bit length can be specified with the `-l' or `--length'
 option (default 2048).  An expiration length can be specified with the
 `-e' or `--expire' option (prompt otherwise).  The expiration format
-is the same as that of \fBextend-key\fP, below.  A key revoker
-fingerprint can be specified with the `-r' or `--revoker' option.  `g'
-may be used in place of `gen-key'.
-
-.TP
-.B diagnostics
-Review the state of the server with respect to the MonkeySphere in
-general and report on suggested changes.  Among other checks, this
-includes making sure there is a valid host key, that the key is
-published, that the sshd configuration points to the right place, and
-that there are at least some valid identity certifiers.  `d' may be
-used in place of `diagnostics'.
+is the same as that of \fBextend-key\fP, below.  `g' may be used in
+place of `gen-key'.
 .TP
 .B import-key
 FIXME:
@@ -92,53 +88,63 @@ FIXME:
    --hostname (-h) NAME[:PORT]         hostname for key user ID
    --keyfile (-f) FILE                 key file to import
    --expire (-e) EXPIRE                date to expire
+.TP
+.B diagnostics
+Review the state of the monkeysphere server host key and report on
+suggested changes.  Among other checks, this includes making sure
+there is a valid host key, that the key is published, that the sshd
+configuration points to the right place, etc.  `d' may be used in
+place of `diagnostics'.
 
-.SH SETUP
+.SH SETUP HOST AUTHENTICATION
 
-In order to start using the monkeysphere, you must first generate an
-OpenPGP key for the server and convert that key to an ssh key that can
-be used by ssh for host authentication.  This can be done with the
-\fBgen-key\fP subcommand:
+To enable host verification via the monkeysphere, the host's key must
+be published to the Web of Trust.  This is not done by default.  To
+publish the host key to the keyservers, run the following command:
 
-$ monkeysphere-server gen-key
+$ monkeysphere-host publish-key
 
-To enable host verification via the monkeysphere, you must then
-publish the host's key to the Web of Trust using the \fBpublish-key\fP
-command to push the key to a keyserver.  You must also modify the
-sshd_config on the server to tell sshd where the new server host key
-is located:
+You must also modify the sshd_config on the server to tell sshd where
+the new server host key is located:
 
-HostKey /var/lib/monkeysphere/ssh_host_rsa_key
+HostKey /var/lib/monkeysphere/host/ssh_host_rsa_key
 
 In order for users logging into the system to be able to identify the
 host via the monkeysphere, at least one person (e.g. a server admin)
 will need to sign the host's key.  This is done using standard OpenPGP
-keysigning techniques, usually: pul the key from the keyserver, verify
-and sign the key, and then re-publish the signature.  Once an admin's
-signature is published, users logging into the host can use it to
-validate the host's key.
+keysigning techniques, usually: pull the key from the keyserver,
+verify and sign the key, and then re-publish the signature.  Once an
+admin's signature is published, users logging into the host can use it
+to validate the host's key.
+
+.SH ENVIRONMENT
 
+The following environment variables will override those specified in
+the config file (defaults in parentheses):
 .TP
 MONKEYSPHERE_LOG_LEVEL
 Set the log level (INFO).  Can be SILENT, ERROR, INFO, VERBOSE, DEBUG, in
 increasing order of verbosity.
 .TP
 MONKEYSPHERE_KEYSERVER
-OpenPGP keyserver to use (subkeys.pgp.net).
+OpenPGP keyserver to use (pool.sks-keyservers.net).
 
 .SH FILES
+
 .TP
 /etc/monkeysphere/monkeysphere-host.conf
 System monkeysphere-host config file.
 .TP
-/var/lib/monkeysphere/ssh_host_rsa_key
+/var/lib/monkeysphere/host/ssh_host_rsa_key
 Copy of the host's private key in ssh format, suitable for use by
 sshd.
 
 .SH AUTHOR
 
-Written by Jameson Rollins <jrollins@fifthhorseman.net>, Daniel Kahn
-Gillmor <dkg@fifthhorseman.net>
+Written by:
+Jameson Rollins <jrollins@fifthhorseman.net>,
+Daniel Kahn Gillmor <dkg@fifthhorseman.net>,
+Matthew Goins <mjgoins@openflows.com>
 
 .SH SEE ALSO