website/getting-started-admin.mdwn

   1 Monkeysphere Server Administrator README
   2 ========================================
   3
   4 As the administrator of an SSH server, you can take advantage of the
   5 monkeysphere in two ways: you can publish the host key of your machine
   6 so that your users can have it automatically verified, and you can set
   7 up your machine to automatically identify connecting users by their
   8 presence in the OpenPGP web of trust.
   9
  10 Server host key publication
  11 ---------------------------
  12 To generate and publish a server host key:
  13
  14         # monkeysphere-server gen-key
  15         # monkeysphere-server publish-key
  16
  17 This will generate the key for server with the service URI
  18 (`ssh://server.example.net`).  The server admin should now sign the
  19 server key so that people in the admin's web of trust can identify the
  20 server without manual host key checking:
  21
  22         $ gpg --search ='ssh://server.example.net'
  23         $ gpg --sign-key ='ssh://server.example.net'
  24
  25
  26 Update OpenSSH configuration files
  27 ----------------------------------
  28
  29 To use the newly-generated host key for ssh connections, put the
  30 following line in `/etc/ssh/sshd_config` (be sure to remove references
  31 to any other keys):
  32
  33         HostKey /var/lib/monkeysphere/ssh_host_rsa_key
  34
  35 FIXME: should we just suggest symlinks in the filesystem here instead?
  36
  37 FIXME: What about DSA host keys?  The SSH RFC seems to require implementations support DSA, though OpenSSH will work without a DSA host key.
  38
  39 To enable users to use the monkeysphere to authenticate using the
  40 OpenPGP web of trust, add this line to `/etc/ssh/sshd_config` (again,
  41 making sure that no other AuthorizedKeysFile directive exists):
  42
  43         AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
  44
  45 And then read the section below about how to ensure these files are
  46 maintained.  You'll need to restart `sshd` to have your changes take
  47 effect.  As with any change to `sshd_config`, be sure to retain an
  48 existing session to the machine while you test your changes so you
  49 don't get locked out.
  50
  51 Monkeysphere authorized_keys maintenance
  52 ----------------------------------------
  53
  54 A host can maintain ssh authorized_keys files automatically for its
  55 users with the Monkeysphere.
  56
  57 For each user account on the server, the userids of people authorized
  58 to log into that account would be placed in:
  59
  60         ~/.config/monkeysphere/authorized_user_ids
  61
  62 However, in order for users to become authenticated, the server must
  63 determine that the user IDs on their keys have "full" validity.  This
  64 means that the server must fully trust at least one person whose
  65 signature on the connecting user's key would validate the relevant
  66 user ID.  The individuals trusted to identify users like this are
  67 known in the Monkeysphere as "Identity Certifiers".  In a simple
  68 scenario, the host's administrator would be trusted identity certifer.
  69 If the admin's OpenPGP keyid is `$GPGID`, then on the server run:
  70
  71         # monkeysphere-server add-identity-certifier $GPGID
  72
  73 To update the monkeysphere authorized_keys file for user "bob" using
  74 the current set of identity certifiers, run:
  75
  76         # monkeysphere-server update-users bob
  77
  78 To update the monkeysphere authorized_keys file for all users on the
  79 the system, run the same command with no arguments:
  80
  81         # monkeysphere-server update-users
  82
  83 You probably want to set up a regularly scheduled job (e.g. with cron)
  84 to take care of this automatically.
  85
  86 FIXME: document other likely problems and troubleshooting techniques