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