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