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