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