Commit | Line | Data |
---|---|---|
b7cfede0 BK |
1 | Setting up a Debian OpenAFS Server |
2 | ||
3 | Introduction | |
4 | ||
5 | This document describes how to set up an OpenAFS server using the Debian | |
6 | packages. If you are not already familiar with the basic concepts of | |
7 | OpenAFS, you should review the documentation at: | |
8 | ||
9 | http://docs.openafs.org/ | |
10 | ||
11 | particularly the AFS Administrator's Guide. This documentation is | |
12 | somewhat out of date (it doesn't talk about how to use a Kerberos v5 KDC | |
13 | instead of the AFS kaserver, for example), but it's a good introduction | |
14 | to the basic concepts and servers you will need to run. | |
15 | ||
16 | The Debian OpenAFS packages follow the FHS and therefore use different | |
17 | paths than the standard AFS documentation or the paths that experienced | |
18 | AFS administrators may be used to. In the first column below are the | |
19 | traditional paths, and in the second column, the Debian paths: | |
20 | ||
21 | /usr/afs/etc /etc/openafs/server | |
22 | /usr/afs/local /var/lib/openafs/local | |
23 | /usr/afs/db /var/lib/openafs/db | |
24 | /usr/afs/logs /var/log/openafs | |
25 | /usr/afs/bin /usr/lib/openafs | |
26 | /usr/vice/etc /etc/openafs | |
27 | ||
28 | The AFS kaserver (a Kerberos v4 KDC) is not packaged for Debian. Any | |
29 | new OpenAFS installation should use Kerberos v5 for authentication in | |
30 | conjunction with either the tools packaged in the openafs-krb5 package | |
31 | or the Heimdal KDC. When setting up a new cell, you should therefore | |
32 | not set up a kaserver as described in the AFS Administrator's Guide, and | |
33 | you will need to follow a slightly different method of setting the cell | |
34 | key. | |
35 | ||
36 | Creating a New Cell | |
37 | ||
38 | For documentation on adding a server to an existing cell, see below. | |
39 | ||
40 | These instructions assume that you are using MIT Kerberos and the | |
41 | openafs-krb5 package. If you are using Heimdal instead, some of the | |
42 | steps will be slightly different (Heimdal can write the AFS KeyFile | |
43 | directly, for example, so you don't have to use asetkey). The | |
44 | afs-newcell and afs-rootvol scripts are the same, however. | |
45 | ||
46 | /usr/share/doc/openafs-dbserver/configuration-transcript.txt.gz has a | |
47 | transcript of the results of these directions, which you may want to | |
48 | follow along with as you do this. | |
49 | ||
50 | 1. If you do not already have a Kerberos KDC (Key Distribution Center, | |
51 | the daemon that handles Kerberos authentication) configured, do so. | |
52 | You can run the KDC on the same system as your OpenAFS db server, | |
53 | although if you plan on using Kerberos for other things, you may | |
54 | eventually want to use separate systems. If you do not have a | |
55 | Kerberos realm set up already, you can do so in Debian with: | |
56 | ||
57 | apt-get install krb5-admin-server | |
58 | krb5_newrealm | |
59 | ||
60 | This will install a KDC and kadmind server (the server that handles | |
61 | password changes and account creations) on the local system. Please | |
62 | be aware that the security of everything that uses Kerberos for | |
63 | authentication, including AFS, depends on the security of the KDC. | |
64 | ||
65 | The name of your Kerberos realm should, for various reasons, be in | |
66 | all uppercase and be a domain name that you control, although | |
67 | neither is technically required. | |
68 | ||
69 | 2. It is traditional (and recommended) in AFS (and for Kerberos) to | |
70 | give administrators two separate Kerberos principals, one regular | |
71 | principal to use for regular purposes and a separate admin principal | |
72 | to use for privileged actions. This is similar to the distinction | |
73 | between a regular user and the root user in Unix, except that | |
74 | everyone can have their own separate root identity. Kerberos | |
75 | recommends username/admin as the admin principal for username, and | |
76 | this will work for AFS as well. | |
77 | ||
78 | If you have not already created such an admin principal for yourself | |
79 | in your Kerberos realm, do so now (using kadmin.local on your KDC, | |
80 | unless you have a local method that you prefer). Also create a | |
81 | regular (non-admin) principal for yourself if you have not already; | |
82 | this is the identity that you'll use for regular operations, like | |
83 | storing files or reading mail. To do this with kadmin.local, run | |
84 | that program and then run the commands: | |
85 | ||
86 | addprinc username/admin | |
87 | addprinc username | |
88 | ||
89 | at the kadmin prompt. You'll be prompted for passwords for both | |
90 | accounts. | |
91 | ||
92 | If the KDC is not on the same system that the OpenAFS db server will | |
93 | be on, you will also need to give your admin principal the rights to | |
94 | download the afs keytab in /etc/krb5kdc/kadm5.acl by adding a lines | |
95 | like: | |
96 | ||
97 | username/admin@REALM * | |
98 | ||
99 | where REALM is your Kerberos realm and username/admin is the admin | |
100 | principal that you created. That line gives you full admin access | |
101 | to the Kerberos v5 realm. You can be more restrictive if you want; | |
102 | see the kadmind man page for the syntax. | |
103 | ||
104 | 3. Install the OpenAFS db server package on an appropriate system with: | |
105 | ||
106 | apt-get install openafs-dbserver openafs-krb5 | |
107 | ||
108 | The openafs-krb5 package will be used to create the AFS KeyFile. | |
109 | ||
110 | As part of this installation, you will need to configure | |
111 | openafs-client with the cell you are creating as the local cell name | |
112 | and the server on which you're working as the db server. This name | |
113 | is technically arbitrary but should, for various reasons, be a valid | |
114 | domain name that you control; unlike Kerberos realms, it should be | |
115 | in all lowercase. Enter the name of the local system when prompted | |
116 | for the names of your OpenAFS db servers. Don't start the client; | |
117 | that will happen below. For right now, say that you don't want it | |
118 | to start at boot. You can change that later with dpkg-reconfigure | |
119 | openafs-client. | |
120 | ||
121 | If you have already installed openafs-client and configured it for | |
122 | some other cell, you do need to configure it to point to your new | |
123 | cell for these instructions to work. Stop the AFS client on the | |
124 | system with service openafs-client stop and then run: | |
125 | ||
126 | dpkg-reconfigure openafs-client | |
127 | ||
128 | pointing it to the new cell you're about to create instead. | |
129 | Remember, your cell name should be in lowercase. If you have had to | |
130 | do this several times, double-check /etc/openafs/CellServDB when | |
131 | you're done and make sure that there is only one entry for your new | |
132 | cell at the top of that file and that it lists the correct IP | |
133 | address for your new db server. | |
134 | ||
135 | In order to complete the AFS installation, you will also need a | |
136 | working AFS client installed on that system, which means that you | |
137 | need to install an OpenAFS kernel module. Please see: | |
138 | ||
139 | /usr/share/doc/openafs-client/README.modules | |
140 | ||
141 | for information on how to do that. | |
142 | ||
143 | 4. Create an AFS principal in Kerberos. This is the AFS service | |
144 | principal, used by clients to authenticate to AFS and for AFS | |
145 | servers to authenticate to each other. It *must* be a DES key; AFS | |
146 | does not support any other encryption type. Run kadmin.local on | |
147 | your KDC and then, at the kadmin.local prompt, run: | |
148 | ||
149 | addprinc -randkey -e des-cbc-crc:v4 afs | |
150 | ||
151 | If your Kerberos realm name does not match your AFS cell name (if, | |
152 | for instance, you have one Kerberos realm with multiple AFS cells), | |
153 | use "afs/cell.name" as the name of the principal above instead of | |
154 | just "afs", where cell.name is the name of your new AFS cell. | |
155 | ||
156 | 5. On the db server, download this key into a keytab. If this is the | |
157 | same system as the KDC, you can use kadmin.local again. If not, you | |
158 | should use kadmin (make sure that krb5-user is installed), and you | |
159 | may need to pass -p username/admin to kadmin to tell it what | |
160 | principal to authenticate as. Whichever way you get into kadmin, | |
161 | run: | |
162 | ||
163 | ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs | |
164 | ||
165 | (or afs/cell.name if you used that instead). In the message that | |
166 | results, note the kvno number reported, since you'll need it later | |
167 | (it will normally be 3). | |
168 | ||
169 | Don't forget the -e des-cbc-crc:v4 to force the afs key to be DES. | |
170 | You can verify this with: | |
171 | ||
172 | getprinc afs | |
173 | ||
174 | and checking to be sure that the only key listed is a DES key. If | |
175 | there are multiple keys listed, delprinc the afs principal, delete | |
176 | the /tmp/afs.keytab file, and then start over with addprinc, making | |
177 | sure not to forget the -e option. | |
178 | ||
179 | 6. Create the AFS KeyFile with: | |
180 | ||
181 | asetkey add <kvno> /tmp/afs.keytab afs | |
182 | ||
183 | (or afs/cell.name if you used that instead). <kvno> should be | |
184 | replaced by the kvno number reported by kadmin. This tells AFS the | |
185 | Kerberos key that it should use, making it match the key in the | |
186 | Kerberos KDC. | |
187 | ||
188 | 7. If the name of your Kerberos realm does not match the name of your | |
189 | AFS cell, tell AFS what Kerberos realm to use with: | |
190 | ||
191 | echo REALM > /etc/openafs/server/krb.conf | |
192 | ||
193 | where REALM is the name of your Kerberos realm. If your AFS cell | |
194 | and Kerberos realm have the same name, this is unnecessary. | |
195 | ||
196 | 8. Create some space to use for AFS volumes. You can set up a separate | |
197 | AFS file server on a different system from the Kerberos KDC and AFS | |
198 | db server, and for a larger cell you will want to do so, but when | |
199 | getting started you can make the db server a file server as well. | |
200 | For a production cell, you will want to create a separate partition | |
201 | devoted to AFS and mount it as /vicepa (and may want to make | |
202 | multiple partitions mounted as /vicepb, /vicepc, etc.), but for | |
203 | testing purposes, you can use the commands below to create a | |
204 | zero-filled file, create a file system in it, and then mount it: | |
205 | ||
206 | dd if=/dev/zero of=/var/lib/openafs/vicepa bs=1024k count=32 | |
207 | mke2fs /var/lib/openafs/vicepa | |
208 | mkdir /vicepa | |
209 | mount -oloop /var/lib/openafs/vicepa /vicepa | |
210 | ||
211 | mke2fs will ask you if you're sure you want to create a file system | |
212 | on a non-block device; say yes. | |
213 | ||
214 | 9. Run afs-newcell. This will prompt you to be sure that the above | |
215 | steps have been complete and will ask you for the Kerberos principal | |
216 | to use for AFS administrative access. You should use the | |
217 | username/admin principal discussed above. afs-newcell sets up the | |
218 | initial protection database (which stores users and groups), | |
219 | configures the AFS database and file server daemons, and creates the | |
220 | root volume for AFS clients. | |
221 | ||
222 | At the completion of this step, you should see bosserver and several | |
223 | other AFS server processes running, and you should be able to see | |
224 | the status of those processes with: | |
225 | ||
226 | bos status localhost -local | |
227 | ||
228 | bosserver is a master server that starts and monitors all the | |
229 | individual AFS servers, and bos is the program used to send it | |
230 | commands. | |
231 | ||
232 | Now, you should be able to run: | |
233 | ||
234 | kinit username/admin@REALM | |
235 | aklog cell.name -k REALM | |
236 | ||
237 | where username/admin is the admin principal discussed above, REALM | |
238 | is the name of your Kerberos realm, and cell.name is the name of | |
239 | your AFS cell. This will obtain Kerberos tickets and AFS tokens in | |
240 | your Kerberos realm and new AFS cell. You should be able to see | |
241 | your AFS tokens by running: | |
242 | ||
243 | tokens | |
244 | ||
245 | Finally, you should be able to see the status of the AFS server | |
246 | processes with: | |
247 | ||
248 | bos status <hostname> | |
249 | ||
250 | where <hostname> is the hostname of the local system, once you've | |
251 | done the above. This tests authenticated bos access as your admin | |
252 | principal (rather than using the local KeyFile to authenticate). | |
253 | ||
254 | 10. Run afs-rootvol. This creates the basic AFS volume structure for | |
255 | your new cell, including the top-level volume, the mount point for | |
256 | your cell in the AFS root volume, and the mount points for all known | |
257 | public cells. It will prompt you to be sure that the above steps | |
258 | are complete and then will ask you what file server and partition to | |
259 | create the volume on. If you were following the above instructions, | |
260 | use the local hostname and "a" as the partition (without the | |
261 | quotes), which will use /vicepa. | |
262 | ||
263 | After this command completes, you should be able to /bin/ls /afs and | |
264 | see your local cell (and, if you aren't using dynroot, mount points | |
265 | for several other cells). Note that if you're not using fakestat, | |
266 | run /bin/ls rather than just ls to be sure that ls isn't aliased to | |
267 | ls -F, ls --color, or some other option that would stat each file in | |
268 | /afs, since this would require contacting lots of foreign cells and | |
269 | could take a very long time. | |
270 | ||
271 | You should now be able to cd to /afs/cell.name where cell.name is | |
272 | the AFS cell name that you used. Currently, there isn't anything in | |
273 | your cell except two volumes, user and service, created by | |
274 | afs-rootvol. To make modifications, cd to /afs/.cell.name (note the | |
275 | leading period) and make changes there. To make those changes show | |
276 | up at /afs/cell.name, run vos release root.cell. For more details | |
277 | on what you can do now, see the AFS Administrator's Reference. | |
278 | ||
279 | 11. While this is optional, you probably want to add AFSDB records to | |
280 | DNS for your new AFS cell. These special DNS records let AFS | |
281 | clients find the db servers for your cell without requiring local | |
282 | configuration. To do this, create a DNS record like: | |
283 | ||
284 | <cell>. 3600 IN AFSDB 1 <server>. | |
285 | ||
286 | where <cell> is the name of your AFS cell and <server> is the name | |
287 | of your db server. Note the trailing periods to prevent the DNS | |
288 | server from appending the origin. You can, of course, choose what | |
289 | you prefer for the lifetime. The 1 is not a priority; it's a | |
290 | special indicator saying that this record is for an AFS database | |
291 | server. | |
292 | ||
293 | If you have multiple db servers (see below for adding new ones), you | |
294 | should create multiple records of this type, one per db server. | |
295 | ||
296 | Congratulations! You now have an AFS cell. If any of the above steps | |
297 | failed, please check the steps carefully and make sure that you've done | |
298 | them all in order. If that doesn't reveal the cause of the problem, | |
299 | please feel free to submit a bug report with reportbug. Include as many | |
300 | details as possible on exactly what you typed and exactly what you saw | |
301 | as a result, particularly any error messages. | |
302 | ||
303 | Adding Additional Servers | |
304 | ||
305 | If you decide one server is not enough, or if you're adding a server to | |
306 | an existing cell, here is roughly what you should do: | |
307 | ||
308 | 1. Copy securely (using scp, encrypted Kerberos rcp, or some other | |
309 | secure method) all of /etc/openafs/server to the new server. | |
310 | ||
311 | 2. Install the openafs-fileserver package on the new server. | |
312 | ||
313 | 3. If the machine is to be a file server, create an fs instance using | |
314 | bos create: | |
315 | ||
316 | bos create <host> dafs dafs -cmd /usr/lib/openafs/dafileserver \ | |
317 | -cmd /usr/lib/openafs/davolserver \ | |
318 | -cmd /usr/lib/openafs/salvageserver \ | |
319 | -cmd /usr/lib/openafs/dasalvager -localauth | |
320 | ||
321 | For a file server, this is all you have to do. The above uses the | |
322 | default fileserver options, however, which are not particularly | |
323 | well-tuned for modern systems. afs-newcell uses the following | |
324 | parameters from Harald Barth: | |
325 | ||
326 | -p 23 -busyat 600 -rxpck 400 -s 1200 -l 1200 -cb 65535 | |
327 | -b 240 -vc 1200 | |
328 | ||
329 | If you want to add any additional fileserver options, enclose | |
330 | /usr/lib/openafs/dafileserver and the following options in double | |
331 | quotes when giving the bos create command. | |
332 | ||
333 | This creates a demand-attach fileserver, which is recommended for | |
334 | new installations. You can also create a regular fileserver if you | |
335 | prefer. See the bos_create(8) man page for more information. | |
336 | ||
337 | 4. For database servers, also install openafs-dbserver and then use bos | |
338 | addhost to add the new server to /etc/openafs/server/CellServDB: | |
339 | ||
340 | bos addhost <server> <new-server> | |
341 | ||
342 | for each db server <server> in your cell (including the new one). | |
343 | Then, restart the ptserver and vlserver instances on each of your | |
344 | existing servers with: | |
345 | ||
346 | bos restart <server> ptserver | |
347 | bos restart <server> vlserver | |
348 | ||
349 | It's best to wait a few seconds after doing this for each server | |
350 | before doing the next server so that voting finishes and you never | |
351 | lose a quorum. | |
352 | ||
353 | Only after ptserver and vlserver have been restarted on each of your | |
354 | existing servers, create ptserver and vlserver instances on the new | |
355 | server: | |
356 | ||
357 | bos create <host> ptserver simple /usr/lib/openafs/ptserver \ | |
358 | -localauth | |
359 | bos create <host> vlserver simple /usr/lib/openafs/vlserver \ | |
360 | -localauth | |
361 | ||
362 | The existing servers should then propagate the database to the new | |
363 | server. If you are using buserver, you will need to do the same | |
364 | thing for it as with ptserver and vlserver. | |
365 | ||
366 | Note that you do not need to run a file server on a db server if you | |
367 | don't want to (and larger sites probably will not want to), but you | |
368 | always need to have the openafs-fileserver package installed on db | |
369 | servers. It contains the bosserver binary and some of the shared | |
370 | infrastructure. | |
371 | ||
372 | 5. If you added a new db server, configure your clients to use it. If | |
373 | you are using AFSDB records in DNS, you can just add a new record | |
374 | (see point 10 in the instructions for creating a new cell). | |
375 | Otherwise, clients will need to have the new server IP address added | |
376 | to their /etc/openafs/CellServDB file (or /usr/vice/etc/CellServDB | |
377 | for non-Debian clients using the standard AFS paths), and the client | |
378 | will have to be restarted before it will know about the new db | |
379 | server. | |
380 | ||
381 | The standard rule of thumb is that all of your database servers and file | |
382 | servers should ideally be running the same version of OpenAFS. However, | |
383 | in practice OpenAFS is fairly good at backward compatibility and you can | |
384 | generally mix and match different versions. Be careful, though, to | |
385 | ensure that all of your database servers are built the same when it | |
386 | comes to options like --enable-supergroups (enabled in the Debian | |
387 | packages). | |
388 | ||
389 | Upgrades | |
390 | ||
391 | Currently, during an upgrade of the openafs-fileserver package, all | |
392 | services will be stopped and restarted. If openafs-dbserver is upgraded | |
393 | without upgrading openafs-fileserver, those server binaries will not be | |
394 | stopped and restarted; that restart will have to be done by hand. | |
395 | ||
396 | It is possible that future versions of this package will install for | |
397 | example /usr/lib/openafs/fileserver.package instead of | |
398 | /usr/lib/openafs/fileserver and then create links to the actual binaries | |
399 | in postinst. Upgrades would then not replace the old binaries, but | |
400 | instead a script will be provided to roll the links forward to the new | |
401 | versions. The intent is that people could install the new package on | |
402 | all their servers and then quickly move the links before restarting the | |
403 | bosserver. This has not yet been implemented. |