doc/README.admin



Monkeysphere Server Administrator README
========================================

FIXME: distinguish between publishing a new monkeysphere-enabled host
key and accepting user identification via the web-of-trust.

server service publication
--------------------------
To publish a server host key:

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

This will generate the key for server with the service URI
(ssh://server.hostname).  The server admin should now sign the server
key so that people in the admin's web of trust can authenticate the
server without manual host key checking:

$ gpg --search ='ssh://server.hostname'
$ gpg --sign-key ='ssh://server.hostname'


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 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 that DSA be available, though OpenSSH will work without a DSA host key.

To enable users to use the monkeysphere to authenticate against the
web-of-trust, add this line to /etc/ssh/sshd_config (again, making
sure that no other AuthorizedKeysFile directive exists):

AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u


MonkeySphere authorized_keys maintenance
----------------------------------------

A system can maintain monkeysphere authorized_keys files for it's
users.

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

However, in order for users to become authenticated, the server must
determine that the user 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 user.  This would generally be
the server admin.  If the server admin's keyid is XXXXXXXX, then on
the server run:

# monkeysphere-server add-identity-certifier XXXXXXXX

To update the monkeysphere authorized_keys file for user "bob", the
system would then run the following:

# monkeysphere-server update-users bob

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

You probably want to set up a regularly scheduled job (e.g. with cron)
to take care of this regularly.

FIXME: document other likely problems and troubleshooting techniques