asetkey list skips rxkad_krb5 keys
[openafs-wiki.git] / InstallingOpenAFSonRHEL.mdwn
1
2 This is a step-by-step guide to installing OpenAFS and setting up an AFS cell
3 on RedHat Enterprise Linux, Fedora, or CentOS.  This guide is current as of
4 OpenAFS version 1.6.9 on CentOS 6.5.
5
6 This document is based on [[Steven Pelley's guide for installing OpenAFS 1.4.x on Fedora|FedoraAFSInstall]].
7
8 [[!toc levels=1]]
9
10 ## Differences from older guides
11
12 ### Non-DES Kerberos service key
13
14 As of OpenAFS version 1.6.5, non-DES encryption keys are supported and should
15 be used for the long term AFS service key. The `asetkey` program is no longer
16 needed to import the Kerberos service key. The OpenAFS servers read a Kerberos
17 keytab file directly. Special changes to the Kerberos configuration files to
18 allow weak crypto and weak enctypes are no longer needed.
19
20 The OpenAFS `kaserver` should not be used in new installations. This guide
21 shows how to install MIT Kerberos.
22
23 ### -noauth server mode
24
25 Older versions of OpenAFS required the `-noauth` flag to be used when first
26 setting up the system. This entailed starting the `bosserver` in `-noauth` mode
27 to disable authorization during the initial setup.  Modern versions of OpenAFS
28 can be installed without the `-noauth`, making the initial setup more secure
29 and without the need to restart the server processes.
30
31 ### -dynroot client mode
32
33 This guide assumes the OpenAFS cache manager is started with `-dynroot` mode
34 enabled, which is the default these days.  This guide shows how to create the
35 initial top level AFS volumes when the cache manager is in `-dynroot` mode.
36
37 ### Recommended options
38
39 This guide recommends using the `bosserver` restricted mode to improve security.
40
41 The default options for the fileserver are rather out of date for modern
42 hardware. This guide provides some examples of more suitable options for
43 the fileserver.
44
45 This guide shows how to setup the Demand Attach Fileserver.
46
47 ## Naming conventions
48
49 When setting up an AFS cell on the internet, the convention is to user your
50 internet domain name for your Kerberos realm and AFS cell name.  The Kerberos
51 realm name should be uppercase and the AFS cell name should be lowercase.
52
53 Note, it is possible to create a AFS cell with a different name than the
54 Kerberos realm (or even use a single Kerberos realm in multiple cells).  See
55 the documentation for the OpenAFS `krb.conf` server configuration file for
56 details on mapping realms to cell names.
57
58 ## Server setup
59
60 A minimal OS install is sufficient.
61
62 For a simple installation, you may use a single server to host the Kerberos
63 KDC, OpenAFS database server, and OpenAFS fileserver.  For a production
64 environment, it is recommended that the Kerberos KDC be deployed on a
65 dedicated, secure server, the OpenAFS database servers be deployed on three
66 separate machines, and multiple file servers deployed as needed.
67
68 ### Disk Partitions
69
70 An important thing to keep in mind is that you'll need at least one partition
71 on the file server to store volumes for AFS.  This will be mounted at
72 `/vicepa`. If you have multiple partitions they can be mounted at `/vicepb`,
73 `/vicepc`, etc.  The file server uses file-based storage (not block based).
74 `ext3`, `ext4`, and `xfs` are commonly used filesystems on the vicep
75 partitions.
76
77 Clients should have a dedicated partition for the file cache. The cache
78 partition is traditionally mounted at `/usr/vice/cache`.
79
80 ### Networking
81
82 DNS should be working correctly for forward and reverse name lookups before you
83 begin the Kerberos and OpenAFS installation.  `bind` can be installed if you
84 need a local DNS server.  Use `system-config-bind` to add a zone and entries.
85
86 Servers need at least one IPv4 interface that is accessible by the AFS clients.
87 IPv6 interfaces are not yet supported.
88
89 ### Time keeping
90
91 Kerberos, and therefore OpenAFS, requires good clock synchronization between
92 clients and servers. Be sure to install and configure `ntp` and verify the
93 clocks are automatically kept in sync.
94
95     # yum install -y ntp
96     # service ntpd start
97     # chkconfig ntpd on
98
99 ### Firewall
100
101 The default firewall settings on RHEL will block the network ports used by
102 Kerberos and OpenAFS.  You will need to adjust the firewall rules on the
103 servers to allow traffic on these ports.
104
105 On the Kerberos server, open udp ports 88 and 646:
106
107     # iptables -A INPUT -p udp --dport 88 -j ACCEPT
108     # iptables -A INPUT -p udp --dport 646 -j ACCEPT
109     # service iptables save
110
111 On the OpenAFS database servers, open the udp ports 7002, 7003, and 7007:
112
113     # iptables -A INPUT -p udp --dport 7002 -j ACCEPT
114     # iptables -A INPUT -p udp --dport 7003 -j ACCEPT
115     # iptables -A INPUT -p udp --dport 7007 -j ACCEPT
116     # service iptables save
117
118 On the OpenAFS file servers, open the udp ports 7000, 7005, and 7007:
119
120     # iptables -A INPUT -p udp --dport 7000 -j ACCEPT
121     # iptables -A INPUT -p udp --dport 7005 -j ACCEPT
122     # iptables -A INPUT -p udp --dport 7007 -j ACCEPT
123     # service iptables save
124
125 OpenAFS clients use udp port 7001. Open udp port 7001 on any system that will
126 have the OpenAFS client installed.
127
128     # iptables -A INPUT -p udp --dport 7001 -j ACCEPT
129     # service iptables save
130
131 ### SELinux
132
133 Ideally, SELinux should be kept in enforcing mode. SELinux may be set to
134 enforcing for the OpenAFS client, but unfortunately, for the servers, there are
135 still several [issues][1] remaining before the servers can run out the box with
136 SELinux in enforcing mode.
137
138 For test installations, SELinux can be set into permissive mode, which will
139 print warnings instead of blocking:
140
141     # setenforce 0
142     # sed -i -e 's/SELINUX=enforcing/SELINUX=permissive/' /etc/selinux/config
143
144 See [this report][1] for workarounds if you need to run in enforcing mode.
145
146 [1]: https://bugzilla.redhat.com/show_bug.cgi?id=1136396
147
148 ## Installing Kerberos
149
150 Install the Kerberos server and client packages with the command:
151
152     # yum install -y krb5-server krb5-workstation krb5-libs
153
154 Replace every instance of `EXAMPLE.COM` with your realm name in the following
155 configuration files:
156
157   * `/etc/krb5.conf`
158   * `/var/kerberos/krb5kdc/kdc.conf`
159   * `/var/kerberos/krb5kdc/kadm5.acl`
160
161 Replace every instance of the example hostname `kerberos.example.com` with
162 the actual hostname of your Kerberos server in the file `/etc/krb5.conf`.
163
164 Create the Kerberos database using the `krb5_util` command. You will be
165 prompted for a master principal password. Choose a password, keep it secret,
166 and keep it safe.
167
168     # /usr/sbin/kdb5_util create -s
169
170 Start the Kerberos servers.
171
172     # service krb5kdc start
173     # service kadmin start
174     # chkconfig krb5kdc on
175     # chkconfig kadmin on
176
177 ## Installing OpenAFS servers
178
179 ### Installing servers
180
181 OpenAFS RPM packages for RHEL 6 are available on the [[OpenAFS]] website. The
182 packages may be installed using `yum`.  First, install the repository
183 definition with
184
185     # version=<version>
186     # rpm -i http://openafs.org/dl/openafs/${version}/openafs-release-rhel-${version}-1.noarch.rpm
187
188 where `<version>` is the OpenAFS version you wish to install, e.g. "1.6.9".
189
190 Use `yum` to install the OpenAFS server packages:
191
192     # yum install -y openafs openafs-server openafs-docs openafs-krb5
193
194 Create the Kerberos AFS service key and export it to a keytab file:
195
196     # cellname=<cellname>
197     # kadmin.local -q "addprinc -randkey afs/${cellname}"
198     # kadmin.local -q "ktadd -k /usr/afs/etc/rxkad.keytab afs/${cellname}"
199
200 where `<cellname>` is the name of your cell.  Start the OpenAFS servers:
201
202     # service openafs-server start
203
204 Check the server log `/usr/afs/logs/BosLog` to verify the OpenAFS `bosserver`
205 process started.  Set the cell name with the command:
206
207     # bos setcellname localhost ${cellname} -localauth
208
209 ### Starting the database services
210
211 The `ptserver` process stores the AFS users and group names in your cell. The
212 `vlserver` process stores the file server locations of the AFS volumes in your
213 cell.  Start the OpenAFS database processes with the commands:
214
215     # bos create localhost ptserver simple -cmd /usr/afs/bin/ptserver -localauth
216     # bos create localhost vlserver simple -cmd /usr/afs/bin/vlserver -localauth
217
218 Check the log files `BosLog`, `PTLog`, `VLLog` in the `/usr/afs/logs`
219 directory to verify the `ptserver` and `vlserver` started.
220
221 ### Starting the file server
222
223 Start the file server. This is a rather long command line.
224
225     # bos create localhost \
226        dafs dafs -cmd \
227        "/usr/afs/bin/dafileserver -p 123 -L -busyat 200 -rxpck 2000 -cb 4000000 -vattachpar 128 -vlruthresh 1440 -vlrumax 8 -vhashsize 11" \
228        "/usr/afs/bin/davolserver -p 64 -log" \
229        "/usr/afs/bin/salvageserver" \
230        "/usr/afs/bin/dasalvager -parallel all32" \
231        -localauth
232
233 Check the servers logs `BosLog`, `FileLog`, `VolserLog`, and `SalsrvLog`, in
234 `/usr/afs/logs' to verify the file server started.  At this point the OpenAFS
235 server processes should be running.
236
237 ### Creating the admin account
238
239 Create a user account for Kerberos and AFS administration.
240
241     # myname=<username>
242     # kadmin.local -q "addprinc ${myname}/admin"
243     Enter password: <password>
244     Re-enter password: <password>
245     # pts createuser ${myname}.admin -localauth
246     # pts adduser ${myname}.admin system:administrators -localauth
247     # bos adduser localhost ${myname}.admin -localauth
248
249 where `<myname>` is your user name and `<password>` is your chosen password.
250
251 The admin principal can be any name you want.  The recommended practice is to
252 create two principals for admins: one for your normal user, and an additional
253 admin account. For example, I may have `steve` and `steve/admin`. Note that for
254 Kerberos 5, the name is `steve/admin@REALM`, whereas in AFS, the name is
255 `steve.admin`. Use `steve.admin` for all AFS commands.  Since this is to be an
256 administrator we will also register it as such with the `bos` server. We can give
257 it administrator rights by adding it to the group `system:administrators`. This
258 is an AFS default group. The `pts membership` command will list all the groups
259 that your user is a member of. Verify that it lists `system:administrators`.
260
261 ### Create the root volumes
262
263 At this point we need our `/vicepa` partition.  You should have done this when
264 installing the operating system. If you have not, do it now, then restart the
265 fileserver with `service openafs-server restart`.  (If this is only a test
266 system you may create a pseudo partition without needing to create an actual
267 separate filesystem. To do this, create an empty directory called `/vicepa` and
268 then create an empty file called `/vicepa/AlwaysAttach`, then restart the file
269 server with `service openafs-server restart`.)
270
271 Create the root volumes with the commands:
272
273     # vos create localhost a root.afs -localauth
274     # vos create localhost a root.cell -localauth
275
276 Check the volume location database to verify the two volumes are listed.
277
278     # vos listvldb
279
280 Finally, now that the server configuration is done, put the `bosserver` into
281 the more secure restricted mode, which disables several bos commands which are
282 strictly not needed for normal operation.
283
284     # bos setrestricted localhost -mode 1 -localauth
285
286 This completes the server side setup. At this point will need to install the
287 OpenAFS cache manager (client), setup the top level directories, and then start
288 adding files to your new cell.  The cache manager may be installed on a
289 separate machine (for example, your laptop.)  Also, you will no longer be using
290 the `root` user to run OpenAFS commands, but instead from this point forward
291 you should use your Kerberos credentials.
292
293 ## Installing OpenAFS Client
294
295 ### Kernel Module
296
297 If installing the cache manager on an OpenAFS server, first remove the symlinks
298 created by `bosserver`. These will be in the way if the client is installed.
299
300     # test -h /usr/vice/etc/ThisCell && rm /usr/vice/etc/ThisCell
301     # test -h /usr/vice/etc/CellServDB && rm /usr/vice/etc/CellServDB
302
303 Install the OpenAFS client with yum:
304
305     # yum install -y openafs openafs-client openafs-krb5 kmod-openafs
306
307 You may need to reboot you system if the kernel version was updated.
308
309 The OpenAFS kernel module must match your kernel version.  If a pre-built
310 module is not available for the kernel version you are running, the yum install
311 of kmod-openafs will fail.  If this happens, then you may use
312 [DKMS to build and install|RpmClientInstallationWithDKMS]] a kernel module
313 that matches your kernel version.
314
315     # yum install -y dkms gcc
316     # yum install -y openafs openafs-client openafs-krb5 dkms-openafs
317
318 Alternately, you can build the kernel module from the source rpm.  You will
319 need to download the OpenAFS SRPM file from OpenAFS.org, install the
320 `kernel-devel` package that matches your kernel version, and the necessary
321 build tools.  Use the `rpmbuild` command to build the kernel module.
322
323     # rpmbuild --rebuild -bb \
324         --define 'build_userspace 0' \
325         --define 'build_modules 1' \
326         openafs-<version>-1.src.rpm
327
328 ### Client side configuration
329
330 `/usr/afs/etc` is the location for the server files. We also need to configure
331 the client. The client files are located in `/usr/vice/etc`. RPM based OpenAFS
332 packages are set up in such a way that there are two `CellServDB` client
333 files in `/usr/vice/etc`: `CellServDB.dist` and `CellServDB.local`. We will
334 copy ours to the local list.
335
336     # cp /usr/afs/etc/CellServDB /usr/vice/etc/CellServDB.local
337     # cp /usr/afs/etc/ThisCell /usr/vice/etc/ThisCell
338
339 The RPM based `openafs-client` init script will combine the `CellServDB.dist`
340 and `CellServDB.local` files into the `CellServDB` file, which the cache
341 manager reads on startup.
342
343 ### Start the cache manager
344
345 Start the cache manager with the command:
346
347     # service openafs-client start
348
349 Run the `mount` command to verify the AFS filesystem is mounted at `/afs`.
350
351 Try logging in to AFS. `kinit` logs you into Kerberos (this is the normal
352 Kerberos utility). `aklog` gets you an AFS token.  The `tokens` command lists
353 the tokens you have. You should see `afs@<cellname>`. If you run into problems, you
354 can use `klist` to list your Kerberos tickets, or `aklog` with the `-d` flag.
355
356     $ kinit <username>/admin
357     <password>
358     $ aklog
359     $ tokens
360
361 ## Setting up the cell root directory
362
363 Now we will set up the root directories.  The root directory for the AFS
364 namespace is in the volume called `root.afs`. The root directory of your cell
365 should be in a volume called `root.cell`. You will need to set the ACLs for
366 these directories.  AFS access rights are rather different from those in UNIX.
367 I suggest reading the IBM documentation for this; it still applies.
368
369 The cache manager is started in `-dynroot` mode on RPM-based installations.
370 This allows the cache manager to mount the AFS filesystem without the need to
371 contact the OpenAFS servers. The side-effect of `-dynroot` is the `root.afs`
372 volume cannot be accessed directly.  Fortunately, we can use "magic" `.:mount`
373 directory to access the `root.afs` volume.
374
375 Set up the top level directories.
376
377     $ cellname=$(cat /usr/vice/etc/ThisCell)
378     
379     $ cd /afs/.:mount/${cellname}:root.afs/
380     $ fs mkmount ${cellname} root.cell -cell ${cellname}
381     $ fs mkmount .${cellname} root.cell -cell ${cellname} -rw
382     $ fs setacl . system:anyuser read
383     
384     $ cd /afs/.:mount/${cellname}:root.cell/
385     $ fs setacl . system:anyuser read
386
387 Replicate the root volumes so that you have read only copies.  Later, if more
388 file servers are added to the cell, additional read-only copies should be made.
389
390     $ server=<hostname of the fileserver>
391     $ vos addsite ${server} a root.afs
392     $ vos release root.afs
393     $ vos addsite ${server} a root.cell
394     $ vos release root.cell
395
396 ## Adding users and volumes
397
398 Now that OpenAFS is installed, the site specific AFS volumes and directory
399 structure can be set up. Users should be made, along with their home
400 volumes. ACLs for the volume directories should be established.
401
402 This section provides an example setup. The names of the volumes and
403 directories can be specific to your needs.
404
405 You must first authenticate as a Kerberos/AFS admin to run the commands
406 shown in this section.
407
408     $ kadmin <username>/admin
409     $ aklog
410
411 ### Creating user accounts
412
413 We can create a user by registering it to Kerberos and the `ptserver` database.
414 If you use integrated login, make sure that the users' UNIX uids and pts ids
415 match.
416
417     $ kadmin -q "addprinc <username>"
418     <enter password for username>
419     $ pts createuser <username> -id <numeric uid>
420
421 If you use integrated login, make sure that you add an entry to /etc/passwd or
422 whatever means you use of distributing user information.
423
424 ### Setting up volumes for users
425
426 First, we can make a top level volume to contain the mount points to volumes
427 for individuals. The IBM documentation suggests making a directory
428 `/afs/<cellname>/user` with volume name user for all of your AFS users. Some
429 sites have adopted the directory `home` instead of `user`.  If you use `home`,
430 your users may feel more comfortable, as this is the convention in Linux and
431 most UNIXes.
432
433 The following commands create the `home` volume and make a read-only replica:
434
435     $ vos create <fileserver> a home
436     $ cd /afs/.<cellname>
437     $ fs mkmount home home
438     $ vos addsite <fileserver> a home
439     $ vos release root.cell
440     $ vos release home
441
442 Now you can create directories for any of your users. We will not replicate
443 these volumes. By not replicating them, we force the cache manager to access a
444 read/write volume. This means that even if we access the cell through the
445 read-only volume we can still access our read/write user directories (this is
446 what you want). Maxquota 0 means that there is no size restriction to the
447 volume. You can give it a restriction if you like (the default is 5mb). Do
448 these commands for every directory you like.
449
450     $ vos create <fileserver> a home.<uid> -maxquota 0
451     $ cd /afs/.<cellname>/home
452     $ fs mkmount <user> home.<uid>
453     $ vos release home
454
455 The home volume is released to make the new directories are visible from the
456 read only mount point.
457
458 ### Setting ACLs
459
460 Now that we have volumes, we should set some restrictions on those volumes.
461 If you trust the users not to make directories *world writable*, you
462 can give the user of the directory full rights.
463
464     $ cd /afs/.<cellname>/home
465     $ fs setacl -dir <user> -acl <user> all
466
467 To give the users read and write access, but not rights to change ACLs,
468
469     $ cd /afs/.<cellname>/home
470     $ fs setacl -dir <user> -acl <user> write
471