X-Git-Url: https://codewiz.org/gitweb?a=blobdiff_plain;f=website%2Fgetting-started-admin.mdwn;h=1c373acffa1883d8de5f1ec351fa8dd33bb84697;hb=647a0fc70e28d641d914f183489d815d4feb7e2b;hp=e97c7944e0ea99af7cbba8bac2ed7229a9c2452d;hpb=8bba6f27dd299180bd55d9f27b8d1b219c356095;p=monkeysphere.git diff --git a/website/getting-started-admin.mdwn b/website/getting-started-admin.mdwn index e97c794..1c373ac 100644 --- a/website/getting-started-admin.mdwn +++ b/website/getting-started-admin.mdwn @@ -1,77 +1,88 @@ Monkeysphere Server Administrator README ======================================== -FIXME: distinguish between publishing a new monkeysphere-enabled host -key and accepting user identification via the web-of-trust. +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 service publication --------------------------- -To publish a server host key: +Server host key publication +--------------------------- +To generate and publish a server host key: - # monkeysphere-server gen-key - # monkeysphere-server publish-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 +(`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.hostname' - $ gpg --sign-key ='ssh://server.hostname' + $ 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 key): +following line in `/etc/ssh/sshd_config` (be sure to remove references +to any other keys): - HostKey /var/lib/monkeysphere/ssh_host_rsa_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. +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 against the -web-of-trust, add this line to /etc/ssh/sshd_config (again, making -sure that no other AuthorizedKeysFile directive exists): +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 + 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 + +Monkeysphere authorized_keys maintenance ---------------------------------------- -A system can maintain monkeysphere authorized_keys files for it's -users. +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 + ~/.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: +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 XXXXXXXX + # monkeysphere-server add-identity-certifier $GPGID -To update the monkeysphere authorized_keys file for user "bob", the -system would then run the following: +To update the monkeysphere authorized_keys file for user "bob" using +the current set of identity certifiers, run: - # monkeysphere-server update-users bob + # 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 + # monkeysphere-server update-users You probably want to set up a regularly scheduled job (e.g. with cron) -to take care of this regularly. +to take care of this automatically. FIXME: document other likely problems and troubleshooting techniques