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

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.


Server host key publication
---------------------------
To generate and 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.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:

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


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):

	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.

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):

	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.


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:

	~/.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
means that the server must fully trust at least one person whose
signature on the connecting user's key would validate the relevant
user ID.  The individuals trusted to identify users like this are
known in the Monkeysphere as "Identity Certifiers".  In a simple
scenario, the host's administrator would be trusted identity certifer.
If the admin's OpenPGP keyid is `$GPGID`, then on the server run:

	# monkeysphere-server add-identity-certifier $GPGID

To update the monkeysphere authorized_keys file for user "bob" using
the current set of identity certifiers, run:

	# 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 automatically.

FIXME: document other likely problems and troubleshooting techniques