1 = Basic AFS cell setup =
3 In this section we will setup the most basic configuration, consisting of
4 a single AFS database service, a single AFS fileserver, and one AFS client.
5 Only read-write volumes will be setup at this time.
7 We assume the Kerberos realm is setup and ready before doing any of the
10 This tutorial assumes the client is configured to start with the Dynamic
11 Root (-dynroot) enabled. This is the default on modern systems.
13 == Creating the service key ==
15 How do we create the afs service key?
17 1, Login as '''root''' to the Kerberos server; <code>root@afsdb1</code>.
19 2. Add a service principal for our new AFS cell using
20 <code>kadmin.local</code>. The format of an AFS service principal name is:
22 afs/<cellname>@<REALMNAME>
24 For this example, YOYODYNE.COM is the realm name, yoyodyne.com is the instance
25 name, and afs is the name. We want to add a principal that does not require a
26 password so we also must use the -randkey option to generate a random set of
27 keys. The following shows how the information should be organized on the kadmin
31 ank -randkey afs/yoyodyne.com@YOYODYNE.COM
33 3. In order to use the newly generated keys, they must be moved to a secure
34 location on the AFS servers. Export the keys into a keytab file to be installed
35 on the AFS servers. To continue the above example:
37 ktadd -k /root/rxkad.keytab -e aes256-cts:normal,aes128-cts:normal afs/yoyodyne.com@YOYODYNE.COM
39 '''NOTE''': Do not add a space after the comma separating the encryption types.
41 4. Check that the correct keys are now in the file by quitting kadmin.local and
42 entering the next command:
44 klist -e -k -t /root/rxkad.keytab
46 This list should only contain keys with aes at the beginning. The principal
47 should also match the principal that was entered in the previous step.
49 5. Now the keys need to be copied to the AFS database and file servers. To do
50 that securely, use the <code>scp</code> command:
52 scp /root/rxkad.keytab afsdb1:/usr/afs/etc/rxkad.keytab
53 scp /root/rxkad.keytab afs01:/usr/afs/etc/rxkad.keytab
55 6. Finally, remove our temporary keytab file.
59 == Creating the database server ==
61 How do we setup the single database server?
63 1. First the BOS server needs to be started which will oversee other AFS server processes. To do that issue the following command:
64 service openafs-server start
66 To check that the server is running issue the next command:
69 The output should include 'bos: running ...' which tells you that the command was correct and started running the bos server.
71 2. Next the bos server needs a cell name that matches the cell name where the keys were stored. The next command names the bos cell:
72 bos setcellname afsdb1 yoyodyne.com -localauth
74 *Remember to include the -localauth command.
76 3. Check that the cell name is correct after doing the previous step. To do that, enter the next command:
79 4. Now the PT Server and the VL Server need to be created on the BOS server. To do that, use this command for the PT Server:
80 bos create afsdb1 ptserver simple /usr/afs/bin/ptserver -localauth
82 Enter the same command for the VL Server, but replace ptserver with vlserver.
84 5. Check the logs for each server to make sure they are running. Enter this command for PT Server:
85 bos getlog afsdb1 PtLog -localauth
87 Enter this command for the VL Server:
88 bos getlog afsdb1 VLLog -localauth
90 Caution: '''Do not''' use this command to try to check the logs: '''bos getlog afsdb1 /usr/afs/bin/ptserver -localauth'''. Bad idea.
92 == Creating the file server ==
94 How do we setup the first file server?
96 1. First the BOS server needs to be started which will oversee other AFS server processes. To do that issue the following command:
97 service openafs-server start
99 To check that the server is running issue the next command:
102 The output should include 'bos: running ...' which tells you that the command was correct and started running the bos server.
104 2. Next the bos server needs a cell name that matches the cell name where the keys were stored. The next command names the bos cell:
105 bos setcellname afs01 yoyodyne.com -localauth
107 *Remember to include the -localauth command.
109 3. Check that the cell name is correct after doing the previous step. To do that, enter the next command:
112 Notice that the host is afs01.classroom.sinenomine.net. That needs to be changed because the original BOS server setup was on afsdb1.classroom.sinenomine.net.
114 a. First add the afsdb1 as a host by using this command:
115 bos addhost afs01.classroom.sinenomine.net afsdb1.classroom.sinenomine.net -localauth
117 Check that afsdb1 was added to the list correctly:
120 b. Next remove the afs01 as a host by using this command:
121 bos removehost afs01.classroom.sinenomine.net afs01.classroom.sinenomine.net -localauth
123 Again, check that afs01 was removed from the list correctly:
126 4. Now the DAFS need to be created on the BOS server. To do that, use this really long command for the DAFS server:
127 bos create afs01 dafs dafs /usr/afs/bin/dafileserver /usr/afs/bin/davolserver /usr/afs/bin/salvageserver /usr/afs/bin/dasalvager -localauth
129 5. Now check all four of the logs. The largest log file will be "FileLog" so save the best for last. The command to check each file is:
130 cat /usr/afs/logs/<filename>
132 *The file names are: FileLog, BosLog, SalsrvLog, and VolserLog.
134 6. The next step is to create the root volumes. There are two important volumes. First is the root.afs volume which is the very first volume to create. This command will create the volume:
135 vos create afs01 a root.afs -localauth
137 Next the root cell volume needs to be created. This will match the cell that was created in previous steps. The command for this is:
138 vos create afs01 a root.cell -localauth
140 == Creating the workstation ==
142 1. First, check that rpms is installed:
145 2. Check that afs is not already running on the machine:
147 service openafs-client status
149 3. We can double check by verifying afs is not mounted, the kernel module is
150 not loaded, and n there are no userspace AFS processes running:
156 ps -ef | grep afs | grep -v grep
159 5. Now change directory:
162 See that there are two folders. "Cache" stores the afs cache files. "Etc" stores the configuration files.
164 Enter into the "Etc" directory:
167 See all of the files that this directory has. The client can have lots of entries for other sites, unlike the
168 server. They are called foreign sites.
170 6. Now secure copy CellServDB.local and ThisCell into the workstation files:
173 scp afsdb1:/usr/afs/etc/CellServDB /usr/vice/etc/CellServDB.local
174 scp afsdb1:/usr/afs/etc/ThisCell /usr/vice/etc/ThisCell
176 Look at the new files.
177 cat /usr/vice/etc/ThisCell
178 cat /usr/vice/etc/CellServDB
179 cat /usr/vice/etc/cacheinfo
181 7. Let us setup the foreign cells which will be accessible to the client:
183 mv /usr/vice/etc/CellServDB.dist /usr/vice/etc/CellServDB.saved
184 scp afsdb1:/root/CellServDB.dist /usr/vice/etc/CellServDB.dist
186 8. Check the AFS client startup options:
188 cat /etc/sysconfig/openafs
190 This should show "-dynroot -fakestat -afsdb" for the client start up options.
192 9. Now is the time to start the client:
194 service openafs-client start
196 Check that the client is now running using steps 2 and 3 above, and try:
200 This should show the list of cells accessible.
202 == Creating the admin user ==
204 Now we create the first user account and grant admin privileges to that
205 account. The account will be used for Kerberos as well as AFS administration.
206 Later, we will create regular user accounts
208 We will need to go back to the database server to create the '''first'''
211 1. First add a new principal to Kerberos called 'admin'. First login as
212 '''root''' on to the Kerberos server: <code>ssh root@afsdb1</code>.
214 2. Run use the kadmin.local command to create the kerberos principal.
218 Enter password for principal "admin@YOYODYNE.COM": **********
219 Re-enter password for principal "admin@YOYODYNE.COM": **********
222 3. The next step is to create a user on the PT server, where usernames and ids
223 are stored in AFS. Use this command to create the user:
225 pts createuser admin -localauth
227 4. Now add the new user to a group:
229 pts adduser admin system:administrators -localauth
231 Check that the user was successfully added to the group:
233 pts membership admin -localauth
235 5. Next add the name to the super user list on the servers. To do that use this
236 command for both afs01 and afsdb1:
238 bos adduser afs01 admin -localauth
239 bos adduser afsdb1 admin -localauth
241 6. Check that admin was added to the super user list through this command for
242 both afs01 and afsdb1:
244 bos listusers afs01 -localauth
245 bos listusers afsdb1 -localauth
249 At this point, you should be able to acquire an admin token and create files and directories
250 in the afs filesystem of your basic cell. Use a regular user from here on out. You should
251 no longer use the Linux '''root''' account or sudo for the rest of this tutorial.
253 1. Log into the workstation as a regular user, <code>ssh <user>@workstation1</code>.
255 2. Acquire the AFS administrator token:
261 The tokens command should show AFS User 1, which is the id of the admin in our tutorial
264 3. Verify we can access the afs name space. we should be able to create files under
268 touch /afs/yoyodyne.com/testfile
269 rm /afs/yoyodyne.com/testfile
273 Before users can use our site, we need to setup the root volume for the AFS
274 namespace (root.afs), the root volume for our cell (root.cell), and any top
275 level volumes for our new site (e.g. users, projects, etc).
277 Log in as a normal user (not root) on the workstation and then acquire an token
278 for the AFS administrator.
284 The <code>tokens</code> output should show the AFS id of 1, which is the
285 Administrator's id in this tutorial.
287 == Setting up root.afs ==
289 The <code>root.afs</code> volume should contain the mount points of the cells
290 to be accessed. This is needed for clients which are running without the
291 '''dynroot''' mode enabled. The client we are using in this tutorial is
292 running in '''dynroot''' mode. See [[OpenAFS root setup without dynroot]] for
293 the setup steps when the client is not running in '''dynroot''' mode.
295 Mount the <code>root.afs</code> volume with a temporary mount point.
297 fs mkmount -dir /afs/yoyodyne.com/temp -vol root.afs
299 Mount the local cell.
301 fs mkmount -dir /afs/yoyodyne.com/temp/yoyodyne.com -vol root.cell -cell yoyodyne.com
303 Mount each of the foreign cells we would like to access:
305 fs mkmount -dir /afs/yoyodyne.com/temp/acme.com -vol root.cell -cell acme.com
307 Grant read access to the AFS root directory to anonymous users.
309 fs setacl /afs/yoyodyne.com/temp system:anyuser read
311 Finally, remove the temporary mount point.
313 fs rmmount -dir /afs/yoyodyne.com/temp
315 Test on a system that does not have <code>-dynroot</code>.
317 == Setting up root.cell ==
319 The <code>root.cell</code> holds the top level directory for our cell. Typically,
320 this will have mount points to the top level volumes for our cell.
322 Grant read access to the cell root directory to anonymous users.
324 fs setacl /afs/yoyodyne.com/ system:anyuser read
326 == Setting up our cell top level volumes ==
328 Create a projects volume to use later, make a mount point in our root.cell to the
329 new volume, and give the anonymous users read rights to the root directory of
332 vos create afs01 a projects
333 fs mkmount /afs/yoyodyne.com/projects projects
334 fs setacl /afs/yoyodyne.com/projects system:anyuser read
336 Do the same for a top level volume for our users.
338 vos create afs01 a user
339 fs mkmount /afs/yoyodyne.com/user user
340 fs setacl /afs/yoyodyne.com/user system:anyuser read
342 = Creating regular users =
344 Now we can create regular users for our site. We give each user a dedicated
345 volume to share files.
347 Every user requires a Kerberos principal and an AFS user name/number. We use
348 the <code>kadmin</code> command to create the kerberos principal, and the AFS
349 <code>pts</code> command to create the AFS user name/number pair.
351 You should be logged on to the workstation as a regular user (not root). The
352 commands will contact the database servers over the network.
354 1. Be sure you have an '''admin''' token.
360 2. Create the Kerberos principal for the new user:
364 Enter password: *******
365 Re-enter password: ******
368 3. Create the AFS user name/number:
370 pts createuser <newuser>
372 4 Create a volume for the new user, mount it under the top level user
373 directory, and give the user write permisssions in their new volume.
375 vos create afs01 a user.<newuser>
376 fs mkmount /afs/yoyodyne.com/user/<newuser> user.<newuser>
377 fs sa /afs/yoyodyne.com/user/<newuser> <newuser> write
379 5. Check by getting a token for the user.
388 fs listacl /afs/yoyodyne.com/user/<newuser>
389 touch /afs/yoyodyne.com/user/<newuser>/testfile
390 rm /afs/yoyodyne.com/user/<newuser>/testfile
395 Sine Nomine Associates Nov 2017