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