doc/README.admin

   1 Monkeysphere Server Administrator README
   2 ========================================
   3
   4 FIXME: distinguish between publishing a new monkeysphere-enabled host
   5 key and accepting user identification via the web-of-trust.
   6
   7
   8 server service publication
   9 --------------------------
  10 To publish a server host key:
  11
  12                 # monkeysphere-server gen-key
  13                 # monkeysphere-server publish-key
  14
  15 This will generate the key for server with the service URI
  16 (ssh://server.hostname).  The server admin should now sign the server
  17 key so that people in the admin's web of trust can authenticate the
  18 server without manual host key checking:
  19
  20                 $ gpg --search ='ssh://server.hostname'
  21                 $ gpg --sign-key ='ssh://server.hostname'
  22
  23
  24 Update OpenSSH configuration files
  25 ----------------------------------
  26
  27 To use the newly-generated host key for ssh connections, put the
  28 following line in /etc/ssh/sshd_config (be sure to remove references
  29 to any other key):
  30
  31                 HostKey /var/lib/monkeysphere/ssh_host_rsa_key
  32
  33 FIXME: should we just suggest symlinks in the filesystem here instead?
  34
  35 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.
  36
  37 To enable users to use the monkeysphere to authenticate against the
  38 web-of-trust, add this line to /etc/ssh/sshd_config (again, making
  39 sure that no other AuthorizedKeysFile directive exists):
  40
  41                 AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
  42
  43
  44 MonkeySphere authorized_keys maintenance
  45 ----------------------------------------
  46
  47 A system can maintain monkeysphere authorized_keys files for it's
  48 users.
  49
  50 For each user account on the server, the userids of people authorized
  51 to log into that account would be placed in:
  52
  53                 ~/.config/monkeysphere/authorized_user_ids
  54
  55 However, in order for users to become authenticated, the server must
  56 determine that the user keys have "full" validity.  This means that
  57 the server must fully trust at least one person whose signature on the
  58 connecting user's key would validate the user.  This would generally be
  59 the server admin.  If the server admin's keyid is XXXXXXXX, then on
  60 the server run:
  61
  62                 # monkeysphere-server add-identity-certifier XXXXXXXX
  63
  64 To update the monkeysphere authorized_keys file for user "bob", the
  65 system would then run the following:
  66
  67                 # monkeysphere-server update-users bob
  68
  69 To update the monkeysphere authorized_keys file for all users on the
  70 the system, run the same command with no arguments:
  71
  72                 # monkeysphere-server update-users
  73
  74 You probably want to set up a regularly scheduled job (e.g. with cron)
  75 to take care of this regularly.
  76
  77 FIXME: document other likely problems and troubleshooting techniques