Update the scp command to work by default.
[openafs-wiki.git] / reguser / OpenAFSSimpleSetup.mdwn
1 = Basic AFS cell setup =
2
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.
6
7 We assume the Kerberos realm is setup and ready before doing any of the
8 steps in this section.
9
10 This tutorial assumes the client is configured to start with the Dynamic
11 Root (-dynroot) enabled.  This is the default on modern systems.
12
13 == Creating the service key ==
14
15 How do we create the afs service key?
16
17 1, Login as '''root''' to the Kerberos server; <code>root@afsdb1</code>.
18
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:
21
22     afs/<cellname>@<REALMNAME>
23
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
28 command line.
29
30     kadmin.local
31     ank -randkey afs/yoyodyne.com@YOYODYNE.COM
32
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: 
36
37     ktadd -k /root/rxkad.keytab -e aes256-cts:normal,aes128-cts:normal afs/yoyodyne.com@YOYODYNE.COM
38
39 '''NOTE''': Do not add a space after the comma separating the encryption types.
40
41 4. Check that the correct keys are now in the file by quitting kadmin.local and
42 entering the next command:
43
44     klist -e -k -t /root/rxkad.keytab
45
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.
48
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:
51
52     scp /root/rxkad.keytab afsdb1:/usr/afs/etc/rxkad.keytab
53     scp /root/rxkad.keytab afs01:/usr/afs/etc/rxkad.keytab
54
55 6. Finally, remove our temporary keytab file.
56
57     rm /root/rxkad.keytab
58
59 == Creating the database server ==
60
61 How do we setup the single database server?
62
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
65
66 To check that the server is running issue the next command: 
67     bos listhosts afsdb1
68
69  The output should include 'bos: running ...' which tells you that the command was correct and started running the bos server.
70
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
73
74 *Remember to include the -localauth command.
75
76 3. Check that the cell name is correct after doing the previous step. To do that, enter the next command: 
77     bos listhosts afsdb1
78
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
81
82 Enter the same command for the VL Server, but replace ptserver with vlserver.
83
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 
86
87 Enter this command for the VL Server: 
88     bos getlog afsdb1 VLLog -localauth
89
90 Caution: '''Do not''' use this command to try to check the logs: '''bos getlog afsdb1 /usr/afs/bin/ptserver -localauth'''. Bad idea.
91
92 == Creating the file server ==
93
94 How do we setup the first file server?
95
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
98
99 To check that the server is running issue the next command: 
100     bos listhosts afs01
101
102 The output should include 'bos: running ...' which tells you that the command was correct and started running the bos server.
103
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 
106
107 *Remember to include the -localauth command.
108
109 3. Check that the cell name is correct after doing the previous step. To do that, enter the next command: 
110     bos listhosts afsdb1 
111
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. 
113
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 
116
117 Check that afsdb1 was added to the list correctly: 
118     bos listhosts afs01
119
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
122
123 Again, check that afs01 was removed from the list correctly: 
124     bos listhosts afs01
125
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
128
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>
131
132 *The file names are: FileLog, BosLog, SalsrvLog, and VolserLog.
133
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
136
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
139
140 == Creating the workstation ==
141
142 1. First, check that rpms is installed: 
143     rpm -qa | grep afs
144
145 2. Check that afs is not already running on the machine:
146
147     service openafs-client status
148
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: 
151
152     mount | grep /afs
153     ...
154     lsmod | grep afs
155     ...
156     ps -ef | grep afs | grep -v grep
157
158
159 5. Now change directory: 
160     cd /usr/vice/
161
162 See that there are two folders. "Cache" stores the afs cache files. "Etc" stores the configuration files. 
163
164 Enter into the "Etc" directory:
165     cd etc 
166
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.
169
170 6. Now secure copy CellServDB.local and ThisCell into the workstation files:
171
172
173     scp afsdb1:/usr/afs/etc/CellServDB /usr/vice/etc/CellServDB.local
174     scp afsdb1:/usr/afs/etc/ThisCell /usr/vice/etc/ThisCell
175
176 Look at the new files. 
177     cat /usr/vice/etc/ThisCell 
178     cat /usr/vice/etc/CellServDB
179     cat /usr/vice/etc/cacheinfo
180
181 7. Let us setup the foreign cells which will be accessible to the client:
182
183     mv /usr/vice/etc/CellServDB.dist /usr/vice/etc/CellServDB.saved
184     scp afsdb1:/root/CellServDB.dist /usr/vice/etc/CellServDB.dist
185
186 8. Check the AFS client startup options:
187
188     cat /etc/sysconfig/openafs
189
190 This should show "-dynroot -fakestat -afsdb" for the client start up options.
191
192 9. Now is the time to start the client:
193
194     service openafs-client start
195
196 Check that the client is now running using steps 2 and 3 above, and try:
197
198     ls /afs
199
200 This should show the list of cells accessible.
201
202 == Creating the admin user ==
203
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
207
208 We will need to go back to the database server to create the '''first'''
209 account.
210
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>.
213
214 2. Run use the kadmin.local command to create the kerberos principal.
215
216     kadmin.local
217     ank admin
218     Enter password for principal "admin@YOYODYNE.COM": **********
219     Re-enter password for principal "admin@YOYODYNE.COM": **********
220     exit
221
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:
224
225     pts createuser admin -localauth
226
227 4. Now add the new user to a group:
228
229     pts adduser admin system:administrators -localauth
230
231 Check that the user was successfully added to the group: 
232
233     pts membership admin -localauth
234
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: 
237
238     bos adduser afs01 admin -localauth
239     bos adduser afsdb1 admin -localauth
240
241 6. Check that admin was added to the super user list through this command for
242 both afs01 and afsdb1: 
243
244     bos listusers afs01 -localauth
245     bos listusers afsdb1 -localauth
246
247 == Check ==
248
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.
252
253 1. Log into the workstation as a regular user, <code>ssh <user>@workstation1</code>.
254
255 2. Acquire the AFS administrator token:
256
257     kinit admin
258     aklog
259     tokens
260
261 The tokens command should show AFS User 1, which is the id of the admin in our tutorial
262 cell.
263
264 3. Verify we can access the afs name space. we should be able to create files under
265 our cell directory.
266
267     ls /afs/yoyodyne.com
268     touch /afs/yoyodyne.com/testfile
269     rm /afs/yoyodyne.com/testfile
270
271 = Namespace setup =
272
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).
276
277 Log in as a normal user (not root) on the workstation and then acquire an token
278 for the AFS administrator.
279
280     kinit admin
281     aklog
282     tokens
283
284 The <code>tokens</code> output should show the AFS id of 1, which is the
285 Administrator's id in this tutorial.
286
287 == Setting up root.afs ==
288
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.
294
295 Mount the <code>root.afs</code> volume with a temporary mount point.
296
297     fs mkmount -dir /afs/yoyodyne.com/temp -vol root.afs
298
299 Mount the local cell.
300
301     fs mkmount -dir /afs/yoyodyne.com/temp/yoyodyne.com -vol root.cell -cell yoyodyne.com
302
303 Mount each of the foreign cells we would like to access:
304
305     fs mkmount -dir /afs/yoyodyne.com/temp/acme.com -vol root.cell -cell acme.com
306
307 Grant read access to the AFS root directory to anonymous users.
308
309     fs setacl /afs/yoyodyne.com/temp system:anyuser read
310
311 Finally, remove the temporary mount point.
312
313     fs rmmount -dir /afs/yoyodyne.com/temp
314
315 Test on a system that does not have <code>-dynroot</code>.
316
317 == Setting up root.cell ==
318
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.
321
322 Grant read access to the cell root directory to anonymous users.
323
324     fs setacl /afs/yoyodyne.com/ system:anyuser read
325
326 == Setting up our cell top level volumes ==
327
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
330 the new volume.
331
332     vos create afs01 a projects
333     fs mkmount /afs/yoyodyne.com/projects projects
334     fs setacl /afs/yoyodyne.com/projects system:anyuser read
335
336 Do the same for a top level volume for our users.
337
338     vos create afs01 a user
339     fs mkmount /afs/yoyodyne.com/user user
340     fs setacl /afs/yoyodyne.com/user system:anyuser read
341
342 = Creating regular users = 
343
344 Now we can create regular users for our site. We give each user a dedicated
345 volume to share files. 
346
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.
350
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.
353
354 1. Be sure you have an '''admin''' token.
355
356     kinit admin
357     aklog
358     tokens
359
360 2. Create the Kerberos principal for the new user:
361
362     kadmin -p admin
363     ank <newuser>
364     Enter password: *******
365     Re-enter password: ******
366     exit
367
368 3. Create the AFS user name/number:
369
370     pts createuser <newuser>
371
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.
374
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
378
379 5. Check by getting a token for the user.
380
381     unlog
382     kdestroy
383      
384     kinit <newuser>
385     aklog
386     tokens
387     
388     fs listacl /afs/yoyodyne.com/user/<newuser>
389     touch /afs/yoyodyne.com/user/<newuser>/testfile
390     rm /afs/yoyodyne.com/user/<newuser>/testfile
391     
392     unlog
393     kdestroy
394
395 Sine Nomine Associates Nov 2017