readability revision for getting-started-admin.mdwn

diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn
index 9010132db7412b7f054ab2050a97aaccf66ec62c..d1146f1da57fd2dc1a377882b913e3caac62d609 100644 (file)
--- a/website/getting-started-admin.mdwn
+++ b/website/getting-started-admin.mdwn
@@ -2,21 +2,15 @@ Monkeysphere Server Administrator README
 ========================================
 
 As the administrator of an SSH server, you can take advantage of the
 ========================================
 
 As the administrator of an SSH server, you can take advantage of the

-monkeysphere in two ways:
+Monkeysphere in two ways:

 
 1. you can publish the host key of your machine to the Web of Trust
 
 1. you can publish the host key of your machine to the Web of Trust

-(WoT) so that your users can have it automatically verified, and
+(WoT) so that your users can automatically verify it, and

 
 2. you can set up your machine to automatically identify connecting
 users by their presence in the OpenPGP Web of Trust.
 
 
 2. you can set up your machine to automatically identify connecting
 users by their presence in the OpenPGP Web of Trust.
 

-These things are not mutually required, and it is in fact possible to
-do one without the other.  However, it is highly recommend that you at
-least do the first.  Even if you decide that you do not want to use
-the monkeysphere to authenticate users to your system, you should at
-least the host key into the Web of Trust so that your users can be
-sure they're connecting to the correct machine.
-
+These two pieces are independent: you can do one without the other.

 
 Monkeysphere for host verification (monkeysphere-host)
 ======================================================
 
 Monkeysphere for host verification (monkeysphere-host)
 ======================================================


@@ -28,33 +22,40 @@ To begin, you must first import an ssh host key.  This assumes that
 you have the ssh server installed, and that you have generated a host
 RSA key.  Once that has been done, import the key:
 
 you have the ssh server installed, and that you have generated a host
 RSA key.  Once that has been done, import the key:
 

-       # monkeysphere-host /etc/ssh/ssh\_host\_rsa\_key
+       # monkeysphere-host import-key /etc/ssh/ssh\_host\_rsa\_key

 
 

-This will generate the key for server with the service URI
-(`ssh://server.example.net`).  You can output the new key information
-with the 'show-key' command:
+This will generate an OpenPGP certificate for server containing the
+service URI (`ssh://server.example.net`).  Now you can display
+information about the host key's certificate with the 'show-key'
+command:

 
        # monkeysphere-host show-key
 
 
        # monkeysphere-host show-key
 

-Once the key has been imported, it needs to be publish to the Web of
-Trust:
+Once the host key's certificate has been generated, you'll probably
+want to publish it to the public keyservers which distribute the Web
+of Trust:

 
        # monkeysphere-host publish-key
 
 
        # monkeysphere-host publish-key
 

