Merge commit 'dkg/master'

[monkeysphere.git] / website / getting-started-admin.mdwn

diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn
index 69f498a82cbfd6bdac41d69dc17e3c0e6e40c617..5c7203ddda6d8afc746bd34e61f6c05cdb680222 100644 (file)
--- a/website/getting-started-admin.mdwn
+++ b/website/getting-started-admin.mdwn
@@ -2,62 +2,110 @@ 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: 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.
+monkeysphere in two ways:
+
+1. you can publish the host key of your machine so that your users can
+have it automatically verified, and
+
+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.
+
+
+Monkeysphere for host verification
+==================================

 
 Server host key publication
 ---------------------------
 
 Server host key publication
 ---------------------------

-To generate and publish a server host key:
+
+To begin, you must first generate a server host key:

 
        # monkeysphere-server gen-key
 
        # monkeysphere-server gen-key

-       # monkeysphere-server publish-key

 
 This will generate the key for server with the service URI
 
 This will generate the key for server with the service URI

-(`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:
+(`ssh://server.example.net`).  Output the new key information with the
+'show-key' command:
+
+       # monkeysphere-server show-key
+
+Once the key has been generated, it needs to be publish to the Web of
+Trust:
+
+       # monkeysphere-server 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'
-       $ gpg --sign-key ='ssh://server.example.net'
+       $ gpg --search '=ssh://server.example.net'

 
 

+Now sign the server key:
+
+       $ 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:
+
+       $ gpg --send-key '=ssh://server.example.net'

 
 Update OpenSSH configuration files
 ----------------------------------
 
 To use the newly-generated host key for ssh connections, put the
 
 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 keys):
+following line in `/etc/ssh/sshd_config` (be sure to comment out or
+remove any other HostKey references):

 
        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
+implementations support DSA, though OpenSSH will work without a DSA
+host key.
+
+
+Monkeysphere for user 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.

 
 

-FIXME: What about DSA host keys?  The SSH RFC seems to require implementations support DSA, though OpenSSH will work without a DSA host key.
+Before this can happen, the host must first have a host key to use for
+user key verification.  If you have not already generated a host key
+(as in the host verification instructions above), generate one now:

 
 

-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):
+       # monkeysphere-server gen-key
+
+Update OpenSSH configuration files
+----------------------------------
+
+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):

 
        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.
+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 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:
 
 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
+       ~/.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
 
 However, in order for users to become authenticated, the server must
 determine that the user IDs on their keys have "full" validity.  This


@@ -70,12 +118,12 @@ If the admin's OpenPGP keyid is `$GPGID`, then on the server run:
 
        # monkeysphere-server add-identity-certifier $GPGID
 
 
        # monkeysphere-server add-identity-certifier $GPGID
 

-To update the monkeysphere authorized_keys file for user "bob" using
+To update the monkeysphere `authorized_keys` file for user "bob" using

 the current set of identity certifiers, run:
 
        # monkeysphere-server update-users bob
 
 the current set of identity certifiers, run:
 
        # monkeysphere-server update-users bob
 

-To update the monkeysphere authorized_keys file for all users on the
+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
 the system, run the same command with no arguments:
 
        # monkeysphere-server update-users