preparing for stupid brown paper bag 0.23.1 release.
[monkeysphere.git] / website / getting-started-admin.mdwn
1 Monkeysphere Server Administrator README
2 ========================================
3
4         Note: This documentation is for Monkeysphere version 0.23 or later.
5         If you are running a version prior to 0.23, we recommend that you upgrade.
6
7 As the administrator of an SSH server, you can take advantage of the
8 Monkeysphere in two ways:
9
10 1. you can publish the host key of your machine to the Web of Trust
11 (WoT) so that your users can automatically verify it, and
12
13 2. you can set up your machine to automatically identify connecting
14 users by their presence in the OpenPGP Web of Trust.
15
16 These two pieces are independent: you can do one without the other.
17
18 Monkeysphere for host verification (monkeysphere-host)
19 ======================================================
20
21 Server host key publication
22 ---------------------------
23
24 To begin, you must first import an ssh host key.  This assumes that
25 you have the ssh server installed, and that you have generated a host
26 RSA key.  Once that has been done, import the key:
27
28         # monkeysphere-host import-key /etc/ssh/ssh_host_rsa_key server.example.net
29
30 This will generate an OpenPGP certificate for the server.  The primary
31 user ID for this certificate will be the ssh service URI for the host,
32 (eg. `ssh://server.example.net`).  Remember that the name you provide
33 here should probably be a fully qualified domain name for the host in
34 order for your users to find it.
35
36 Now you can display information about the host key's certificate with
37 the 'show-key' command:
38
39         # monkeysphere-host show-key
40
41 Once the host key's certificate has been generated, you'll probably
42 want to publish it to the public keyservers which distribute the Web
43 of Trust:
44
45         # monkeysphere-host publish-key
46
47 But anyone could publish a simple self-signed certificate to the WoT
48 with any name attached.  Your users should be able to tell that
49 someone they know and trust with the machine (e.g. *you*, the
50 administrator) has verified that this particular key is indeed the
51 correct key.  So your next step is to sign the host's key with your
52 own OpenPGP key.
53
54 On your (the admin's) local machine retrieve the host key (it may take
55 several minutes for the key to propagate across the keyserver
56 network), and sign it:
57
58         $ gpg --search '=ssh://server.example.net'
59         $ gpg --sign-key '=ssh://server.example.net'
60
61 Make sure you compare the fingerprint of the retrieved certificate
62 with the output from the 'show-key' command above!
63
64 Finally, publish your signatures back to the keyservers, so that your
65 users can automatically verify your machine when they connect:
66
67         $ gpg --send-key '=ssh://server.example.net'
68
69 See http://web.monkeysphere.info/signing-host-keys/ for more info
70 signing host keys.
71
72 Monkeysphere for user authentication (monkeysphere-authentication)
73 ==================================================================
74
75 A host can maintain ssh-style `authorized_keys` files automatically
76 for its users with the Monkeysphere.  This frees you (the
77 administrator) from the task of manually checking/placing SSH keys,
78 and enables users to do relatively painless key transitions, and to
79 quickly and universally revoke access if they find that their ssh key
80 has become compromised.
81
82 You simply tell the system what *person* (identified by her OpenPGP
83 User ID) should have access to an account, the Monkeysphere takes care
84 of generating the proper `authorized_keys` file and keeping it
85 up-to-date, and `sshd` reads the generated `authorized_keys` files
86 directly.
87
88 Monkeysphere authorized_keys maintenance
89 ----------------------------------------
90
91 For each user account on the server, the userids of people authorized
92 to log into that account would be placed in:
93
94         ~/.monkeysphere/authorized_user_ids
95
96 The server will use the Monkeysphere to look up matching OpenPGP
97 certificates, validate them, and generate an `authorized_keys` file.
98
99 To validate the OpenPGP certificates, the server needs to know who it
100 can trust to correctly identify users.  The individuals trusted to
101 identify users like this are known in the Monkeysphere as "Identity
102 Certifiers".  One obvious choice is to trust *you*, the administrator,
103 to be an Identity Certifier.  If your OpenPGP keyid is `$GPGID`, then
104 run the following command on the server:
105
106         # monkeysphere-authentication add-identity-certifier $GPGID
107
108 You'll probably only set up Identity Certifiers when you set up the
109 machine.  After that, you'll only need to add or remove Identity
110 Certifiers when the roster of admins on the machine changes, or when
111 one of the admins switches OpenPGP keys.
112
113 Now that the server knows who to trust to identify users, the
114 Monkeysphere can generate ssh-style `authorized_keys` quickly and
115 easily:
116
117 To update the Monkeysphere-generated `authorized_keys` file for user
118 "bob", run:
119
120         # monkeysphere-authentication update-users bob
121
122 To update the monkeysphere `authorized_keys` file for all users on the
123 the system, run the same command with no arguments:
124
125         # monkeysphere-authentication update-users
126
127 You probably want to set up a regularly scheduled job (e.g. with cron)
128 to do this automatically.
129
130 Update OpenSSH server AuthorizedKeysFile configuration
131 ------------------------------------------------------
132
133 Generating the `authorized_keys` files is not quite enough, because
134 `sshd` needs to know where to find the generated keys.
135
136 You can do this by adding the following line to
137 `/etc/ssh/sshd_config`, commenting out any other `AuthorizedKeysFile`
138 directives:
139
140         AuthorizedKeysFile /var/lib/monkeysphere/authorized_keys/%u
141
142 You'll need to restart `sshd` to have your changes take effect.  As
143 with any change to `sshd_config`, if you're doing this remotely, be
144 sure to retain an existing session to the machine while you test your
145 changes so you don't get locked out if something went wrong.