-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.  On your (the admin's) local machine retrieve the host key:
-
-       $ gpg --search '=ssh://server.example.net'
+But anyone could publish a simple self-signed certificate to the WoT
+with any name attached.  Your users should be able to tell that
+someone they know and trust with the machine (e.g. *you*, the
+administrator) has verified that this particular key is indeed the
+correct key.  So your next step is to sign the host's key with your
+own OpenPGP key.

 
 

-Now sign the server key:
+On your (the admin's) local machine retrieve the host key (it may take
+several minutes for the key to propagate across the keyserver
+network), and sign it:

 
 

+       $ gpg --search '=ssh://server.example.net'

        $ gpg --sign-key '=ssh://server.example.net'
 
        $ gpg --sign-key '=ssh://server.example.net'
 

-Make sure you compare the fingerprint of the retrieved with the one
-output with the 'show-key' command above, to verify you are signing
-the correct key.  Finally, publish your signatures back to the
-keyservers:
+Make sure you compare the fingerprint of the retrieved certificate
+with the output from the 'show-key' command above!
+
+Finally, publish your signatures back to the keyservers, so that your
+users can automatically verify your machine when they connect:

 
        $ gpg --send-key '=ssh://server.example.net'
 
 
        $ gpg --send-key '=ssh://server.example.net'
 


@@ -64,10 +65,18 @@ signing host keys.
 Monkeysphere for user authentication (monkeysphere-authentication)
 ==================================================================
 
 Monkeysphere for user authentication (monkeysphere-authentication)
 ==================================================================
 

-A host can maintain ssh `authorized_keys` files automatically for its
-users with the Monkeysphere.  These `authorized_keys` files can then
-be used to enable users to use the monkeysphere to authenticate to
-your machine using the OpenPGP web of trust.
+A host can maintain ssh-style `authorized_keys` files automatically
+for its users with the Monkeysphere.  This frees you (the
+administrator) from the task of manually checking/placing SSH keys,
+and enables users to do relatively painless key transitions, and to
+quickly and universally revoke access if they find that their ssh key
+has become compromised.
+
+You simply tell the system what *person* (identified by her OpenPGP
+User ID) should have access to an account, the Monkeysphere takes care
+of generating the proper `authorized_keys` file and keeping it
+up-to-date, and `sshd` reads the generated `authorized_keys` files
+directly.

 
 Monkeysphere authorized_keys maintenance
 ----------------------------------------
 
 Monkeysphere authorized_keys maintenance
 ----------------------------------------


@@ -77,20 +86,29 @@ to log into that account would be placed in:
 
        ~/.monkeysphere/authorized_user_ids
 
 
        ~/.monkeysphere/authorized_user_ids
 

-However, in order for users to become authenticated, the server must
-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 a trusted identity
-certifer.  If the admin's OpenPGP keyid is `$GPGID`, then on the
-server run:
+The server will use the Monkeysphere to look up matching OpenPGP
+certificates, validate them, and generate an `authorized_keys` file.
+
+To validate the OpenPGP certificates, the server needs to know who it
+can trust to correctly identify users.  The individuals trusted to
+identify users like this are known in the Monkeysphere as "Identity
+Certifiers".  One obvious choice is to trust *you*, the administrator,
+to be an Identity Certifier.  If your OpenPGP keyid is `$GPGID`, then
+run the following command on the server:

 
        # monkeysphere-authentication add-identity-certifier $GPGID
 
 
        # monkeysphere-authentication add-identity-certifier $GPGID
 

-To update the monkeysphere `authorized_keys` file for user "bob" using
-the current set of identity certifiers, run:
+You'll probably only set up Identity Certifiers when you set up the
+machine.  After that, you'll only need to add or remove Identity
+Certifiers when the roster of admins on the machine changes, or when
+one of the admins switches OpenPGP keys.
+
+Now that the server knows who to trust to identify users, the
+Monkeysphere can generate ssh-style `authorized_keys` quickly and
+easily:
+
+To update the Monkeysphere-generated `authorized_keys` file for user
+"bob", run:

 
        # monkeysphere-authentication update-users bob
 
 
        # monkeysphere-authentication update-users bob
 


@@ -100,19 +118,21 @@ the system, run the same command with no arguments:
        # monkeysphere-authentication update-users
 
 You probably want to set up a regularly scheduled job (e.g. with cron)
        # monkeysphere-authentication update-users
 
 You probably want to set up a regularly scheduled job (e.g. with cron)

-to take care of this automatically.
+to do this automatically.

 
 Update OpenSSH server AuthorizedKeysFile configuration
 ------------------------------------------------------
 
 
 Update OpenSSH server AuthorizedKeysFile configuration
 ------------------------------------------------------
 

-SSH must be configured to point to the monkeysphere generated
-`authorized_keys` file.  Add this line to `/etc/ssh/sshd_config`
-(again, making sure that no other AuthorizedKeysFile directive is left
-uncommented):
+Generating the `authorized_keys` files is not quite enough, because
+`sshd` needs to know where to find the generated keys.
+
+You can do this by adding the following line to
+`/etc/ssh/sshd_config`, commenting out any other `AuthorizedKeysFile`
+directives:

 
        AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 
 You'll need to restart `sshd` to have your changes take effect.  As
 
        AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
 
 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.
+with any change to `sshd_config`, if you're doing this remotely, be
+sure to retain an existing session to the machine while you test your
+changes so you don't get locked out if something went wrong.