summaryrefslogtreecommitdiff
path: root/website/getting-started-admin.mdwn
blob: 69f498a82cbfd6bdac41d69dc17e3c0e6e40c617 (plain)

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:

~/.config/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