edits and cleanup on getting started documents.

1 files changed, 44 insertions, 35 deletions

diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn
index e97c794..69f498a 100644
--- a/website/getting-started-admin.mdwn
+++ b/website/getting-started-admin.mdwn
@@ -1,77 +1,86 @@
 Monkeysphere Server Administrator README
 ========================================
 
-FIXME: distinguish between publishing a new monkeysphere-enabled host
-key and accepting user identification via the web-of-trust.
+As the administrator of an SSH server, you can take advantage of the
+monkeysphere in two ways: you can publish the host key of your machine
+so that your users can have it automatically verified, and you can set
+up your machine to automatically identify connecting users by their
+presence in the OpenPGP web of trust.
 
+Server host key publication
+---------------------------
+To generate and publish a server host key:
 
-server service publication
---------------------------
-To publish a server host key:
-
-		# monkeysphere-server gen-key
-		# monkeysphere-server publish-key
+	# monkeysphere-server gen-key
+	# monkeysphere-server publish-key
 
 This will generate the key for server with the service URI
-(ssh://server.hostname).  The server admin should now sign the server
-key so that people in the admin's web of trust can authenticate the
+(`ssh://server.example.net`).  The server admin should now sign the
+server key so that people in the admin's web of trust can identify the
 server without manual host key checking:
 
-		$ gpg --search ='ssh://server.hostname'
-		$ gpg --sign-key ='ssh://server.hostname'
+	$ gpg --search ='ssh://server.example.net'
+	$ gpg --sign-key ='ssh://server.example.net'
 
 
 Update OpenSSH configuration files
 ----------------------------------
 
 To use the newly-generated host key for ssh connections, put the
-following line in /etc/ssh/sshd_config (be sure to remove references
-to any other key):
+following line in `/etc/ssh/sshd_config` (be sure to remove references
+to any other keys):
 
-		HostKey /var/lib/monkeysphere/ssh_host_rsa_key
+	HostKey /var/lib/monkeysphere/ssh_host_rsa_key
 
 FIXME: should we just suggest symlinks in the filesystem here instead?
 
-FIXME: What about DSA host keys?  The SSH RFC seems to require that DSA be available, though OpenSSH will work without a DSA host key.
+FIXME: What about DSA host keys?  The SSH RFC seems to require implementations support DSA, though OpenSSH will work without a DSA host key.
 
-To enable users to use the monkeysphere to authenticate against the
-web-of-trust, add this line to /etc/ssh/sshd_config (again, making
-sure that no other AuthorizedKeysFile directive exists):
+To enable users to use the monkeysphere to authenticate using the
+OpenPGP web of trust, add this line to `/etc/ssh/sshd_config` (again,
+making sure that no other AuthorizedKeysFile directive exists):
 
-		AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
+	AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 
+And then read the section below about how to ensure these files are
+maintained.  You'll need to restart `sshd` to have your changes take
+effect.  As with any change to `sshd_config`, be sure to retain an
+existing session to the machine while you test your changes so you
+don't get locked out.
 
-MonkeySphere authorized_keys maintenance
+Monkeysphere authorized_keys maintenance
 ----------------------------------------
 
-A system can maintain monkeysphere authorized_keys files for it's
-users.
+A host can maintain ssh authorized_keys files automatically for its
+users with the Monkeysphere.
 
 For each user account on the server, the userids of people authorized
 to log into that account would be placed in:
 
-		~/.config/monkeysphere/authorized_user_ids
+	~/.config/monkeysphere/authorized_user_ids
 
 However, in order for users to become authenticated, the server must
-determine that the user keys have "full" validity.  This means that
-the server must fully trust at least one person whose signature on the
-connecting user's key would validate the user.  This would generally be
-the server admin.  If the server admin's keyid is XXXXXXXX, then on
-the server run:
+determine that the user IDs on their keys have "full" validity.  This
+means that the server must fully trust at least one person whose
+signature on the connecting user's key would validate the relevant
+user ID.  The individuals trusted to identify users like this are
+known in the Monkeysphere as "Identity Certifiers".  In a simple
+scenario, the host's administrator would be trusted identity certifer.
+If the admin's OpenPGP keyid is `$GPGID`, then on the server run:
 
-		# monkeysphere-server add-identity-certifier XXXXXXXX
+	# monkeysphere-server add-identity-certifier $GPGID
 
-To update the monkeysphere authorized_keys file for user "bob", the
-system would then run the following:
+To update the monkeysphere authorized_keys file for user "bob" using
+the current set of identity certifiers, run:
 
-		# monkeysphere-server update-users bob
+	# monkeysphere-server update-users bob
 
 To update the monkeysphere authorized_keys file for all users on the
 the system, run the same command with no arguments:
 
-		# monkeysphere-server update-users
+	# monkeysphere-server update-users
 
 You probably want to set up a regularly scheduled job (e.g. with cron)
-to take care of this regularly.
+to take care of this automatically.
 
 FIXME: document other likely problems and troubleshooting techniques