Commit | Line | Data |
---|---|---|
805e021f CE |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <chapter id="HDRWQ17"> | |
3 | <title>Installing the First AFS Machine</title> | |
4 | ||
5 | <para> | |
6 | <indexterm> | |
7 | <primary>file server machine</primary> | |
8 | ||
9 | <seealso>first AFS machine</seealso> | |
10 | ||
11 | <seealso>file server machine, additional</seealso> | |
12 | </indexterm> | |
13 | ||
14 | <indexterm> | |
15 | <primary>instructions</primary> | |
16 | ||
17 | <secondary>first AFS machine</secondary> | |
18 | </indexterm> | |
19 | ||
20 | <indexterm> | |
21 | <primary>installing</primary> | |
22 | ||
23 | <secondary>first AFS machine</secondary> | |
24 | </indexterm> | |
25 | ||
26 | This chapter describes how to install the first AFS machine in your cell, configuring it as both a file server machine and a | |
27 | client machine. After completing all procedures in this chapter, you can remove the client functionality if you wish, as described | |
28 | in <link linkend="HDRWQ98">Removing Client Functionality</link>.</para> | |
29 | ||
30 | <para>To install additional file server machines after completing this chapter, see <link linkend="HDRWQ99">Installing Additional | |
31 | Server Machines</link>.</para> | |
32 | ||
33 | <para>To install additional client machines after completing this chapter, see <link linkend="HDRWQ133">Installing Additional | |
34 | Client Machines</link>. <indexterm> | |
35 | <primary>requirements</primary> | |
36 | ||
37 | <secondary>first AFS machine</secondary> | |
38 | </indexterm></para> | |
39 | ||
40 | <sect1 id="Header_29"> | |
41 | <title>Requirements and Configuration Decisions</title> | |
42 | ||
43 | <para>The instructions in this chapter assume that you meet the following requirements. | |
44 | <itemizedlist> | |
45 | <listitem> | |
46 | <para>You are logged onto the machine's console as the local superuser <emphasis role="bold">root</emphasis></para> | |
47 | </listitem> | |
48 | ||
49 | <listitem> | |
50 | <para>A standard version of one of the operating systems supported by the current version of AFS is running on the | |
51 | machine</para> | |
52 | </listitem> | |
53 | ||
54 | <listitem> | |
55 | <para>You have either installed the provided OpenAFS packages for | |
56 | your system, have access to a binary distribution tarball, or have | |
57 | successfully built OpenAFS from source</para> | |
58 | </listitem> | |
59 | ||
60 | <listitem> | |
61 | <para>You have a Kerberos v5 realm running for your site. If you are | |
62 | working with an existing cell which uses legacy | |
63 | <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for | |
64 | authentication, please see | |
65 | <link linkend="KAS001">kaserver and Legacy Kerberos v4 Authentication</link> | |
66 | for the modifications required to this installation procedure.</para> | |
67 | </listitem> | |
68 | ||
69 | <listitem> | |
70 | <para>You have NTP or a similar time service deployed to ensure | |
71 | rough clock syncronistation between your clients and servers.</para> | |
72 | </listitem> | |
73 | </itemizedlist></para> | |
74 | ||
75 | <para>You must make the following configuration decisions while installing the first AFS machine. To speed the installation | |
76 | itself, it is best to make the decisions before beginning. See the chapter in the <emphasis>OpenAFS Administration | |
77 | Guide</emphasis> about issues in cell administration and configuration for detailed guidelines. <indexterm> | |
78 | <primary>cell name</primary> | |
79 | ||
80 | <secondary>choosing</secondary> | |
81 | </indexterm> <indexterm> | |
82 | <primary>AFS filespace</primary> | |
83 | ||
84 | <secondary>deciding how to configure</secondary> | |
85 | </indexterm> <indexterm> | |
86 | <primary>filespace</primary> | |
87 | ||
88 | <see>AFS filespace</see> | |
89 | </indexterm> <itemizedlist> | |
90 | <listitem> | |
91 | <para>Select the first AFS machine</para> | |
92 | </listitem> | |
93 | ||
94 | <listitem> | |
95 | <para>Select the cell name</para> | |
96 | </listitem> | |
97 | ||
98 | <listitem> | |
99 | <para>Decide which partitions or logical volumes to configure as AFS server partitions, and choose the directory names on | |
100 | which to mount them</para> | |
101 | </listitem> | |
102 | ||
103 | <listitem> | |
104 | <para>Decide how big to make the client cache</para> | |
105 | </listitem> | |
106 | ||
107 | <listitem> | |
108 | <para>Decide how to configure the top levels of your cell's AFS filespace</para> | |
109 | </listitem> | |
110 | </itemizedlist></para> | |
111 | ||
112 | <para>This chapter is divided into three large sections corresponding to the three parts of installing the first AFS machine. | |
113 | Perform all of the steps in the order they appear. Each functional section begins with a summary of the procedures to perform. | |
114 | The sections are as follows: <itemizedlist> | |
115 | <listitem> | |
116 | <para>Installing server functionality (begins in <link linkend="HDRWQ18">Overview: Installing Server | |
117 | Functionality</link>)</para> | |
118 | </listitem> | |
119 | ||
120 | <listitem> | |
121 | <para>Installing client functionality (begins in <link linkend="HDRWQ63">Overview: Installing Client | |
122 | Functionality</link>)</para> | |
123 | </listitem> | |
124 | ||
125 | <listitem> | |
126 | <para>Configuring your cell's filespace, establishing further security mechanisms, and enabling access to foreign cells | |
127 | (begins in <link linkend="HDRWQ71">Overview: Completing the Installation of the First AFS Machine</link>)</para> | |
128 | </listitem> | |
129 | </itemizedlist></para> | |
130 | ||
131 | <indexterm> | |
132 | <primary>overview</primary> | |
133 | ||
134 | <secondary>installing server functionality on first AFS machine</secondary> | |
135 | </indexterm> | |
136 | ||
137 | <indexterm> | |
138 | <primary>first AFS machine</primary> | |
139 | ||
140 | <secondary>server functionality</secondary> | |
141 | </indexterm> | |
142 | ||
143 | <indexterm> | |
144 | <primary>installing</primary> | |
145 | ||
146 | <secondary>server functionality</secondary> | |
147 | ||
148 | <tertiary>first AFS machine</tertiary> | |
149 | </indexterm> | |
150 | </sect1> | |
151 | ||
152 | <sect1 id="HDRWQ18"> | |
153 | <title>Overview: Installing Server Functionality</title> | |
154 | ||
155 | <para>In the first phase of installing your cell's first AFS machine, you install file server and database server functionality | |
156 | by performing the following procedures: | |
157 | <orderedlist> | |
158 | <listitem> | |
159 | <para>Choose which machine to install as the first AFS machine</para> | |
160 | </listitem> | |
161 | ||
162 | <listitem> | |
163 | <para>Create AFS-related directories on the local disk</para> | |
164 | </listitem> | |
165 | ||
166 | <listitem> | |
167 | <para>Incorporate AFS modifications into the machine's kernel</para> | |
168 | </listitem> | |
169 | ||
170 | <listitem> | |
171 | <para>Configure partitions or logical volumes for storing AFS volumes</para> | |
172 | </listitem> | |
173 | ||
174 | <listitem> | |
175 | <para>On some system types (very rare), install and configure | |
176 | an AFS-modified version of the <emphasis role="bold">fsck</emphasis> | |
177 | program</para> | |
178 | </listitem> | |
179 | ||
180 | <listitem> | |
181 | <para>If the machine is to remain a client machine, incorporate AFS into its authentication system</para> | |
182 | </listitem> | |
183 | ||
184 | <listitem> | |
185 | <para>Start the Basic OverSeer (BOS) Server</para> | |
186 | </listitem> | |
187 | ||
188 | <listitem> | |
189 | <para>Define the cell name and the machine's cell membership</para> | |
190 | </listitem> | |
191 | ||
192 | <listitem> | |
193 | <para>Start the database server processes: Backup Server, Protection Server, and Volume Location | |
194 | (VL) Server</para> | |
195 | </listitem> | |
196 | ||
197 | <listitem> | |
198 | <para>Configure initial security mechanisms</para> | |
199 | </listitem> | |
200 | ||
201 | <listitem> | |
202 | <para>Start the <emphasis role="bold">fs</emphasis> process, which incorporates three component processes: the File | |
203 | Server, Volume Server, and Salvager</para> | |
204 | </listitem> | |
205 | ||
206 | <listitem> | |
207 | <para>Optionally, start the server portion of the Update Server</para> | |
208 | </listitem> | |
209 | ||
210 | </orderedlist></para> | |
211 | </sect1> | |
212 | ||
213 | <sect1 id="HDRWQ19"> | |
214 | <title>Choosing the First AFS Machine</title> | |
215 | ||
216 | <para>The first AFS machine you install must have sufficient disk space to store AFS volumes. | |
217 | When you later install additional file server | |
218 | machines in your cell, you can distribute these volumes among the different machines as you see fit.</para> | |
219 | ||
220 | <para>These instructions configure the first AFS machine as a <emphasis>database server machine</emphasis>, and optionally as the <emphasis>binary | |
221 | distribution machine</emphasis> for its system type and the cell's <emphasis>system control machine</emphasis>. For a | |
222 | description of these roles, see the <emphasis>OpenAFS Administration Guide</emphasis>.</para> | |
223 | ||
224 | <para>Installation of additional machines is simplest if the first machine has the lowest IP address of any database server | |
225 | machine you currently plan to install. If you later install database server functionality on a machine with a lower IP address, | |
226 | you must first update the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on all of your cell's client machines. | |
227 | For more details, see <link linkend="HDRWQ114">Installing Database Server Functionality</link>.</para> | |
228 | </sect1> | |
229 | ||
230 | <sect1 id="Header_32"> | |
231 | <title>Creating AFS Directories</title> | |
232 | ||
233 | <indexterm> | |
234 | <primary>usr/afs directory</primary> | |
235 | ||
236 | <secondary>first AFS machine</secondary> | |
237 | </indexterm> | |
238 | ||
239 | <indexterm> | |
240 | <primary>first AFS machine</primary> | |
241 | ||
242 | <secondary>/usr/afs directory</secondary> | |
243 | </indexterm> | |
244 | ||
245 | <indexterm> | |
246 | <primary>creating</primary> | |
247 | ||
248 | <secondary>/usr/afs directory</secondary> | |
249 | ||
250 | <tertiary>first AFS machine</tertiary> | |
251 | </indexterm> | |
252 | ||
253 | <indexterm> | |
254 | <primary>usr/vice/etc directory</primary> | |
255 | ||
256 | <secondary>first AFS machine</secondary> | |
257 | </indexterm> | |
258 | ||
259 | <indexterm> | |
260 | <primary>first AFS machine</primary> | |
261 | ||
262 | <secondary>/usr/vice/etc directory</secondary> | |
263 | </indexterm> | |
264 | ||
265 | <indexterm> | |
266 | <primary>creating</primary> | |
267 | ||
268 | <secondary>/usr/vice/etc directory</secondary> | |
269 | ||
270 | <tertiary>first AFS machine</tertiary> | |
271 | </indexterm> | |
272 | ||
273 | <indexterm> | |
274 | <primary>/ as start to file and directory names</primary> | |
275 | ||
276 | <secondary>see alphabetized entries without initial slash</secondary> | |
277 | </indexterm> | |
278 | ||
279 | <para>If you are installing from packages (such as Debian .deb or | |
280 | Fedora/SuSe .rpm files), you should now install all of the available | |
281 | OpenAFS packages for your system type. Typically, these will include | |
282 | packages for client and server functionality, and a seperate package | |
283 | containing a suitable kernel module for your running kernel. Consult | |
284 | the package lists on the OpenAFS website to determine the packages | |
285 | appropriate for your system. The preparer of such packages may | |
286 | have included some helper scripts to partially automate the | |
287 | creation of a new cell; such scripts can supersede much of the | |
288 | procedures described in the rest of this document.</para> | |
289 | ||
290 | <para>If you are installing from a tarfile, or from a locally compiled | |
291 | source tree you should create the <emphasis role="bold">/usr/afs</emphasis> | |
292 | and <emphasis role="bold">/usr/vice/etc</emphasis> directories on the | |
293 | local disk, to house server and client files respectively. Subsequent | |
294 | instructions copy files from the distribution tarfile into them. </para> | |
295 | <programlisting> | |
296 | # <emphasis role="bold">mkdir /usr/afs</emphasis> | |
297 | # <emphasis role="bold">mkdir /usr/vice</emphasis> | |
298 | # <emphasis role="bold">mkdir /usr/vice/etc</emphasis> | |
299 | </programlisting> | |
300 | </sect1> | |
301 | ||
302 | <sect1 id="HDRWQ20"> | |
303 | <title>Performing Platform-Specific Procedures</title> | |
304 | ||
305 | <para>Several of the initial procedures for installing a file server machine differ for each system type. For convenience, the | |
306 | following sections group them together for each system type: <itemizedlist> | |
307 | <indexterm> | |
308 | <primary>kernel extensions</primary> | |
309 | ||
310 | <see>AFS kernel extensions</see> | |
311 | </indexterm> | |
312 | ||
313 | <indexterm> | |
314 | <primary>loading AFS kernel extensions</primary> | |
315 | ||
316 | <see>incorporating</see> | |
317 | </indexterm> | |
318 | ||
319 | <indexterm> | |
320 | <primary>building</primary> | |
321 | ||
322 | <secondary>AFS extensions into kernel</secondary> | |
323 | ||
324 | <see>incorporating AFS kernel extensions</see> | |
325 | </indexterm> | |
326 | ||
327 | <listitem> | |
328 | <para>Incorporate AFS modifications into the kernel.</para> | |
329 | ||
330 | <para>The kernel on every AFS client machine and, on some systems, | |
331 | the AFS fileservers, must incorporate AFS extensions. On machines | |
332 | that use a dynamic kernel module loader, it is conventional to | |
333 | alter the machine's initialization script to load the AFS extensions | |
334 | at each reboot. The preparer of OS-format binary packages | |
335 | may have included an init script which automates the loading | |
336 | of the needed kernel module, eliminating a need to manually | |
337 | configure this step. <indexterm> | |
338 | <primary>AFS server partition</primary> | |
339 | ||
340 | <secondary>mounted on /vicep directory</secondary> | |
341 | </indexterm> <indexterm> | |
342 | <primary>partition</primary> | |
343 | ||
344 | <see>AFS server partition</see> | |
345 | </indexterm> <indexterm> | |
346 | <primary>logical volume</primary> | |
347 | ||
348 | <see>AFS server partition</see> | |
349 | </indexterm> <indexterm> | |
350 | <primary>requirements</primary> | |
351 | ||
352 | <secondary>AFS server partition name and location</secondary> | |
353 | </indexterm> <indexterm> | |
354 | <primary>naming conventions for AFS server partition</primary> | |
355 | </indexterm> <indexterm> | |
356 | <primary>vicep<emphasis>xx</emphasis> directory</primary> | |
357 | ||
358 | <see>AFS server partition</see> | |
359 | </indexterm> <indexterm> | |
360 | <primary>directories</primary> | |
361 | ||
362 | <secondary>/vicep<emphasis>xx</emphasis></secondary> | |
363 | ||
364 | <see>AFS server partition</see> | |
365 | </indexterm></para> | |
366 | </listitem> | |
367 | ||
368 | <listitem> | |
369 | <para>Configure server partitions or logical volumes to house AFS volumes.</para> | |
370 | ||
371 | <para>Every AFS file server machine should have at least one partition or logical volume dedicated to storing AFS volumes | |
372 | (for convenience, the documentation hereafter refers to partitions only). Each server partition is mounted at a directory | |
373 | named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where <replaceable>xx</replaceable> is one or | |
374 | two lowercase letters. By convention, the first 26 partitions are mounted on the directories called <emphasis | |
375 | role="bold">/vicepa</emphasis> through <emphasis role="bold">/vicepz</emphasis>, the 27th one is mounted on the <emphasis | |
376 | role="bold">/vicepaa</emphasis> directory, and so on through <emphasis role="bold">/vicepaz</emphasis> and <emphasis | |
377 | role="bold">/vicepba</emphasis>, continuing up to the index corresponding to the maximum number of server partitions | |
378 | supported in the current version of AFS (which is specified in the <emphasis>OpenAFS Release Notes</emphasis>).</para> | |
379 | ||
380 | <para>The <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server | |
381 | machine's root directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is | |
382 | not an acceptable directory location). | |
383 | ||
384 | The <emphasis role="bold">fileserver</emphasis> will refuse to | |
385 | mount | |
386 | any <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> | |
387 | folders that are not separate partitions without additional | |
388 | configuration. </para> | |
389 | ||
390 | <warning> | |
391 | <para>The separate partition requirement may be overridden by | |
392 | creating a file named | |
393 | <emphasis role="bold">/vicep<replaceable>xx</replaceable>/AlwaysAttach</emphasis>; | |
394 | however, mixed-use partitions, whether cache or fileserver, | |
395 | have the risk that a non-AFS use will fill the partition and | |
396 | not leave enough free space for AFS. Even though it is | |
397 | allowed, be wary of configuring a mixed-use partition | |
398 | without understanding the ramifications of doing so with the | |
399 | workload on your filesystem. | |
400 | <indexterm> | |
401 | <primary>AFS server partition</primary> | |
402 | <secondary>AlwaysAttach</secondary> | |
403 | </indexterm> | |
404 | </para> | |
405 | </warning> | |
406 | ||
407 | <para>You can also add or remove server partitions on an existing file server machine. For instructions, see the chapter | |
408 | in the <emphasis>OpenAFS Administration Guide</emphasis> about maintaining server machines.</para> | |
409 | ||
410 | <note> | |
411 | <para>Not all file system types supported by an operating system are necessarily supported as AFS server partitions. For | |
412 | possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para> | |
413 | </note> | |
414 | </listitem> | |
415 | ||
416 | <listitem> | |
417 | <para>On (rare) system types using the <emphasis role="bold">inode</emphasis> storage format, install and configure a modified <emphasis role="bold">fsck</emphasis> program which | |
418 | recognizes the structures that the File Server uses to organize volume data on AFS server partitions. The <emphasis | |
419 | role="bold">fsck</emphasis> program provided with the operating system does not understand the AFS data structures, and so | |
420 | removes them to the <emphasis role="bold">lost+found</emphasis> directory.</para> | |
421 | </listitem> | |
422 | ||
423 | <listitem> | |
424 | <para>If the machine is to remain an AFS client machine, modify the machine's authentication system so that users obtain | |
425 | an AFS token as they log into the local file system. Using AFS is simpler and more convenient for your users if you make | |
426 | the modifications on all client machines. Otherwise, users must perform a two or three step login procedure (login to the local | |
427 | system, then obtain Kerberos credentials, and then issue the <emphasis role="bold">aklog</emphasis> command). For further discussion of AFS | |
428 | authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration and | |
429 | administration issues.</para> | |
430 | </listitem> | |
431 | </itemizedlist></para> | |
432 | ||
433 | <para>To continue, proceed to the appropriate section: <itemizedlist> | |
434 | <listitem> | |
435 | <para><link linkend="HDRWQ41">Getting Started on Linux Systems</link></para> | |
436 | </listitem> | |
437 | ||
438 | <listitem> | |
439 | <para><link linkend="HDRWQ45">Getting Started on Solaris Systems</link></para> | |
440 | </listitem> | |
441 | </itemizedlist></para> | |
442 | </sect1> | |
443 | ||
444 | <sect1 id="HDRWQ41"> | |
445 | <title>Getting Started on Linux Systems</title> | |
446 | ||
447 | <indexterm> | |
448 | <primary>replacing fsck program</primary> | |
449 | ||
450 | <secondary>not necessary on Linux</secondary> | |
451 | </indexterm> | |
452 | ||
453 | <indexterm> | |
454 | <primary>fsck program</primary> | |
455 | ||
456 | <secondary>on first AFS machine</secondary> | |
457 | ||
458 | <tertiary>Linux</tertiary> | |
459 | </indexterm> | |
460 | ||
461 | <indexterm> | |
462 | <primary>first AFS machine</primary> | |
463 | ||
464 | <secondary>fsck program</secondary> | |
465 | ||
466 | <tertiary>on Linux</tertiary> | |
467 | </indexterm> | |
468 | ||
469 | <indexterm> | |
470 | <primary>Linux</primary> | |
471 | ||
472 | <secondary>fsck program replacement not necessary</secondary> | |
473 | </indexterm> | |
474 | ||
475 | <para>Since this guide was originally written, the procedure for starting | |
476 | OpenAFS has diverged significantly between different Linux distributions. | |
477 | The instructions that follow are appropriate for both the Fedora and | |
478 | RedHat Enterprise Linux packages distributed by OpenAFS. Additional | |
479 | instructions are provided for those building from source.</para> | |
480 | ||
481 | <para>Begin by running the AFS client startup scripts, which call the | |
482 | <emphasis role="bold">modprobe</emphasis> program to dynamically | |
483 | load the AFS modifications into the kernel. Then create partitions for | |
484 | storing AFS volumes. You do not need to replace the Linux <emphasis | |
485 | role="bold">fsck</emphasis> program. If the machine is to remain an | |
486 | AFS client machine, incorporate AFS into the machine's Pluggable | |
487 | Authentication Module (PAM) scheme. <indexterm> | |
488 | <primary>incorporating AFS kernel extensions</primary> | |
489 | ||
490 | <secondary>first AFS machine</secondary> | |
491 | ||
492 | <tertiary>Linux</tertiary> | |
493 | </indexterm> <indexterm> | |
494 | <primary>AFS kernel extensions</primary> | |
495 | ||
496 | <secondary>on first AFS machine</secondary> | |
497 | ||
498 | <tertiary>Linux</tertiary> | |
499 | </indexterm> <indexterm> | |
500 | <primary>first AFS machine</primary> | |
501 | ||
502 | <secondary>AFS kernel extensions</secondary> | |
503 | ||
504 | <tertiary>on Linux</tertiary> | |
505 | </indexterm> <indexterm> | |
506 | <primary>Linux</primary> | |
507 | ||
508 | <secondary>AFS kernel extensions</secondary> | |
509 | ||
510 | <tertiary>on first AFS machine</tertiary> | |
511 | </indexterm></para> | |
512 | ||
513 | <sect2 id="HDRWQ42"> | |
514 | <title>Loading AFS into the Linux Kernel</title> | |
515 | ||
516 | <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support | |
517 | incorporation of AFS modifications during a kernel build.</para> | |
518 | ||
519 | <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine | |
520 | reboots, so your distribution's AFS initialization script invokes it automatically. The script also includes | |
521 | commands that select the appropriate AFS library file automatically. In this section you run the script.</para> | |
522 | ||
523 | <para>In later sections you verify that the script correctly initializes all AFS components, then activate a configuration | |
524 | variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para> | |
525 | ||
526 | <para>The procedure for starting up OpenAFS depends upon your distribution</para> | |
527 | <sect3> | |
528 | <title>Fedora and RedHat Enterprise Linux</title> | |
529 | <para>OpenAFS provides RPMS for all current Fedora and | |
530 | RedHat Enterprise Linux (RHEL) releases prior to EL7 on the | |
531 | OpenAFS web site and the OpenAFS yum repository. | |
532 | <orderedlist> | |
533 | <listitem> | |
534 | <para>Browse to | |
535 | http://dl.openafs.org/dl/openafs/<replaceable>VERSION</replaceable>, | |
536 | where VERSION is the latest stable release of | |
537 | OpenAFS for Unix. Download the | |
538 | openafs-repository-<replaceable>VERSION</replaceable>.noarch.rpm | |
539 | file for Fedora systems or the | |
540 | openafs-repository-rhel-<replaceable>VERSION</replaceable>.noarch.rpm | |
541 | file for RedHat-based systems. | |
542 | </para> | |
543 | </listitem> | |
544 | <listitem> | |
545 | <para>Install the downloaded RPM file using the following command: | |
546 | <programlisting> | |
547 | # rpm -U openafs-repository*.rpm | |
548 | </programlisting> | |
549 | </para> | |
550 | </listitem> | |
551 | <listitem> | |
552 | <para>Install the RPM set for your operating system using the yum command as follows: | |
553 | <programlisting> | |
554 | # yum -y install openafs-client openafs-server openafs-krb5 kmod-openafs | |
555 | </programlisting> | |
556 | ||
557 | </para> | |
558 | <para>Alternatively, you may use dynamically-compiled kernel | |
559 | modules if you have the kernel headers, a compiler, and the | |
560 | dkms package from | |
561 | <ulink url="http://fedoraproject.org/wiki/EPEL"><citetitle>EPEL</citetitle></ulink> installed. | |
562 | ||
563 | </para> | |
564 | <para>To use dynamically-compiled kernel modules instead of statically compiled modules, use the following command instead of the kmod-openafs as shown above: | |
565 | <programlisting> | |
566 | # yum install openafs-client openafs-server openafs-krb5 dkms-openafs | |
567 | </programlisting> | |
568 | </para> | |
569 | </listitem> | |
570 | <!-- If you do this with current RHEL and Fedora releases you end up with | |
571 | a dynroot'd client running - this breaks setting up the root.afs volume | |
572 | as described later in this guide | |
573 | <listitem> | |
574 | <para>Run the AFS initialization script to load AFS extensions into | |
575 | the kernel. You can ignore any error messages about the inability | |
576 | to start the BOS Server or the Cache Manager or AFS client.</para> | |
577 | <programlisting> | |
578 | # <emphasis role="bold">/etc/rc.d/init.d/openafs-client start</emphasis> | |
579 | </programlisting> | |
580 | </listitem> | |
581 | --> | |
582 | </orderedlist> | |
583 | </para> | |
584 | </sect3> | |
585 | <sect3> | |
586 | <title>Debian and Ubuntu Linux</title> | |
587 | <para>OpenAFS is available as binary packages from the Debian | |
588 | linux distribution and its derivatives such as Ubuntu. | |
589 | <orderedlist> | |
590 | <listitem> | |
591 | <para>Install the client and server packages using the following command: | |
592 | <programlisting> | |
593 | # apt-get install openafs-client openafs-modules-dkms openafs-krb5 \ | |
594 | openafs-fileserver openafs-dbserver | |
595 | </programlisting> | |
596 | You will be prompted by debconf to select your cell name and | |
597 | the size of your local cache. | |
598 | </para> | |
599 | </listitem> | |
600 | </orderedlist> | |
601 | </para> | |
602 | <para>The Debian package also includes helper scripts | |
603 | <literal>afs-newcell</literal> and <literal>afs-rootvol</literal>, | |
604 | which can automate much of the remainder of this document. | |
605 | </para> | |
606 | </sect3> | |
607 | <sect3> | |
608 | <title>Systems built from source</title> | |
609 | <para>If you are running a system where | |
610 | you have built the system from | |
611 | source yourself, you need to install the relevant components by hand: | |
612 | </para> | |
613 | <orderedlist> | |
614 | ||
615 | <listitem> | |
616 | <para>Unpack the distribution tarball. The examples below assume | |
617 | that you have extracted and built OpenAFS in the | |
618 | <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you | |
619 | pick a different location, substitute this in all of the following | |
620 | examples. Once you have compiled the distribution, | |
621 | change to the source directory as indicated. | |
622 | <programlisting> | |
623 | # <emphasis role="bold">cd /tmp/afsdist</emphasis> | |
624 | </programlisting></para> | |
625 | </listitem> | |
626 | ||
627 | <listitem> | |
628 | <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory. | |
629 | The filenames for the libraries have the format <emphasis | |
630 | role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where | |
631 | <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in | |
632 | the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor | |
633 | kernel. <programlisting> | |
634 | # <emphasis role="bold">mkdir -p /usr/vice/etc/modload</emphasis> | |
635 | # <emphasis role="bold">cp -rp src/libafs/*.ko /usr/vice/etc/modload</emphasis> | |
636 | </programlisting></para> | |
637 | </listitem> | |
638 | ||
639 | <listitem> | |
640 | <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis | |
641 | role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis> | |
642 | extension as you copy the script. <programlisting> | |
643 | # <emphasis role="bold">cp -p src/afsd/afs.rc.linux /etc/rc.d/init.d/afs</emphasis> | |
644 | </programlisting></para> | |
645 | </listitem> | |
646 | ||
647 | </orderedlist> | |
648 | ||
649 | <indexterm> | |
650 | <primary>configuring</primary> | |
651 | ||
652 | <secondary>AFS server partition on first AFS machine</secondary> | |
653 | ||
654 | <tertiary>Linux</tertiary> | |
655 | </indexterm> | |
656 | ||
657 | <indexterm> | |
658 | <primary>AFS server partition</primary> | |
659 | ||
660 | <secondary>configuring on first AFS machine</secondary> | |
661 | ||
662 | <tertiary>Linux</tertiary> | |
663 | </indexterm> | |
664 | ||
665 | <indexterm> | |
666 | <primary>first AFS machine</primary> | |
667 | ||
668 | <secondary>AFS server partition</secondary> | |
669 | ||
670 | <tertiary>on Linux</tertiary> | |
671 | </indexterm> | |
672 | ||
673 | <indexterm> | |
674 | <primary>Linux</primary> | |
675 | ||
676 | <secondary>AFS server partition</secondary> | |
677 | ||
678 | <tertiary>on first AFS machine</tertiary> | |
679 | </indexterm> | |
680 | </sect3> | |
681 | </sect2> | |
682 | ||
683 | <sect2 id="HDRWQ43"> | |
684 | <title>Configuring Server Partitions on Linux Systems</title> | |
685 | ||
686 | <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each | |
687 | server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where | |
688 | <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis | |
689 | role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root | |
690 | directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable | |
691 | directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>. | |
692 | <orderedlist> | |
693 | <listitem> | |
694 | <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server | |
695 | partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting> | |
696 | # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable> | |
697 | </programlisting></para> | |
698 | </listitem> | |
699 | ||
700 | <listitem> | |
701 | <para>Add a line with the following format to the file systems registry file, <emphasis | |
702 | role="bold">/etc/fstab</emphasis>, for each directory just created. The entry maps the directory name to the disk | |
703 | partition to be mounted on it. <programlisting> | |
704 | /dev/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> ext2 defaults 0 2 | |
705 | </programlisting></para> | |
706 | ||
707 | <para>The following is an example for the first partition being configured.</para> | |
708 | ||
709 | <programlisting> | |
710 | /dev/sda8 /vicepa ext2 defaults 0 2 | |
711 | </programlisting> | |
712 | </listitem> | |
713 | ||
714 | <listitem> | |
715 | <para>Create a file system on each partition that is to be mounted at a <emphasis | |
716 | role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but | |
717 | consult the Linux documentation for more information. <programlisting> | |
718 | # <emphasis role="bold">mkfs -v /dev/</emphasis><replaceable>disk</replaceable> | |
719 | </programlisting></para> | |
720 | </listitem> | |
721 | ||
722 | <listitem> | |
723 | <para>Mount each partition by issuing either the <emphasis role="bold">mount -a</emphasis> command to mount all | |
724 | partitions at once or the <emphasis role="bold">mount</emphasis> command to mount each partition in turn.</para> | |
725 | </listitem> | |
726 | ||
727 | <listitem> | |
728 | <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link | |
729 | linkend="HDRWQ44">Enabling AFS Login on Linux Systems</link>. Otherwise, proceed to <link linkend="HDRWQ50">Starting the | |
730 | BOS Server</link>.</para> | |
731 | </listitem> | |
732 | </orderedlist></para> | |
733 | ||
734 | <indexterm> | |
735 | <primary>enabling AFS login</primary> | |
736 | ||
737 | <secondary>file server machine</secondary> | |
738 | ||
739 | <tertiary>Linux</tertiary> | |
740 | </indexterm> | |
741 | ||
742 | <indexterm> | |
743 | <primary>AFS login</primary> | |
744 | ||
745 | <secondary>on file server machine</secondary> | |
746 | ||
747 | <tertiary>Linux</tertiary> | |
748 | </indexterm> | |
749 | ||
750 | <indexterm> | |
751 | <primary>first AFS machine</primary> | |
752 | ||
753 | <secondary>AFS login</secondary> | |
754 | ||
755 | <tertiary>on Linux</tertiary> | |
756 | </indexterm> | |
757 | ||
758 | <indexterm> | |
759 | <primary>Linux</primary> | |
760 | ||
761 | <secondary>AFS login</secondary> | |
762 | ||
763 | <tertiary>on file server machine</tertiary> | |
764 | </indexterm> | |
765 | ||
766 | <indexterm> | |
767 | <primary>PAM</primary> | |
768 | ||
769 | <secondary>on Linux</secondary> | |
770 | ||
771 | <tertiary>file server machine</tertiary> | |
772 | </indexterm> | |
773 | </sect2> | |
774 | ||
775 | <sect2 id="HDRWQ44"> | |
776 | <title>Enabling AFS Login on Linux Systems</title> | |
777 | ||
778 | <note> | |
779 | <para>If you plan to remove client functionality from this machine | |
780 | after completing the installation, skip this section and proceed | |
781 | to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para> | |
782 | </note> | |
783 | ||
784 | <para>At this point you incorporate AFS into the operating system's | |
785 | Pluggable Authentication Module (PAM) scheme. PAM integrates all | |
786 | authentication mechanisms on the machine, including login, to provide | |
787 | the security infrastructure for authenticated access to and from the | |
788 | machine.</para> | |
789 | ||
790 | <para>You should first configure your system to obtain Kerberos v5 | |
791 | tickets as part of the authentication process, and then run an AFS PAM | |
792 | module to obtain tokens from those tickets after authentication. Many | |
793 | Linux distributions come with a Kerberos v5 PAM module (usually called | |
794 | pam-krb5 or pam_krb5), or you can download and install <ulink | |
795 | url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's | |
796 | Kerberos v5 PAM module</ulink>, which is tested regularly with AFS. | |
797 | See the instructions of whatever PAM module you use for how to | |
798 | configure it.</para> | |
799 | ||
800 | <para>Some Kerberos v5 PAM modules do come with native AFS support | |
801 | (usually requiring the Heimdal Kerberos implementation rather than the | |
802 | MIT Kerberos implementation). If you are using one of those PAM | |
803 | modules, you can configure it to obtain AFS tokens. It's more common, | |
804 | however, to separate the AFS token acquisition into a separate PAM | |
805 | module.</para> | |
806 | ||
807 | <para>The recommended AFS PAM module is <ulink | |
808 | url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ | |
809 | Allbery's pam-afs-session module</ulink>. It should work with any of | |
810 | the Kerberos v5 PAM modules. To add it to the PAM configuration, you | |
811 | often only need to add configuration to the session group:</para> | |
812 | ||
813 | <example> | |
814 | <title>Linux PAM session example</title> | |
815 | <literallayout>session required pam_afs_session.so</literallayout> | |
816 | </example> | |
817 | ||
818 | <para>If you also want to obtain AFS tokens for <command>scp</command> | |
819 | and similar commands that don't open a session, you will also need to | |
820 | add the AFS PAM module to the auth group so that the PAM | |
821 | <function>setcred</function> call will obtain tokens. The | |
822 | <literal>pam_afs_session</literal> module will always return success | |
823 | for authentication so that it can be added to the auth group only for | |
824 | <function>setcred</function>, so make sure that it's not marked as | |
825 | <literal>sufficient</literal>.</para> | |
826 | ||
827 | <example> | |
828 | <title>Linux PAM auth example</title> | |
829 | <literallayout>auth [success=ok default=1] pam_krb5.so | |
830 | auth [default=done] pam_afs_session.so | |
831 | auth required pam_unix.so try_first_pass</literallayout> | |
832 | </example> | |
833 | ||
834 | <para>This example will work if you want to try Kerberos v5 first and | |
835 | then fall back to regular Unix authentication. | |
836 | <literal>success=ok</literal> for the Kerberos PAM module followed by | |
837 | <literal>default=done</literal> for the AFS PAM module will cause a | |
838 | successful Kerberos login to run the AFS PAM module and then skip the | |
839 | Unix authentication module. <literal>default=1</literal> on the | |
840 | Kerberos PAM module causes failure of that module to skip the next | |
841 | module (the AFS PAM module) and fall back to the Unix module. If you | |
842 | want to try Unix authentication first and rearrange the order, be sure | |
843 | to use <literal>default=die</literal> instead.</para> | |
844 | ||
845 | <para>The PAM configuration is stored in different places in different | |
846 | Linux distributions. On Red Hat, look in | |
847 | <filename>/etc/pam.d/system-auth</filename>. On Debian and | |
848 | derivatives, look in <filename>/etc/pam.d/common-session</filename> | |
849 | and <filename>/etc/pam.d/common-auth</filename>.</para> | |
850 | ||
851 | <para>For additional configuration examples and the configuration | |
852 | options of the AFS PAM module, see its documentation. For more | |
853 | details on the available options for the PAM configuration, see the | |
854 | Linux PAM documentation.</para> | |
855 | ||
856 | <para>Sites which still require the deprecated | |
857 | <command>kaserver</command> or | |
858 | external Kerberos v4 authentication should consult <link | |
859 | linkend="KAS015">Enabling kaserver based AFS Login on Linux | |
860 | Systems</link> for details of how to enable AFS login on Linux.</para> | |
861 | ||
862 | <para>Proceed to <link linkend="HDRWQ50">Starting the BOS | |
863 | Server</link> (or if referring to these instructions while installing | |
864 | an additional file server machine, return to <link | |
865 | linkend="HDRWQ108">Starting Server Programs</link>).</para> | |
866 | </sect2> | |
867 | </sect1> | |
868 | ||
869 | <sect1 id="HDRWQ45"> | |
870 | <title>Getting Started on Solaris Systems</title> | |
871 | ||
872 | <para>Begin by running the AFS initialization script to call the <emphasis role="bold">modload</emphasis> program distributed by | |
873 | Sun Microsystems, which dynamically loads AFS modifications into the kernel. Then create partitions for storing AFS volumes, and | |
874 | install and configure the AFS-modified <emphasis role="bold">fsck</emphasis> program to run on AFS server partitions. If the | |
875 | machine is to remain an AFS client machine, incorporate AFS into the machine's Pluggable Authentication Module (PAM) scheme. | |
876 | <indexterm> | |
877 | <primary>incorporating AFS kernel extensions</primary> | |
878 | ||
879 | <secondary>first AFS machine</secondary> | |
880 | ||
881 | <tertiary>Solaris</tertiary> | |
882 | </indexterm> <indexterm> | |
883 | <primary>AFS kernel extensions</primary> | |
884 | ||
885 | <secondary>on first AFS machine</secondary> | |
886 | ||
887 | <tertiary>Solaris</tertiary> | |
888 | </indexterm> <indexterm> | |
889 | <primary>first AFS machine</primary> | |
890 | ||
891 | <secondary>AFS kernel extensions</secondary> | |
892 | ||
893 | <tertiary>on Solaris</tertiary> | |
894 | </indexterm> <indexterm> | |
895 | <primary>Solaris</primary> | |
896 | ||
897 | <secondary>AFS kernel extensions</secondary> | |
898 | ||
899 | <tertiary>on first AFS machine</tertiary> | |
900 | </indexterm></para> | |
901 | ||
902 | <sect2 id="HDRWQ46"> | |
903 | <title>Loading AFS into the Solaris Kernel</title> | |
904 | ||
905 | <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for | |
906 | Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para> | |
907 | ||
908 | <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine | |
909 | reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the | |
910 | appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then | |
911 | run the script.</para> | |
912 | ||
913 | <para>In later sections you verify that the script correctly initializes all AFS components, then create the links that | |
914 | incorporate AFS into the Solaris startup and shutdown sequence. <orderedlist> | |
915 | <listitem> | |
916 | <para>Unpack the OpenAFS Solaris distribution tarball. The examples | |
917 | below assume that you have unpacked the files into the | |
918 | <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you | |
919 | pick a diferent location, substitute this in all of the following | |
920 | exmaples. Once you have unpacked the distribution, change directory | |
921 | as indicated. | |
922 | <programlisting> | |
923 | # <emphasis role="bold">cd /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</emphasis> | |
924 | </programlisting></para> | |
925 | </listitem> | |
926 | ||
927 | <listitem> | |
928 | <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis | |
929 | role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis> | |
930 | extension as you copy the script. <programlisting> | |
931 | # <emphasis role="bold">cp -p afs.rc /etc/init.d/afs</emphasis> | |
932 | </programlisting></para> | |
933 | </listitem> | |
934 | ||
935 | <listitem> | |
936 | <para>Copy the appropriate AFS kernel library file to the local file <emphasis | |
937 | role="bold">/kernel/fs/afs</emphasis>.</para> | |
938 | ||
939 | <para>If the machine is running Solaris 11 on the x86_64 platform:</para> | |
940 | ||
941 | <programlisting> | |
942 | # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis> | |
943 | </programlisting> | |
944 | ||
945 | <para>If the machine is running Solaris 10 on the x86_64 platform:</para> | |
946 | ||
947 | <programlisting> | |
948 | # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis> | |
949 | </programlisting> | |
950 | ||
951 | <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server | |
952 | functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para> | |
953 | ||
954 | <programlisting> | |
955 | # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis> | |
956 | </programlisting> | |
957 | ||
958 | <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS | |
959 | server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para> | |
960 | ||
961 | <programlisting> | |
962 | # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis> | |
963 | </programlisting> | |
964 | ||
965 | <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the | |
966 | <emphasis role="bold">nfsd</emphasis> process is running:</para> | |
967 | ||
968 | <programlisting> | |
969 | # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis> | |
970 | </programlisting> | |
971 | ||
972 | <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server | |
973 | functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para> | |
974 | ||
975 | <programlisting> | |
976 | # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis> | |
977 | </programlisting> | |
978 | </listitem> | |
979 | ||
980 | <listitem> | |
981 | <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages | |
982 | about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting> | |
983 | # <emphasis role="bold">/etc/init.d/afs start</emphasis> | |
984 | </programlisting></para> | |
985 | ||
986 | <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis | |
987 | role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start | |
988 | using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis> | |
989 | after the reboot and run the initialization script again. This time the required entry exists in the <emphasis | |
990 | role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para> | |
991 | ||
992 | <programlisting> | |
993 | login: <emphasis role="bold">root</emphasis> | |
994 | Password: <replaceable>root_password</replaceable> | |
995 | # <emphasis role="bold">/etc/init.d/afs start</emphasis> | |
996 | </programlisting> | |
997 | </listitem> | |
998 | </orderedlist></para> | |
999 | ||
1000 | <indexterm> | |
1001 | <primary>replacing fsck program</primary> | |
1002 | ||
1003 | <secondary>first AFS machine</secondary> | |
1004 | ||
1005 | <tertiary>Solaris</tertiary> | |
1006 | </indexterm> | |
1007 | ||
1008 | <indexterm> | |
1009 | <primary>fsck program</primary> | |
1010 | ||
1011 | <secondary>on first AFS machine</secondary> | |
1012 | ||
1013 | <tertiary>Solaris</tertiary> | |
1014 | </indexterm> | |
1015 | ||
1016 | <indexterm> | |
1017 | <primary>first AFS machine</primary> | |
1018 | ||
1019 | <secondary>fsck program</secondary> | |
1020 | ||
1021 | <tertiary>on Solaris</tertiary> | |
1022 | </indexterm> | |
1023 | ||
1024 | <indexterm> | |
1025 | <primary>Solaris</primary> | |
1026 | ||
1027 | <secondary>fsck program</secondary> | |
1028 | ||
1029 | <tertiary>on first AFS machine</tertiary> | |
1030 | </indexterm> | |
1031 | </sect2> | |
1032 | ||
1033 | <sect2 id="HDRWQ47"> | |
1034 | <title>Configuring the AFS-modified fsck Program on Solaris Systems</title> | |
1035 | ||
1036 | <para>In this section, you make modifications to guarantee that the appropriate <emphasis role="bold">fsck</emphasis> program | |
1037 | runs on AFS server partitions. The <emphasis role="bold">fsck</emphasis> program provided with the operating system must never | |
1038 | run on AFS server partitions. Because it does not recognize the structures that the File Server uses to organize volume data, | |
1039 | it removes all of the data. To repeat:</para> | |
1040 | ||
1041 | <para><emphasis role="bold">Never run the standard fsck program on AFS server partitions. It discards AFS volumes.</emphasis> | |
1042 | <orderedlist> | |
1043 | <listitem> | |
1044 | <para>Create the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory to house the AFS-modified <emphasis | |
1045 | role="bold">fsck</emphasis> program and related files. <programlisting> | |
1046 | # <emphasis role="bold">mkdir /usr/lib/fs/afs</emphasis> | |
1047 | # <emphasis role="bold">cd /usr/lib/fs/afs</emphasis> | |
1048 | </programlisting></para> | |
1049 | </listitem> | |
1050 | ||
1051 | <listitem> | |
1052 | <para>Copy the <emphasis role="bold">vfsck</emphasis> binary to the newly created directory, changing the name as you do | |
1053 | so. <programlisting> | |
1054 | # <emphasis role="bold">cp /tmp/afsdist/sun4x_56/dest/root.server/etc/vfsck fsck</emphasis> | |
1055 | </programlisting></para> | |
1056 | </listitem> | |
1057 | ||
1058 | <listitem> | |
1059 | <para>Working in the <emphasis role="bold">/usr/lib/fs/afs</emphasis> directory, create the following links to Solaris | |
1060 | libraries: <programlisting> | |
1061 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/clri</emphasis> | |
1062 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/df</emphasis> | |
1063 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/edquota</emphasis> | |
1064 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ff</emphasis> | |
1065 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsdb</emphasis> | |
1066 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fsirand</emphasis> | |
1067 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/fstyp</emphasis> | |
1068 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/labelit</emphasis> | |
1069 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/lockfs</emphasis> | |
1070 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mkfs</emphasis> | |
1071 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/mount</emphasis> | |
1072 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ncheck</emphasis> | |
1073 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/newfs</emphasis> | |
1074 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quot</emphasis> | |
1075 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quota</emphasis> | |
1076 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaoff</emphasis> | |
1077 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/quotaon</emphasis> | |
1078 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/repquota</emphasis> | |
1079 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/tunefs</emphasis> | |
1080 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsdump</emphasis> | |
1081 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/ufsrestore</emphasis> | |
1082 | # <emphasis role="bold">ln -s /usr/lib/fs/ufs/volcopy</emphasis> | |
1083 | </programlisting></para> | |
1084 | </listitem> | |
1085 | ||
1086 | <listitem> | |
1087 | <para>Append the following line to the end of the file <emphasis role="bold">/etc/dfs/fstypes</emphasis>. | |
1088 | <programlisting> | |
1089 | afs AFS Utilities | |
1090 | </programlisting></para> | |
1091 | </listitem> | |
1092 | ||
1093 | <listitem> | |
1094 | <para>Edit the <emphasis role="bold">/sbin/mountall</emphasis> file, making two changes. <itemizedlist> | |
1095 | <listitem> | |
1096 | <para>Add an entry for AFS to the <computeroutput>case</computeroutput> statement for option 2, so that it reads | |
1097 | as follows: <programlisting> | |
1098 | case "$2" in | |
1099 | ufs) foptions="-o p" | |
1100 | ;; | |
1101 | afs) foptions="-o p" | |
1102 | ;; | |
1103 | s5) foptions="-y -t /var/tmp/tmp$$ -D" | |
1104 | ;; | |
1105 | *) foptions="-y" | |
1106 | ;; | |
1107 | </programlisting></para> | |
1108 | </listitem> | |
1109 | ||
1110 | <listitem> | |
1111 | <para>Edit the file so that all AFS and UFS partitions are checked in parallel. Replace the following section of | |
1112 | code: <programlisting> | |
1113 | # For fsck purposes, we make a distinction between ufs and | |
1114 | # other file systems | |
1115 | # | |
1116 | if [ "$fstype" = "ufs" ]; then | |
1117 | ufs_fscklist="$ufs_fscklist $fsckdev" | |
1118 | saveentry $fstype "$OPTIONS" $special $mountp | |
1119 | continue | |
1120 | fi | |
1121 | </programlisting></para> | |
1122 | ||
1123 | <para>with the following section of code:</para> | |
1124 | ||
1125 | <programlisting> | |
1126 | # For fsck purposes, we make a distinction between ufs/afs | |
1127 | # and other file systems. | |
1128 | # | |
1129 | if [ "$fstype" = "ufs" -o "$fstype" = "afs" ]; then | |
1130 | ufs_fscklist="$ufs_fscklist $fsckdev" | |
1131 | saveentry $fstype "$OPTIONS" $special $mountp | |
1132 | continue | |
1133 | fi | |
1134 | </programlisting> | |
1135 | </listitem> | |
1136 | </itemizedlist></para> | |
1137 | </listitem> | |
1138 | </orderedlist></para> | |
1139 | ||
1140 | <indexterm> | |
1141 | <primary>configuring</primary> | |
1142 | ||
1143 | <secondary>AFS server partition on first AFS machine</secondary> | |
1144 | ||
1145 | <tertiary>Solaris</tertiary> | |
1146 | </indexterm> | |
1147 | ||
1148 | <indexterm> | |
1149 | <primary>AFS server partition</primary> | |
1150 | ||
1151 | <secondary>configuring on first AFS machine</secondary> | |
1152 | ||
1153 | <tertiary>Solaris</tertiary> | |
1154 | </indexterm> | |
1155 | ||
1156 | <indexterm> | |
1157 | <primary>first AFS machine</primary> | |
1158 | ||
1159 | <secondary>AFS server partition</secondary> | |
1160 | ||
1161 | <tertiary>on Solaris</tertiary> | |
1162 | </indexterm> | |
1163 | ||
1164 | <indexterm> | |
1165 | <primary>Solaris</primary> | |
1166 | ||
1167 | <secondary>AFS server partition</secondary> | |
1168 | ||
1169 | <tertiary>on first AFS machine</tertiary> | |
1170 | </indexterm> | |
1171 | </sect2> | |
1172 | ||
1173 | <sect2 id="HDRWQ48"> | |
1174 | <title>Configuring Server Partitions on Solaris Systems</title> | |
1175 | ||
1176 | <para>Every AFS file server machine must have at least one partition or logical volume dedicated to storing AFS volumes. Each | |
1177 | server partition is mounted at a directory named <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable>, where | |
1178 | <replaceable>xx</replaceable> is one or two lowercase letters. The <emphasis | |
1179 | role="bold">/vicep</emphasis><replaceable>xx</replaceable> directories must reside in the file server machine's root | |
1180 | directory, not in one of its subdirectories (for example, <emphasis role="bold">/usr/vicepa</emphasis> is not an acceptable | |
1181 | directory location). For additional information, see <link linkend="HDRWQ20">Performing Platform-Specific Procedures</link>. | |
1182 | <orderedlist> | |
1183 | <listitem> | |
1184 | <para>Create a directory called <emphasis role="bold">/vicep</emphasis><replaceable>xx</replaceable> for each AFS server | |
1185 | partition you are configuring (there must be at least one). Repeat the command for each partition. <programlisting> | |
1186 | # <emphasis role="bold">mkdir /vicep</emphasis><replaceable>xx</replaceable> | |
1187 | </programlisting></para> | |
1188 | </listitem> | |
1189 | ||
1190 | <listitem> | |
1191 | <para>Add a line with the following format to the file systems registry file, <emphasis | |
1192 | role="bold">/etc/vfstab</emphasis>, for each partition to be mounted on a directory created in the previous step. Note | |
1193 | the value <computeroutput>afs</computeroutput> in the fourth field, which tells Solaris to use the AFS-modified | |
1194 | <emphasis role="bold">fsck</emphasis> program on this partition. <programlisting> | |
1195 | /dev/dsk/<replaceable>disk</replaceable> /dev/rdsk/<replaceable>disk</replaceable> /vicep<replaceable>xx</replaceable> afs <replaceable>boot_order</replaceable> yes | |
1196 | </programlisting></para> | |
1197 | ||
1198 | <para>The following is an example for the first partition being configured.</para> | |
1199 | ||
1200 | <programlisting> | |
1201 | /dev/dsk/c0t6d0s1 /dev/rdsk/c0t6d0s1 /vicepa afs 3 yes | |
1202 | </programlisting> | |
1203 | </listitem> | |
1204 | ||
1205 | <listitem> | |
1206 | <para>Create a file system on each partition that is to be mounted at a <emphasis | |
1207 | role="bold">/vicep</emphasis><replaceable>xx</replaceable> directory. The following command is probably appropriate, but | |
1208 | consult the Solaris documentation for more information. <programlisting> | |
1209 | # <emphasis role="bold">newfs -v /dev/rdsk/</emphasis><replaceable>disk</replaceable> | |
1210 | </programlisting></para> | |
1211 | </listitem> | |
1212 | ||
1213 | <listitem> | |
1214 | <para>Issue the <emphasis role="bold">mountall</emphasis> command to mount all partitions at once.</para> | |
1215 | </listitem> | |
1216 | ||
1217 | <listitem> | |
1218 | <para>If you plan to retain client functionality on this machine after completing the installation, proceed to <link | |
1219 | linkend="HDRWQ49">Enabling AFS Login and Editing the File Systems Clean-up Script on Solaris Systems</link>. Otherwise, | |
1220 | proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para> | |
1221 | </listitem> | |
1222 | </orderedlist></para> | |
1223 | </sect2> | |
1224 | ||
1225 | <sect2 id="HDRWQ49"> | |
1226 | <title>Enabling AFS Login on Solaris Systems</title> | |
1227 | <indexterm> | |
1228 | <primary>enabling AFS login</primary> | |
1229 | ||
1230 | <secondary>file server machine</secondary> | |
1231 | ||
1232 | <tertiary>Solaris</tertiary> | |
1233 | </indexterm> | |
1234 | ||
1235 | <indexterm> | |
1236 | <primary>AFS login</primary> | |
1237 | ||
1238 | <secondary>on file server machine</secondary> | |
1239 | ||
1240 | <tertiary>Solaris</tertiary> | |
1241 | </indexterm> | |
1242 | ||
1243 | <indexterm> | |
1244 | <primary>first AFS machine</primary> | |
1245 | ||
1246 | <secondary>AFS login</secondary> | |
1247 | ||
1248 | <tertiary>on Solaris</tertiary> | |
1249 | </indexterm> | |
1250 | ||
1251 | <indexterm> | |
1252 | <primary>Solaris</primary> | |
1253 | ||
1254 | <secondary>AFS login</secondary> | |
1255 | ||
1256 | <tertiary>on file server machine</tertiary> | |
1257 | </indexterm> | |
1258 | ||
1259 | <indexterm> | |
1260 | <primary>PAM</primary> | |
1261 | ||
1262 | <secondary>on Solaris</secondary> | |
1263 | ||
1264 | <tertiary>file server machine</tertiary> | |
1265 | </indexterm> | |
1266 | ||
1267 | <note> | |
1268 | <para>If you plan to remove client functionality from this machine after completing the installation, skip this section and | |
1269 | proceed to <link linkend="HDRWQ50">Starting the BOS Server</link>.</para> | |
1270 | </note> | |
1271 | ||
1272 | <para>At this point you incorporate AFS into the operating system's | |
1273 | Pluggable Authentication Module (PAM) scheme. PAM integrates all | |
1274 | authentication mechanisms on the machine, including login, to provide | |
1275 | the security infrastructure for authenticated access to and from the | |
1276 | machine.</para> | |
1277 | ||
1278 | <para>Explaining PAM is beyond the scope of this document. It is | |
1279 | assumed that you understand the syntax and meanings of settings in the | |
1280 | PAM configuration file (for example, how the | |
1281 | <computeroutput>other</computeroutput> entry works, the effect of | |
1282 | marking an entry as <computeroutput>required</computeroutput>, | |
1283 | <computeroutput>optional</computeroutput>, or | |
1284 | <computeroutput>sufficient</computeroutput>, and so on).</para> | |
1285 | ||
1286 | <para>You should first configure your system to obtain Kerberos v5 | |
1287 | tickets as part of the authentication process, and then run an AFS PAM | |
1288 | module to obtain tokens from those tickets after authentication. | |
1289 | Current versions of Solaris come with a Kerberos v5 PAM module that | |
1290 | will work, or you can download and install <ulink | |
1291 | url="http://www.eyrie.org/~eagle/software/pam-krb5">Russ Allbery's | |
1292 | Kerberos v5 PAM module</ulink>, which is tested regularly with AFS. | |
1293 | See the instructions of whatever PAM module you use for how to | |
1294 | configure it.</para> | |
1295 | ||
1296 | <para>Some Kerberos v5 PAM modules do come with native AFS support | |
1297 | (usually requiring the Heimdal Kerberos implementation rather than the | |
1298 | MIT Kerberos implementation). If you are using one of those PAM | |
1299 | modules, you can configure it to obtain AFS tokens. It's more common, | |
1300 | however, to separate the AFS token acquisition into a separate PAM | |
1301 | module.</para> | |
1302 | ||
1303 | <para>The recommended AFS PAM module is <ulink | |
1304 | url="http://www.eyrie.org/~eagle/software/pam-afs-session/">Russ | |
1305 | Allbery's pam-afs-session module</ulink>. It should work with any of | |
1306 | the Kerberos v5 PAM modules. To add it to the PAM configuration, you | |
1307 | often only need to add configuration to the session group in | |
1308 | <filename>pam.conf</filename>:</para> | |
1309 | ||
1310 | <example> | |
1311 | <title>Solaris PAM session example</title> | |
1312 | <literallayout>login session required pam_afs_session.so</literallayout> | |
1313 | </example> | |
1314 | ||
1315 | <para>This example enables PAM authentication only for console login. | |
1316 | You may want to add a similar line for the ssh service and for any | |
1317 | other login service that you use, including possibly the | |
1318 | <literal>other</literal> service (which serves as a catch-all). You | |
1319 | may also want to add options to the AFS PAM session module | |
1320 | (particularly <literal>retain_after_close</literal>, which is | |
1321 | necessary for some versions of Solaris.</para> | |
1322 | ||
1323 | <para>For additional configuration examples and the configuration | |
1324 | options of the AFS PAM module, see its documentation. For more | |
1325 | details on the available options for the PAM configuration, see the | |
1326 | <filename>pam.conf</filename> manual page.</para> | |
1327 | ||
1328 | <para>Sites which still require <emphasis | |
1329 | role="bold">kaserver</emphasis> or external Kerberos v4 authentication | |
1330 | should consult <link linkend="KAS016">"Enabling kaserver based AFS | |
1331 | Login on Solaris Systems"</link> for details of how to enable AFS | |
1332 | login on Solaris.</para> | |
1333 | ||
1334 | <para>Proceed to <link linkend="HDRWQ49a">Editing the File Systems | |
1335 | Clean-up Script on Solaris Systems</link></para> | |
1336 | </sect2> | |
1337 | <sect2 id="HDRWQ49a"> | |
1338 | <title>Editing the File Systems Clean-up Script on Solaris Systems</title> | |
1339 | <indexterm> | |
1340 | <primary>Solaris</primary> | |
1341 | ||
1342 | <secondary>file systems clean-up script</secondary> | |
1343 | ||
1344 | <tertiary>on file server machine</tertiary> | |
1345 | </indexterm> | |
1346 | ||
1347 | <indexterm> | |
1348 | <primary>file systems clean-up script (Solaris)</primary> | |
1349 | ||
1350 | <secondary>file server machine</secondary> | |
1351 | </indexterm> | |
1352 | ||
1353 | <indexterm> | |
1354 | <primary>scripts</primary> | |
1355 | ||
1356 | <secondary>file systems clean-up (Solaris)</secondary> | |
1357 | ||
1358 | <tertiary>file server machine</tertiary> | |
1359 | </indexterm> | |
1360 | ||
1361 | ||
1362 | <orderedlist> | |
1363 | <listitem> | |
1364 | <para>Some Solaris distributions include a script that locates and removes unneeded files from various file systems. Its | |
1365 | conventional location is <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The script generally uses an argument | |
1366 | to the <emphasis role="bold">find</emphasis> command to define which file systems to search. In this step you modify the | |
1367 | command to exclude the <emphasis role="bold">/afs</emphasis> directory. Otherwise, the command traverses the AFS | |
1368 | filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are | |
1369 | possibilities, but you must verify that they are appropriate for your cell.</para> | |
1370 | ||
1371 | <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command, | |
1372 | so that it looks like the following:</para> | |
1373 | ||
1374 | <programlisting> | |
1375 | find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \; | |
1376 | </programlisting> | |
1377 | ||
1378 | <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis | |
1379 | role="bold">a</emphasis> or a non-alphabetic character.</para> | |
1380 | ||
1381 | <programlisting> | |
1382 | find /[A-Zb-z]* <replaceable>remainder of existing command</replaceable> | |
1383 | </programlisting> | |
1384 | ||
1385 | <para>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory, | |
1386 | looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para> | |
1387 | ||
1388 | <programlisting> | |
1389 | find / -fstype 4.2 /* <replaceable>do not use</replaceable> */ | |
1390 | </programlisting> | |
1391 | </listitem> | |
1392 | ||
1393 | <listitem> | |
1394 | <para>Proceed to <link linkend="HDRWQ50">Starting the BOS Server</link> (or if referring to these instructions while | |
1395 | installing an additional file server machine, return to <link linkend="HDRWQ108">Starting Server | |
1396 | Programs</link>).</para> | |
1397 | </listitem> | |
1398 | </orderedlist> | |
1399 | ||
1400 | <indexterm> | |
1401 | <primary>Basic OverSeer Server</primary> | |
1402 | ||
1403 | <see>BOS Server</see> | |
1404 | </indexterm> | |
1405 | ||
1406 | <indexterm> | |
1407 | <primary>BOS Server</primary> | |
1408 | ||
1409 | <secondary>starting</secondary> | |
1410 | ||
1411 | <tertiary>first AFS machine</tertiary> | |
1412 | </indexterm> | |
1413 | ||
1414 | <indexterm> | |
1415 | <primary>starting</primary> | |
1416 | ||
1417 | <secondary>BOS Server</secondary> | |
1418 | ||
1419 | <tertiary>first AFS machine</tertiary> | |
1420 | </indexterm> | |
1421 | ||
1422 | <indexterm> | |
1423 | <primary>first AFS machine</primary> | |
1424 | ||
1425 | <secondary>BOS Server</secondary> | |
1426 | </indexterm> | |
1427 | ||
1428 | <indexterm> | |
1429 | <primary>authorization checking (disabling)</primary> | |
1430 | ||
1431 | <secondary>first AFS machine</secondary> | |
1432 | </indexterm> | |
1433 | ||
1434 | <indexterm> | |
1435 | <primary>disabling authorization checking</primary> | |
1436 | ||
1437 | <secondary>first AFS machine</secondary> | |
1438 | </indexterm> | |
1439 | ||
1440 | <indexterm> | |
1441 | <primary>first AFS machine</primary> | |
1442 | ||
1443 | <secondary>authorization checking (disabling)</secondary> | |
1444 | </indexterm> | |
1445 | </sect2> | |
1446 | </sect1> | |
1447 | ||
1448 | <sect1 id="HDRWQ50"> | |
1449 | <title>Starting the BOS Server</title> | |
1450 | ||
1451 | <para>You are now ready to start the AFS server processes on this machine. | |
1452 | If you are not working from a packaged distribution, begin by installing the | |
1453 | AFS server binaries to the conventional local disk | |
1454 | location, the <emphasis role="bold">/usr/afs/bin</emphasis> directory. The | |
1455 | following instructions also create files in other subdirectories of the | |
1456 | <emphasis role="bold">/usr/afs</emphasis> directory.</para> | |
1457 | ||
1458 | <para>Then obtain a krb5 keytab for use by the servers in the cell. | |
1459 | Once the keytab is in place, issue the | |
1460 | <emphasis role="bold">bosserver</emphasis> command to initialize | |
1461 | the Basic OverSeer (BOS) Server, which | |
1462 | monitors and controls other AFS server processes on its server machine. | |
1463 | Because you have not yet configured your cell's AFS authentication and authorization | |
1464 | mechanisms, you must always use the | |
1465 | <emphasis role="bold">-localauth</emphasis> flag to commands, to use a | |
1466 | printed token that does not correspond to a normal krb5 identity.</para> | |
1467 | <para>Older versions of these instructions used the | |
1468 | <emphasis role="bold">-noauth</emphasis> flag, which completely disables | |
1469 | all authentication and authorization checking, allowing anyone at all | |
1470 | to control the system. Do not use this flag! It is highly insecure, | |
1471 | and is no longer needed.</para> | |
1472 | ||
1473 | <para>As it initializes for the first time, the BOS Server creates the following directories and files, setting the owner to the | |
1474 | local superuser <emphasis role="bold">root</emphasis> and the mode bits to limit the ability to write (and in some cases, read) | |
1475 | them. For a description of the contents and function of these directories and files, see the chapter in the <emphasis>OpenAFS | |
1476 | Administration Guide</emphasis> about administering server machines. For further discussion of the mode bit settings, see <link | |
1477 | linkend="HDRWQ96">Protecting Sensitive AFS Directories</link>. <indexterm> | |
1478 | <primary>Binary Distribution</primary> | |
1479 | ||
1480 | <secondary>copying server files from</secondary> | |
1481 | ||
1482 | <tertiary>first AFS machine</tertiary> | |
1483 | </indexterm> <indexterm> | |
1484 | <primary>first AFS machine</primary> | |
1485 | ||
1486 | <secondary>subdirectories of /usr/afs</secondary> | |
1487 | </indexterm> <indexterm> | |
1488 | <primary>creating</primary> | |
1489 | ||
1490 | <secondary>/usr/afs/bin directory</secondary> | |
1491 | ||
1492 | <tertiary>first AFS machine</tertiary> | |
1493 | </indexterm> <indexterm> | |
1494 | <primary>creating</primary> | |
1495 | ||
1496 | <secondary>/usr/afs/etc directory</secondary> | |
1497 | ||
1498 | <tertiary>first AFS machine</tertiary> | |
1499 | </indexterm> <indexterm> | |
1500 | <primary>copying</primary> | |
1501 | ||
1502 | <secondary>server files to local disk</secondary> | |
1503 | ||
1504 | <tertiary>first AFS machine</tertiary> | |
1505 | </indexterm> <indexterm> | |
1506 | <primary>first AFS machine</primary> | |
1507 | ||
1508 | <secondary>copying</secondary> | |
1509 | ||
1510 | <tertiary>server files to local disk</tertiary> | |
1511 | </indexterm> <indexterm> | |
1512 | <primary>usr/afs/bin directory</primary> | |
1513 | ||
1514 | <secondary>first AFS machine</secondary> | |
1515 | </indexterm> <indexterm> | |
1516 | <primary>usr/afs/etc directory</primary> | |
1517 | ||
1518 | <secondary>first AFS machine</secondary> | |
1519 | </indexterm> <indexterm> | |
1520 | <primary>usr/afs/db directory</primary> | |
1521 | </indexterm> <indexterm> | |
1522 | <primary>usr/afs/local directory</primary> | |
1523 | </indexterm> <indexterm> | |
1524 | <primary>usr/afs/logs directory</primary> | |
1525 | </indexterm> <itemizedlist> | |
1526 | <listitem> | |
1527 | <para><emphasis role="bold">/usr/afs/db</emphasis></para> | |
1528 | </listitem> | |
1529 | ||
1530 | <listitem> | |
1531 | <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis></para> | |
1532 | </listitem> | |
1533 | ||
1534 | <listitem> | |
1535 | <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis></para> | |
1536 | </listitem> | |
1537 | ||
1538 | <listitem> | |
1539 | <para><emphasis role="bold">/usr/afs/local</emphasis></para> | |
1540 | </listitem> | |
1541 | ||
1542 | <listitem> | |
1543 | <para><emphasis role="bold">/usr/afs/logs</emphasis></para> | |
1544 | </listitem> | |
1545 | </itemizedlist></para> | |
1546 | ||
1547 | <para>The BOS Server also creates symbolic links called <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis | |
1548 | role="bold">/usr/vice/etc/CellServDB</emphasis> to the corresponding files in the <emphasis role="bold">/usr/afs/etc</emphasis> | |
1549 | directory. The AFS command interpreters consult the <emphasis role="bold">CellServDB</emphasis> and <emphasis | |
1550 | role="bold">ThisCell</emphasis> files in the <emphasis role="bold">/usr/vice/etc</emphasis> directory because they generally run | |
1551 | on client machines. On machines that are AFS servers only (as this machine currently is), the files reside only in the <emphasis | |
1552 | role="bold">/usr/afs/etc</emphasis> directory; the links enable the command interpreters to retrieve the information they need. | |
1553 | Later instructions for installing the client functionality replace the links with actual files.</para> | |
1554 | <sect2> | |
1555 | <title>Generating the Cell's Kerberos V5 Keys</title> | |
1556 | ||
1557 | <para>This guide uses krb5 for authentication; do not use the | |
1558 | legacy <emphasis role="bold">kaserver</emphasis> for new | |
1559 | installations.</para> | |
1560 | <para>This section creates only the cell-wide shared secret key; | |
1561 | administrative users will be created later in the procedure. | |
1562 | This cell-wide key has the principal name | |
1563 | <emphasis role="bold">afs/<replaceable>cell</replaceable></emphasis>. | |
1564 | No user logs in under this identity, but it is used to encrypt the | |
1565 | server tickets that the KDC grants to AFS clients for presentation | |
1566 | to server processes during mutual authentication. (The | |
1567 | chapter in the <emphasis>OpenAFS Administration Guide</emphasis> | |
1568 | about cell configuration and administration describes the | |
1569 | role of server encryption keys in mutual authentication.)</para> | |
1570 | <para>The OpenAFS 1.8.x series stores the cell-wide shared keys in | |
1571 | the file <emphasis role="bold">/usr/afs/etc/KeyFileExt</emphasis>, | |
1572 | whereas the 1.6.x series uses a krb5 keytab format file in | |
1573 | <emphasis role="bold">/usr/afs/etc/rxkad.keytab</emphasis>. | |
1574 | These instructions create both files, but populating the | |
1575 | <emphasis role="bold">KeyFileExt</emphasis> file will only succeed | |
1576 | using the version of <emphasis role="bold">asetkey</emphasis> | |
1577 | from OpenAFS 1.8.x.</para> | |
1578 | <para>The examples below assume you are using MIT Kerberos. Please refer | |
1579 | to the documentation for your KDC's administrative interface if you are | |
1580 | using a different vendor</para> | |
1581 | ||
1582 | <orderedlist> | |
1583 | <listitem> | |
1584 | <para>Enter <emphasis role="bold">kadmin</emphasis> interactive mode. | |
1585 | <programlisting> | |
1586 | # <emphasis role="bold">kadmin</emphasis> | |
1587 | Authenticating as principal <replaceable>you</replaceable>/admin@<replaceable>YOUR REALM</replaceable> with password | |
1588 | Password for <replaceable>you/admin@REALM</replaceable>: <replaceable>your_password</replaceable> | |
1589 | </programlisting> <indexterm> | |
1590 | <primary>server encryption key</primary> | |
1591 | ||
1592 | <secondary>in Kerberos Database</secondary> | |
1593 | </indexterm> <indexterm> | |
1594 | <primary>creating</primary> | |
1595 | ||
1596 | <secondary>server encryption key</secondary> | |
1597 | ||
1598 | <tertiary>Kerberos Database</tertiary> | |
1599 | </indexterm></para> | |
1600 | </listitem> | |
1601 | ||
1602 | <listitem> | |
1603 | <para>Issue the | |
1604 | <emphasis role="bold">add_principal</emphasis> command to create | |
1605 | a Kerberos Database entry for | |
1606 | <emphasis role="bold">afs/<<replaceable>cell name</replaceable>></emphasis>.</para> | |
1607 | ||
1608 | <para>Note that when creating the | |
1609 | <emphasis role="bold">afs/<<replaceable>cell name</replaceable>></emphasis> | |
1610 | entry, the encryption type list does not include any single-DES | |
1611 | encryption types. If such encryption types are included, | |
1612 | additional <emphasis role="bold">asetkey</emphasis> commands | |
1613 | will be needed to place those keys in the legacy | |
1614 | <emphasis role="bold">KeyFile</emphasis> and ensure proper | |
1615 | operation of the cell. | |
1616 | For more details regarding encryption types, see the documentation | |
1617 | for your Kerberos installation. | |
1618 | ||
1619 | <programlisting> | |
1620 | kadmin: <emphasis role="bold">add_principal -randkey -e aes256-cts-hmac-sha1-96:normal,aes128-cts-hmac-sha1-96:normal afs/</emphasis><<replaceable>cell name</replaceable>> | |
1621 | Principal "afs/<replaceable>cell name</replaceable>@<replaceable>REALM</replaceable>" created. | |
1622 | </programlisting> | |
1623 | </para> | |
1624 | </listitem> | |
1625 | ||
1626 | <listitem> | |
1627 | <para>Extract the newly created key for | |
1628 | <emphasis role="bold">afs/<replaceable>cell</replaceable></emphasis> | |
1629 | to a keytab on the local machine.</para> | |
1630 | ||
1631 | <para>The keytab contains the key material that ensures the security of your AFS cell. You should ensure that it is kept in a secure location at all times.</para> | |
1632 | ||
1633 | <programlisting> | |
1634 | kadmin: <emphasis role="bold">ktadd -k /usr/afs/etc/rxkad.keytab -e aes256-cts-hmac-sha1-96:normal,aes128-cts-hmac-sha1-96:normal afs/<<replaceable>cell name</replaceable>></emphasis> | |
1635 | Entry for principal afs/<<replaceable>cell name</replaceable>> with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/usr/afs/etc/rxkad.keytab | |
1636 | Entry for principal afs/<<replaceable>cell name</replaceable>> with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/usr/afs/etc/rxkad.keytab | |
1637 | </programlisting> | |
1638 | <para>Make a note of the key version number (kvno) given in the | |
1639 | response, as you will need it to load the key into | |
1640 | the <emphasis role="bold">KeyFileExt</emphasis> in a later | |
1641 | step</para> | |
1642 | ||
1643 | <note><para>Note that each time you run | |
1644 | <emphasis role="bold">ktadd</emphasis> a new key is generated | |
1645 | for the item being extracted. This means that you cannot run ktadd | |
1646 | multiple times and end up with the same key material each time. | |
1647 | </para></note> | |
1648 | ||
1649 | </listitem> | |
1650 | <listitem> | |
1651 | <para>Issue the <emphasis role="bold">quit</emphasis> command to leave <emphasis role="bold">kadmin</emphasis> | |
1652 | interactive mode. <programlisting> | |
1653 | kadmin: <emphasis role="bold">quit</emphasis> | |
1654 | </programlisting></para> | |
1655 | </listitem> | |
1656 | ||
1657 | <listitem id="LIWQ58"> | |
1658 | <para>Issue the | |
1659 | <emphasis role="bold">asetkey</emphasis> command to set the AFS | |
1660 | server encryption key in the | |
1661 | <emphasis role="bold">/usr/afs/etc/KeyFileExt</emphasis> file. | |
1662 | This key | |
1663 | is created from the <emphasis role="bold">rxkad.keytab</emphasis> | |
1664 | file created earlier.</para> | |
1665 | ||
1666 | <para>asetkey requires the key version number (or kvno) of the | |
1667 | <emphasis role="bold">afs/</emphasis><replaceable>cell</replaceable> | |
1668 | key, as well as the encryption type number of the key. | |
1669 | You should have made note of the kvno when creating the key | |
1670 | earlier. The key version number can also be found by running the | |
1671 | <emphasis role="bold">kvno</emphasis> command</para> | |
1672 | <programlisting> | |
1673 | # <emphasis role="bold">kvno -kt /usr/afs/etc/rxkad.keytab</emphasis> | |
1674 | </programlisting> | |
1675 | <para>The encryption type numbers can be found in the local krb5 | |
1676 | headers or the IANA registry. The most common numbers are | |
1677 | 18 for <emphasis role="bold">aes256-cts-hmac-sha1-96</emphasis> and | |
1678 | 17 for <emphasis role="bold">aes128-cts-hmac-sha1-96</emphasis>. | |
1679 | </para> | |
1680 | ||
1681 | <para>Once the kvno and enctypes are known, the keys | |
1682 | can then be extracted using asetkey</para> | |
1683 | <programlisting> | |
1684 | # <emphasis role="bold">asetkey add rxkad_krb5</emphasis> <<replaceable>kvno</replaceable>> <emphasis role="bold">18 /usr/afs/etc/rxkad.keytab afs/</emphasis><<replaceable>cell name</replaceable>> | |
1685 | # <emphasis role="bold">asetkey add rxkad_krb5</emphasis> <<replaceable>kvno</replaceable>> <emphasis role="bold">17 /usr/afs/etc/rxkad.keytab afs/</emphasis><<replaceable>cell name</replaceable>> | |
1686 | </programlisting> | |
1687 | </listitem> | |
1688 | </orderedlist> | |
1689 | </sect2> | |
1690 | <sect2> | |
1691 | <title>Starting the Server Processes</title> | |
1692 | ||
1693 | <para>Now that the keys are in place, proceed to start the server | |
1694 | processes: | |
1695 | <orderedlist> | |
1696 | <listitem> | |
1697 | <para>If you are building from source, you need to install the | |
1698 | compiled files to the local | |
1699 | <emphasis role="bold">/usr/afs</emphasis> directory. <indexterm> | |
1700 | <primary>commands</primary> | |
1701 | ||
1702 | <secondary>bosserver</secondary> | |
1703 | </indexterm> <indexterm> | |
1704 | <primary>bosserver command</primary> | |
1705 | </indexterm></para> | |
1706 | </listitem> | |
1707 | ||
1708 | <listitem> | |
1709 | <para>Issue the <emphasis role="bold">bosserver</emphasis> command. | |
1710 | <programlisting> | |
1711 | # <emphasis role="bold">/usr/afs/bin/bosserver</emphasis> | |
1712 | </programlisting></para> | |
1713 | </listitem> | |
1714 | ||
1715 | <listitem> | |
1716 | <para>Verify that the BOS Server created <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis | |
1717 | role="bold">/usr/vice/etc/CellServDB</emphasis> as symbolic links to the corresponding files in the <emphasis | |
1718 | role="bold">/usr/afs/etc</emphasis> directory. <programlisting> | |
1719 | # <emphasis role="bold">ls -l /usr/vice/etc</emphasis> | |
1720 | </programlisting></para> | |
1721 | ||
1722 | <para>If either or both of <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> and <emphasis | |
1723 | role="bold">/usr/vice/etc/CellServDB</emphasis> do not exist, or are not links, issue the following commands.</para> | |
1724 | ||
1725 | <programlisting> | |
1726 | # <emphasis role="bold">cd /usr/vice/etc</emphasis> | |
1727 | # <emphasis role="bold">ln -s /usr/afs/etc/ThisCell</emphasis> | |
1728 | # <emphasis role="bold">ln -s /usr/afs/etc/CellServDB</emphasis> | |
1729 | </programlisting> | |
1730 | </listitem> | |
1731 | </orderedlist></para> | |
1732 | ||
1733 | <indexterm> | |
1734 | <primary>cell name</primary> | |
1735 | ||
1736 | <secondary>defining during installation of first machine</secondary> | |
1737 | </indexterm> | |
1738 | ||
1739 | <indexterm> | |
1740 | <primary>defining</primary> | |
1741 | ||
1742 | <secondary>cell name during installation of first machine</secondary> | |
1743 | </indexterm> | |
1744 | ||
1745 | <indexterm> | |
1746 | <primary>cell name</primary> | |
1747 | ||
1748 | <secondary>setting in server ThisCell file</secondary> | |
1749 | ||
1750 | <tertiary>first AFS machine</tertiary> | |
1751 | </indexterm> | |
1752 | ||
1753 | <indexterm> | |
1754 | <primary>setting</primary> | |
1755 | ||
1756 | <secondary>cell name in server ThisCell file</secondary> | |
1757 | ||
1758 | <tertiary>first AFS machine</tertiary> | |
1759 | </indexterm> | |
1760 | ||
1761 | <indexterm> | |
1762 | <primary>first AFS machine</primary> | |
1763 | ||
1764 | <secondary>ThisCell file (server)</secondary> | |
1765 | </indexterm> | |
1766 | ||
1767 | <indexterm> | |
1768 | <primary>usr/afs/etc/ThisCell</primary> | |
1769 | ||
1770 | <see>ThisCell file (server)</see> | |
1771 | </indexterm> | |
1772 | ||
1773 | <indexterm> | |
1774 | <primary>ThisCell file (server)</primary> | |
1775 | ||
1776 | <secondary>first AFS machine</secondary> | |
1777 | </indexterm> | |
1778 | ||
1779 | <indexterm> | |
1780 | <primary>files</primary> | |
1781 | ||
1782 | <secondary>ThisCell (server)</secondary> | |
1783 | </indexterm> | |
1784 | ||
1785 | <indexterm> | |
1786 | <primary>database server machine</primary> | |
1787 | ||
1788 | <secondary>entry in server CellServDB file</secondary> | |
1789 | ||
1790 | <tertiary>on first AFS machine</tertiary> | |
1791 | </indexterm> | |
1792 | ||
1793 | <indexterm> | |
1794 | <primary>first AFS machine</primary> | |
1795 | ||
1796 | <secondary>cell membership, defining</secondary> | |
1797 | ||
1798 | <tertiary>for server processes</tertiary> | |
1799 | </indexterm> | |
1800 | ||
1801 | <indexterm> | |
1802 | <primary>usr/afs/etc/CellServDB file</primary> | |
1803 | ||
1804 | <see>CellServDB file (server)</see> | |
1805 | </indexterm> | |
1806 | ||
1807 | <indexterm> | |
1808 | <primary>CellServDB file (server)</primary> | |
1809 | ||
1810 | <secondary>creating</secondary> | |
1811 | ||
1812 | <tertiary>on first AFS machine</tertiary> | |
1813 | </indexterm> | |
1814 | ||
1815 | <indexterm> | |
1816 | <primary>creating</primary> | |
1817 | ||
1818 | <secondary>CellServDB file (server)</secondary> | |
1819 | ||
1820 | <tertiary>first AFS machine</tertiary> | |
1821 | </indexterm> | |
1822 | ||
1823 | <indexterm> | |
1824 | <primary>files</primary> | |
1825 | ||
1826 | <secondary>CellServDB (server)</secondary> | |
1827 | </indexterm> | |
1828 | ||
1829 | <indexterm> | |
1830 | <primary>first AFS machine</primary> | |
1831 | ||
1832 | <secondary>CellServDB file (server)</secondary> | |
1833 | </indexterm> | |
1834 | ||
1835 | <indexterm> | |
1836 | <primary>first AFS machine</primary> | |
1837 | ||
1838 | <secondary>defining</secondary> | |
1839 | ||
1840 | <tertiary>as database server</tertiary> | |
1841 | </indexterm> | |
1842 | ||
1843 | <indexterm> | |
1844 | <primary>defining</primary> | |
1845 | ||
1846 | <secondary>first AFS machine as database server</secondary> | |
1847 | </indexterm> | |
1848 | </sect2> | |
1849 | </sect1> | |
1850 | ||
1851 | <sect1 id="HDRWQ51"> | |
1852 | <title>Defining Cell Name and Membership for Server Processes</title> | |
1853 | ||
1854 | <para>Now assign your cell's name. The chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell configuration | |
1855 | and administration issues discusses the important considerations, explains why changing the name is difficult, and outlines the | |
1856 | restrictions on name format. Two of the most important restrictions are that the name cannot include uppercase letters or more | |
1857 | than 64 characters.</para> | |
1858 | ||
1859 | <para>Use the <emphasis role="bold">bos setcellname</emphasis> command to assign the cell name. It creates two files: | |
1860 | <itemizedlist> | |
1861 | <listitem> | |
1862 | <para><emphasis role="bold">/usr/afs/etc/ThisCell</emphasis>, which defines this machine's cell membership</para> | |
1863 | </listitem> | |
1864 | ||
1865 | <listitem> | |
1866 | <para><emphasis role="bold">/usr/afs/etc/CellServDB</emphasis>, which lists the cell's database server machines; the | |
1867 | machine named on the command line is placed on the list automatically</para> | |
1868 | </listitem> | |
1869 | </itemizedlist> <note> | |
1870 | <para>In the following and every instruction in this guide, for the <replaceable>machine name</replaceable> argument | |
1871 | substitute the fully-qualified hostname (such as <emphasis role="bold">fs1.example.com</emphasis>) of the machine you are | |
1872 | installing. For the <replaceable>cell name</replaceable> argument substitute your cell's complete name (such as <emphasis | |
1873 | role="bold">example.com</emphasis>).</para> | |
1874 | </note></para> | |
1875 | ||
1876 | <indexterm> | |
1877 | <primary>commands</primary> | |
1878 | ||
1879 | <secondary>bos setcellname</secondary> | |
1880 | </indexterm> | |
1881 | ||
1882 | <indexterm> | |
1883 | <primary>bos commands</primary> | |
1884 | ||
1885 | <secondary>setcellname</secondary> | |
1886 | </indexterm> | |
1887 | ||
1888 | <orderedlist> | |
1889 | <listitem> | |
1890 | <para>If necessary, add the directory containing the <emphasis role="bold">bos</emphasis> command to your path. | |
1891 | <programlisting> | |
1892 | # <emphasis role="bold">export PATH=$PATH:/usr/afs/bin</emphasis> | |
1893 | </programlisting> | |
1894 | </para> | |
1895 | </listitem> | |
1896 | ||
1897 | <listitem> | |
1898 | <para>Issue the <emphasis role="bold">bos setcellname</emphasis> command to set the cell name. <programlisting> | |
1899 | # <emphasis role="bold">bos setcellname</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>cell name</replaceable>> <emphasis | |
1900 | role="bold">-localauth</emphasis> | |
1901 | </programlisting></para> <indexterm> | |
1902 | <primary>commands</primary> | |
1903 | ||
1904 | <secondary>bos listhosts</secondary> | |
1905 | </indexterm> <indexterm> | |
1906 | <primary>bos commands</primary> | |
1907 | ||
1908 | <secondary>listhosts</secondary> | |
1909 | </indexterm> <indexterm> | |
1910 | <primary>CellServDB file (server)</primary> | |
1911 | ||
1912 | <secondary>displaying entries</secondary> | |
1913 | </indexterm> <indexterm> | |
1914 | <primary>displaying</primary> | |
1915 | ||
1916 | <secondary>CellServDB file (server) entries</secondary> | |
1917 | </indexterm> | |
1918 | </listitem> | |
1919 | ||
1920 | <listitem> | |
1921 | <para>Issue the <emphasis role="bold">bos listhosts</emphasis> command to verify that the machine you are installing is now | |
1922 | registered as the cell's first database server machine. <programlisting> | |
1923 | # <emphasis role="bold">bos listhosts</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">-localauth</emphasis> | |
1924 | Cell name is <replaceable>cell_name</replaceable> | |
1925 | Host 1 is <replaceable>machine_name</replaceable> | |
1926 | </programlisting></para> | |
1927 | </listitem> | |
1928 | </orderedlist> | |
1929 | ||
1930 | <indexterm> | |
1931 | <primary>database server machine</primary> | |
1932 | ||
1933 | <secondary>installing</secondary> | |
1934 | ||
1935 | <tertiary>first</tertiary> | |
1936 | </indexterm> | |
1937 | ||
1938 | <indexterm> | |
1939 | <primary>instructions</primary> | |
1940 | ||
1941 | <secondary>database server machine, installing first</secondary> | |
1942 | </indexterm> | |
1943 | ||
1944 | <indexterm> | |
1945 | <primary>installing</primary> | |
1946 | ||
1947 | <secondary>database server machine</secondary> | |
1948 | ||
1949 | <tertiary>first</tertiary> | |
1950 | </indexterm> | |
1951 | ||
1952 | <indexterm> | |
1953 | <primary>Backup Server</primary> | |
1954 | ||
1955 | <secondary>starting</secondary> | |
1956 | ||
1957 | <tertiary>first AFS machine</tertiary> | |
1958 | </indexterm> | |
1959 | ||
1960 | <indexterm> | |
1961 | <primary>buserver process</primary> | |
1962 | ||
1963 | <see>Backup Server</see> | |
1964 | </indexterm> | |
1965 | ||
1966 | <indexterm> | |
1967 | <primary>starting</primary> | |
1968 | ||
1969 | <secondary>Backup Server</secondary> | |
1970 | ||
1971 | <tertiary>first AFS machine</tertiary> | |
1972 | </indexterm> | |
1973 | ||
1974 | <indexterm> | |
1975 | <primary>first AFS machine</primary> | |
1976 | ||
1977 | <secondary>Backup Server</secondary> | |
1978 | </indexterm> | |
1979 | ||
1980 | <indexterm> | |
1981 | <primary>Protection Server</primary> | |
1982 | ||
1983 | <secondary>starting</secondary> | |
1984 | ||
1985 | <tertiary>first AFS machine</tertiary> | |
1986 | </indexterm> | |
1987 | ||
1988 | <indexterm> | |
1989 | <primary>ptserver process</primary> | |
1990 | ||
1991 | <see>Protection Server</see> | |
1992 | </indexterm> | |
1993 | ||
1994 | <indexterm> | |
1995 | <primary>starting</primary> | |
1996 | ||
1997 | <secondary>Protection Server</secondary> | |
1998 | ||
1999 | <tertiary>first AFS machine</tertiary> | |
2000 | </indexterm> | |
2001 | ||
2002 | <indexterm> | |
2003 | <primary>first AFS machine</primary> | |
2004 | ||
2005 | <secondary>Protection Server</secondary> | |
2006 | </indexterm> | |
2007 | ||
2008 | <indexterm> | |
2009 | <primary>VL Server (vlserver process)</primary> | |
2010 | ||
2011 | <secondary>starting</secondary> | |
2012 | ||
2013 | <tertiary>first AFS machine</tertiary> | |
2014 | </indexterm> | |
2015 | ||
2016 | <indexterm> | |
2017 | <primary>Volume Location Server</primary> | |
2018 | ||
2019 | <see>VL Server</see> | |
2020 | </indexterm> | |
2021 | ||
2022 | <indexterm> | |
2023 | <primary>starting</primary> | |
2024 | ||
2025 | <secondary>VL Server</secondary> | |
2026 | ||
2027 | <tertiary>first AFS machine</tertiary> | |
2028 | </indexterm> | |
2029 | ||
2030 | <indexterm> | |
2031 | <primary>first AFS machine</primary> | |
2032 | ||
2033 | <secondary>VL Server</secondary> | |
2034 | </indexterm> | |
2035 | ||
2036 | <indexterm> | |
2037 | <primary>usr/afs/local/BosConfig</primary> | |
2038 | ||
2039 | <see>BosConfig file</see> | |
2040 | </indexterm> | |
2041 | ||
2042 | <indexterm> | |
2043 | <primary>BosConfig file</primary> | |
2044 | ||
2045 | <secondary>adding entries</secondary> | |
2046 | ||
2047 | <tertiary>first AFS machine</tertiary> | |
2048 | </indexterm> | |
2049 | ||
2050 | <indexterm> | |
2051 | <primary>adding</primary> | |
2052 | ||
2053 | <secondary>entries to BosConfig file</secondary> | |
2054 | ||
2055 | <tertiary>first AFS machine</tertiary> | |
2056 | </indexterm> | |
2057 | ||
2058 | <indexterm> | |
2059 | <primary>files</primary> | |
2060 | ||
2061 | <secondary>BosConfig</secondary> | |
2062 | </indexterm> | |
2063 | ||
2064 | <indexterm> | |
2065 | <primary>initializing</primary> | |
2066 | ||
2067 | <secondary>server process</secondary> | |
2068 | ||
2069 | <see>starting</see> | |
2070 | </indexterm> | |
2071 | ||
2072 | <indexterm> | |
2073 | <primary>server process</primary> | |
2074 | ||
2075 | <secondary>see also entry for each server's name</secondary> | |
2076 | </indexterm> | |
2077 | </sect1> | |
2078 | ||
2079 | <sect1 id="HDRWQ52"> | |
2080 | <title>Starting the Database Server Processes</title> | |
2081 | ||
2082 | <para>Next use the <emphasis role="bold">bos create</emphasis> command to create entries for the three database server processes | |
2083 | in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file and start them running. The three processes run on database | |
2084 | server machines only: <itemizedlist> | |
2085 | ||
2086 | <listitem> | |
2087 | <para>The Protection Server (the <emphasis role="bold">ptserver</emphasis> process) maintains the Protection | |
2088 | Database</para> | |
2089 | </listitem> | |
2090 | ||
2091 | <listitem> | |
2092 | <para>The Volume Location (VL) Server (the <emphasis role="bold">vlserver</emphasis> process) maintains the Volume | |
2093 | Location Database (VLDB)</para> | |
2094 | </listitem> | |
2095 | ||
2096 | <listitem> | |
2097 | <para>The optional Backup Server (the <emphasis role="bold">buserver</emphasis> process) maintains the Backup Database</para> | |
2098 | </listitem> | |
2099 | </itemizedlist></para> | |
2100 | ||
2101 | <indexterm> | |
2102 | <primary>Kerberos</primary> | |
2103 | </indexterm> | |
2104 | ||
2105 | <note> | |
2106 | <para>AFS ships with an additional database server named 'kaserver', which | |
2107 | was historically used to provide authentication services to AFS cells. | |
2108 | kaserver was based on <emphasis>Kerberos v4</emphasis>, as such, it is | |
2109 | not recommended for new cells. This guide assumes you have already | |
2110 | configured a Kerberos v5 realm for your site, and details the procedures | |
2111 | required to use AFS with this realm. If you do wish to use | |
2112 | <emphasis role="bold">kaserver</emphasis>, please see the modifications | |
2113 | to these instructions detailed in | |
2114 | <link linkend="KAS006">Starting the kaserver Database Server Process</link> | |
2115 | </para> | |
2116 | </note> | |
2117 | ||
2118 | <para>The remaining instructions in this chapter include the <emphasis role="bold">-cell</emphasis> argument on all applicable | |
2119 | commands. Provide the cell name you assigned in <link linkend="HDRWQ51">Defining Cell Name and Membership for Server | |
2120 | Processes</link>. If a command appears on multiple lines, it is only for legibility. <indexterm> | |
2121 | <primary>commands</primary> | |
2122 | ||
2123 | <secondary>bos create</secondary> | |
2124 | </indexterm> <indexterm> | |
2125 | <primary>bos commands</primary> | |
2126 | ||
2127 | <secondary>create</secondary> | |
2128 | </indexterm> <orderedlist> | |
2129 | <listitem> | |
2130 | <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the Protection Server. <programlisting> | |
2131 | # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">ptserver simple /usr/afs/bin/ptserver</emphasis> <emphasis role="bold">-localauth</emphasis> | |
2132 | </programlisting></para> | |
2133 | </listitem> | |
2134 | ||
2135 | <listitem> | |
2136 | <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the VL Server. <programlisting> | |
2137 | # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">vlserver simple /usr/afs/bin/vlserver</emphasis> <emphasis role="bold">-localauth</emphasis> | |
2138 | </programlisting></para> | |
2139 | </listitem> | |
2140 | ||
2141 | <listitem> | |
2142 | <para>Optionally, issue the <emphasis role="bold">bos create</emphasis> command to start the Backup Server. <programlisting> | |
2143 | # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">buserver simple /usr/afs/bin/buserver</emphasis> <emphasis role="bold">-localauth</emphasis> | |
2144 | </programlisting></para> | |
2145 | </listitem> | |
2146 | </orderedlist></para> | |
2147 | ||
2148 | <indexterm> | |
2149 | <primary>admin account</primary> | |
2150 | ||
2151 | <secondary>creating</secondary> | |
2152 | </indexterm> | |
2153 | ||
2154 | <indexterm> | |
2155 | <primary>afs entry in Kerberos Database</primary> | |
2156 | </indexterm> | |
2157 | ||
2158 | <indexterm> | |
2159 | <primary>Kerberos Database</primary> | |
2160 | </indexterm> | |
2161 | ||
2162 | <indexterm> | |
2163 | <primary>creating</primary> | |
2164 | ||
2165 | <secondary>afs entry in Kerberos Database</secondary> | |
2166 | </indexterm> | |
2167 | ||
2168 | <indexterm> | |
2169 | <primary>creating</primary> | |
2170 | ||
2171 | <secondary>admin account in Kerberos Database</secondary> | |
2172 | </indexterm> | |
2173 | ||
2174 | <indexterm> | |
2175 | <primary>security</primary> | |
2176 | ||
2177 | <secondary>initializing cell-wide</secondary> | |
2178 | </indexterm> | |
2179 | ||
2180 | <indexterm> | |
2181 | <primary>cell</primary> | |
2182 | ||
2183 | <secondary>initializing security mechanisms</secondary> | |
2184 | </indexterm> | |
2185 | ||
2186 | <indexterm> | |
2187 | <primary>initializing</primary> | |
2188 | ||
2189 | <secondary>cell security mechanisms</secondary> | |
2190 | </indexterm> | |
2191 | ||
2192 | <indexterm> | |
2193 | <primary>usr/afs/etc/KeyFile</primary> | |
2194 | ||
2195 | <see>KeyFile file</see> | |
2196 | </indexterm> | |
2197 | ||
2198 | <indexterm> | |
2199 | <primary>KeyFile file</primary> | |
2200 | ||
2201 | <secondary>first AFS machine</secondary> | |
2202 | </indexterm> | |
2203 | ||
2204 | <indexterm> | |
2205 | <primary>files</primary> | |
2206 | ||
2207 | <secondary>KeyFile</secondary> | |
2208 | </indexterm> | |
2209 | ||
2210 | <indexterm> | |
2211 | <primary>key</primary> | |
2212 | ||
2213 | <see>server encryption key</see> | |
2214 | </indexterm> | |
2215 | ||
2216 | <indexterm> | |
2217 | <primary>encryption key</primary> | |
2218 | ||
2219 | <see>server encryption key</see> | |
2220 | </indexterm> | |
2221 | </sect1> | |
2222 | ||
2223 | <sect1 id="HDRWQ53"> | |
2224 | <title>Initializing Cell Security </title> | |
2225 | ||
2226 | <para>If you are working with an existing cell which uses | |
2227 | <emphasis role="bold">kaserver</emphasis> or Kerberos v4 for authentication, | |
2228 | please see | |
2229 | <link linkend="HDRWQ53">Initializing Cell Security with kaserver</link> | |
2230 | for installation instructions which replace this section.</para> | |
2231 | ||
2232 | <para>Now finish initializing the cell's security mechanisms. Begin by creating the following entry in your site's Kerberos database: <itemizedlist> | |
2233 | <listitem> | |
2234 | <para>A generic administrative account, called <emphasis role="bold">admin</emphasis> by convention. If you choose to | |
2235 | assign a different name, substitute it throughout the remainder of this document.</para> | |
2236 | ||
2237 | <para>After you complete the installation of the first machine, you can continue to have all administrators use the | |
2238 | <emphasis role="bold">admin</emphasis> account, or you can create a separate administrative account for each of them. The | |
2239 | latter scheme implies somewhat more overhead, but provides a more informative audit trail for administrative | |
2240 | operations.</para> | |
2241 | </listitem> | |
2242 | </itemizedlist></para> | |
2243 | ||
2244 | <para>You also issue several commands that enable the new <emphasis role="bold">admin</emphasis> user to issue privileged | |
2245 | commands in all of the AFS suites.</para> | |
2246 | ||
2247 | <para>The following instructions do not configure all of the security mechanisms related to the AFS Backup System. See the | |
2248 | chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about configuring the Backup System.</para> | |
2249 | ||
2250 | <para>The examples below assume you are using MIT Kerberos. Please refer | |
2251 | to the documentation for your KDC's administrative interface if you are | |
2252 | using a different vendor</para> | |
2253 | ||
2254 | <orderedlist> | |
2255 | <listitem> | |
2256 | <para>Enter <emphasis role="bold">kadmin</emphasis> interactive mode. | |
2257 | <programlisting> | |
2258 | # <emphasis role="bold">kadmin</emphasis> | |
2259 | Authenticating as principal <replaceable>you</replaceable>/admin@<replaceable>YOUR REALM</replaceable> with password | |
2260 | Password for <replaceable>you/admin@REALM</replaceable>: <replaceable>your_password</replaceable> | |
2261 | </programlisting> </para> | |
2262 | </listitem> | |
2263 | ||
2264 | <listitem> | |
2265 | <para>Issue the | |
2266 | <emphasis role="bold">add_principal</emphasis> command to create | |
2267 | the Kerberos Database entry for | |
2268 | <emphasis role="bold">admin</emphasis>.</para> | |
2269 | ||
2270 | <para>You should make the <replaceable>admin_passwd</replaceable> as | |
2271 | long and complex as possible, but keep in mind that administrators | |
2272 | need to enter it often. It must be at least six characters long. | |
2273 | <programlisting> | |
2274 | kadmin: <emphasis role="bold">add_principal admin</emphasis> | |
2275 | Enter password for principal "admin@<replaceable>REALM</replaceable>": <emphasis role="bold"><replaceable>admin_password</replaceable></emphasis> | |
2276 | Principal "admin@<replaceable>REALM</replaceable>" created. | |
2277 | </programlisting> | |
2278 | </para> | |
2279 | ||
2280 | <indexterm> | |
2281 | <primary>displaying</primary> | |
2282 | ||
2283 | <secondary>server encryption key</secondary> | |
2284 | ||
2285 | <tertiary>Authentication Database</tertiary> | |
2286 | </indexterm> | |
2287 | </listitem> | |
2288 | ||
2289 | <listitem> | |
2290 | <para>Issue the <emphasis role="bold">quit</emphasis> command to leave <emphasis role="bold">kadmin</emphasis> | |
2291 | interactive mode. <programlisting> | |
2292 | kadmin: <emphasis role="bold">quit</emphasis> | |
2293 | </programlisting> <indexterm> | |
2294 | <primary>commands</primary> | |
2295 | ||
2296 | <secondary>bos adduser</secondary> | |
2297 | </indexterm> <indexterm> | |
2298 | <primary>bos commands</primary> | |
2299 | ||
2300 | <secondary>adduser</secondary> | |
2301 | </indexterm> <indexterm> | |
2302 | <primary>usr/afs/etc/UserList</primary> | |
2303 | ||
2304 | <see>UserList file</see> | |
2305 | </indexterm> <indexterm> | |
2306 | <primary>UserList file</primary> | |
2307 | ||
2308 | <secondary>first AFS machine</secondary> | |
2309 | </indexterm> <indexterm> | |
2310 | <primary>files</primary> | |
2311 | ||
2312 | <secondary>UserList</secondary> | |
2313 | </indexterm> <indexterm> | |
2314 | <primary>creating</primary> | |
2315 | ||
2316 | <secondary>UserList file entry</secondary> | |
2317 | </indexterm> <indexterm> | |
2318 | <primary>admin account</primary> | |
2319 | ||
2320 | <secondary>adding</secondary> | |
2321 | ||
2322 | <tertiary>to UserList file</tertiary> | |
2323 | </indexterm></para> | |
2324 | </listitem> | |
2325 | ||
2326 | <listitem id="LIWQ57"> | |
2327 | <para>Issue the <emphasis role="bold">bos adduser</emphasis> command to add the <emphasis | |
2328 | role="bold">admin</emphasis> user to the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. This enables the | |
2329 | <emphasis role="bold">admin</emphasis> user to issue privileged <emphasis role="bold">bos</emphasis> and <emphasis | |
2330 | role="bold">vos</emphasis> commands. <programlisting> | |
2331 | # <emphasis role="bold">./bos adduser</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">admin -localauth</emphasis> | |
2332 | </programlisting> | |
2333 | <indexterm> | |
2334 | <primary>commands</primary> | |
2335 | <secondary>asetkey</secondary> | |
2336 | </indexterm> | |
2337 | <indexterm> | |
2338 | <primary>creating</primary> | |
2339 | <secondary>server encryption key</secondary> | |
2340 | <tertiary>KeyFile file</tertiary> | |
2341 | </indexterm> | |
2342 | <indexterm> | |
2343 | <primary>server encryption key</primary> | |
2344 | <secondary>in KeyFile file</secondary> | |
2345 | </indexterm></para> | |
2346 | </listitem> | |
2347 | </orderedlist> | |
2348 | </sect1> | |
2349 | <sect1 id="HDRWQ53a"> | |
2350 | <title>Initializing the Protection Database</title> | |
2351 | ||
2352 | <para>Now continue to configure your cell's security systems by | |
2353 | populating the Protection Database with the newly created | |
2354 | <emphasis role="bold">admin</emphasis> user, and permitting it | |
2355 | to issue priviledged commands on the AFS filesystem. | |
2356 | There is nothing special about the name "admin"; it is just a | |
2357 | convenient name for these instructions. An other name could | |
2358 | be used throughout this document, or multiple privileged | |
2359 | accounts created.</para> | |
2360 | ||
2361 | <orderedlist> | |
2362 | <listitem> | |
2363 | <para>Issue the <emphasis role="bold">pts createuser</emphasis> command to create a Protection Database entry for the | |
2364 | <emphasis role="bold">admin</emphasis> user. | |
2365 | <indexterm> | |
2366 | <primary>commands</primary> | |
2367 | <secondary>pts createuser</secondary> | |
2368 | </indexterm> | |
2369 | ||
2370 | <indexterm> | |
2371 | <primary>pts commands</primary> | |
2372 | <secondary>createuser</secondary> | |
2373 | </indexterm> | |
2374 | ||
2375 | <indexterm> | |
2376 | <primary>Protection Database</primary> | |
2377 | </indexterm></para> | |
2378 | ||
2379 | <para>By default, the Protection Server assigns AFS UID 1 (one) to the <emphasis role="bold">admin</emphasis> user, | |
2380 | because it is the first user entry you are creating. If the local password file (<emphasis | |
2381 | role="bold">/etc/passwd</emphasis> or equivalent) already has an entry for <emphasis role="bold">admin</emphasis> that | |
2382 | assigns it a UNIX UID other than 1, it is best to use the <emphasis role="bold">-id</emphasis> argument to the <emphasis | |
2383 | role="bold">pts createuser</emphasis> command to make the new AFS UID match the existing UNIX UID. Otherwise, it is best | |
2384 | to accept the default.</para> | |
2385 | ||
2386 | <programlisting> | |
2387 | # <emphasis role="bold">pts createuser -name admin</emphasis> [<emphasis | |
2388 | role="bold">-id</emphasis> <<replaceable>AFS UID</replaceable>>] <emphasis role="bold">-localauth</emphasis> | |
2389 | User admin has id <replaceable>AFS UID</replaceable> | |
2390 | </programlisting> | |
2391 | ||
2392 | <indexterm> | |
2393 | <primary>commands</primary> | |
2394 | <secondary>pts adduser</secondary> | |
2395 | </indexterm> | |
2396 | ||
2397 | <indexterm> | |
2398 | <primary>pts commands</primary> | |
2399 | <secondary>adduser</secondary> | |
2400 | </indexterm> | |
2401 | ||
2402 | <indexterm> | |
2403 | <primary>system:administrators group</primary> | |
2404 | </indexterm> | |
2405 | ||
2406 | <indexterm> | |
2407 | <primary>admin account</primary> | |
2408 | <secondary>adding</secondary> | |
2409 | <tertiary>to system:administrators group</tertiary> | |
2410 | </indexterm> | |
2411 | </listitem> | |
2412 | ||
2413 | <listitem> | |
2414 | <para>Issue the <emphasis role="bold">pts adduser</emphasis> command to make the <emphasis role="bold">admin</emphasis> | |
2415 | user a member of the <emphasis role="bold">system:administrators</emphasis> group, and the <emphasis role="bold">pts | |
2416 | membership</emphasis> command to verify the new membership. Membership in the group enables the <emphasis | |
2417 | role="bold">admin</emphasis> user to issue privileged <emphasis role="bold">pts</emphasis> commands and some privileged | |
2418 | <emphasis role="bold">fs</emphasis> commands. <programlisting> | |
2419 | # <emphasis role="bold">./pts adduser admin system:administrators</emphasis> <emphasis role="bold">-localauth</emphasis> | |
2420 | # <emphasis role="bold">./pts membership admin</emphasis> <emphasis role="bold">-localauth</emphasis> | |
2421 | Groups admin (id: 1) is a member of: | |
2422 | system:administrators | |
2423 | </programlisting> <indexterm> | |
2424 | <primary>commands</primary> | |
2425 | <secondary>bos restart</secondary> | |
2426 | <tertiary>on first AFS machine</tertiary> | |
2427 | </indexterm> <indexterm> | |
2428 | <primary>bos commands</primary> | |
2429 | <secondary>restart</secondary> | |
2430 | <tertiary>on first AFS machine</tertiary> | |
2431 | </indexterm> <indexterm> | |
2432 | <primary>restarting server process</primary> | |
2433 | <secondary>on first AFS machine</secondary> | |
2434 | </indexterm> <indexterm> | |
2435 | <primary>server process</primary> | |
2436 | <secondary>restarting</secondary> | |
2437 | <tertiary>on first AFS machine</tertiary> | |
2438 | </indexterm></para> | |
2439 | </listitem> | |
2440 | </orderedlist> | |
2441 | ||
2442 | <indexterm> | |
2443 | <primary>File Server</primary> | |
2444 | ||
2445 | <secondary>first AFS machine</secondary> | |
2446 | </indexterm> | |
2447 | ||
2448 | <indexterm> | |
2449 | <primary>fileserver process</primary> | |
2450 | ||
2451 | <see>File Server</see> | |
2452 | </indexterm> | |
2453 | ||
2454 | <indexterm> | |
2455 | <primary>starting</primary> | |
2456 | ||
2457 | <secondary>File Server</secondary> | |
2458 | ||
2459 | <tertiary>first AFS machine</tertiary> | |
2460 | </indexterm> | |
2461 | ||
2462 | <indexterm> | |
2463 | <primary>first AFS machine</primary> | |
2464 | ||
2465 | <secondary>File Server, fs process</secondary> | |
2466 | </indexterm> | |
2467 | ||
2468 | <indexterm> | |
2469 | <primary>Volume Server</primary> | |
2470 | ||
2471 | <secondary>first AFS machine</secondary> | |
2472 | </indexterm> | |
2473 | ||
2474 | <indexterm> | |
2475 | <primary>volserver process</primary> | |
2476 | ||
2477 | <see>Volume Server</see> | |
2478 | </indexterm> | |
2479 | ||
2480 | <indexterm> | |
2481 | <primary>starting</primary> | |
2482 | ||
2483 | <secondary>Volume Server</secondary> | |
2484 | ||
2485 | <tertiary>first AFS machine</tertiary> | |
2486 | </indexterm> | |
2487 | ||
2488 | <indexterm> | |
2489 | <primary>first AFS machine</primary> | |
2490 | ||
2491 | <secondary>Volume Server</secondary> | |
2492 | </indexterm> | |
2493 | ||
2494 | <indexterm> | |
2495 | <primary>Salvager (salvager process)</primary> | |
2496 | ||
2497 | <secondary>first AFS machine</secondary> | |
2498 | </indexterm> | |
2499 | ||
2500 | <indexterm> | |
2501 | <primary>fs process</primary> | |
2502 | ||
2503 | <secondary>first AFS machine</secondary> | |
2504 | </indexterm> | |
2505 | ||
2506 | <indexterm> | |
2507 | <primary>starting</primary> | |
2508 | ||
2509 | <secondary>fs process</secondary> | |
2510 | ||
2511 | <tertiary>first AFS machine</tertiary> | |
2512 | </indexterm> | |
2513 | ||
2514 | <indexterm> | |
2515 | <primary>first AFS machine</primary> | |
2516 | ||
2517 | <secondary>Salvager</secondary> | |
2518 | </indexterm> | |
2519 | </sect1> | |
2520 | ||
2521 | <sect1 id="HDRWQ60"> | |
2522 | <title>Starting the File Server processes</title> | |
2523 | ||
2524 | <para>Start the | |
2525 | <emphasis role="bold">dafs</emphasis> process. | |
2526 | The <emphasis role="bold">dafs</emphasis> process consists of the | |
2527 | Demand-Attach File Server, Volume Server, Salvage Server, and Salvager (<emphasis role="bold">dafileserver</emphasis>, | |
2528 | <emphasis role="bold"> davolserver</emphasis>, <emphasis role="bold">salvageserver</emphasis>, and <emphasis | |
2529 | role="bold">dasalvager</emphasis> processes). Most sites should run the | |
2530 | Demand-Attach File Server, but the traditional/legacy File Server remains | |
2531 | an option. If you are uncertain whether to run the legacy File Server, | |
2532 | see <link linkend="DAFS">Appendix C, The Demand-Attach File Server</link>. | |
2533 | <orderedlist> | |
2534 | <listitem> | |
2535 | <para>Issue the <emphasis role="bold">bos create</emphasis> command to start the | |
2536 | <emphasis role="bold">dafs</emphasis> process. The commands appear here on multiple lines only for legibility. | |
2537 | ||
2538 | <itemizedlist> | |
2539 | <listitem> | |
2540 | <para>Create the <emphasis | |
2541 | role="bold">dafs</emphasis> process: | |
2542 | <programlisting> | |
2543 | # <emphasis role="bold">./bos create</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">dafs dafs /usr/afs/bin/dafileserver</emphasis> \ | |
2544 | <emphasis role="bold">/usr/afs/bin/davolserver /usr/afs/bin/salvageserver</emphasis> \ | |
2545 | <emphasis role="bold">/usr/afs/bin/dasalvager</emphasis> <emphasis role="bold">-localauth</emphasis> | |
2546 | </programlisting></para> | |
2547 | </listitem> | |
2548 | </itemizedlist> | |
2549 | </para> | |
2550 | ||
2551 | <para>Sometimes a message about Volume Location Database (VLDB) initialization appears, along with one or more instances | |
2552 | of an error message similar to the following:</para> | |
2553 | ||
2554 | <programlisting> | |
2555 | FSYNC_clientInit temporary failure (will retry) | |
2556 | </programlisting> | |
2557 | ||
2558 | <para>This message appears when the <emphasis role="bold">volserver</emphasis> process tries to start before the <emphasis | |
2559 | role="bold">fileserver</emphasis> process has completed its initialization. Wait a few minutes after the last such message | |
2560 | before continuing, to guarantee that both processes have started successfully. <indexterm> | |
2561 | <primary>commands</primary> | |
2562 | ||
2563 | <secondary>bos status</secondary> | |
2564 | </indexterm> <indexterm> | |
2565 | <primary>bos commands</primary> | |
2566 | ||
2567 | <secondary>status</secondary> | |
2568 | </indexterm></para> | |
2569 | ||
2570 | <para>You can verify that the <emphasis role="bold">dafs</emphasis> process has started | |
2571 | successfully by issuing the <emphasis role="bold">bos status</emphasis> command. Its output mentions two <computeroutput>proc | |
2572 | starts</computeroutput>.</para> | |
2573 | ||
2574 | <para> | |
2575 | <programlisting> | |
2576 | # <emphasis role="bold">./bos status</emphasis> <<replaceable>machine name</replaceable>> <emphasis role="bold">dafs -long -localauth</emphasis> | |
2577 | </programlisting></para> | |
2578 | </listitem> | |
2579 | ||
2580 | <listitem> | |
2581 | <para>Your next action depends on whether you have ever run AFS file server machines in the cell: <itemizedlist> | |
2582 | <indexterm> | |
2583 | <primary>commands</primary> | |
2584 | ||
2585 | <secondary>vos create</secondary> | |
2586 | ||
2587 | <tertiary>root.afs volume</tertiary> | |
2588 | </indexterm> | |
2589 | ||
2590 | <indexterm> | |
2591 | <primary>vos commands</primary> | |
2592 | ||
2593 | <secondary>create</secondary> | |
2594 | ||
2595 | <tertiary>root.afs volume</tertiary> | |
2596 | </indexterm> | |
2597 | ||
2598 | <indexterm> | |
2599 | <primary>root.afs volume</primary> | |
2600 | ||
2601 | <secondary>creating</secondary> | |
2602 | </indexterm> | |
2603 | ||
2604 | <indexterm> | |
2605 | <primary>volume</primary> | |
2606 | ||
2607 | <secondary>creating</secondary> | |
2608 | ||
2609 | <tertiary>root.afs</tertiary> | |
2610 | </indexterm> | |
2611 | ||
2612 | <indexterm> | |
2613 | <primary>creating</primary> | |
2614 | ||
2615 | <secondary>root.afs volume</secondary> | |
2616 | </indexterm> | |
2617 | ||
2618 | <listitem> | |
2619 | <para>If you are installing the first AFS server machine ever in the cell (that is, you are not upgrading the AFS | |
2620 | software from a previous version), create the first AFS volume, <emphasis role="bold">root.afs</emphasis>.</para> | |
2621 | ||
2622 | <para>For the <replaceable>partition name</replaceable> argument, substitute the name of one of the machine's AFS | |
2623 | server partitions (such as <emphasis role="bold">/vicepa</emphasis>).</para> | |
2624 | ||
2625 | <programlisting> | |
2626 | # <emphasis role="bold">./vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <emphasis | |
2627 | role="bold">root.afs</emphasis> \ | |
2628 | <emphasis role="bold">-localauth</emphasis> | |
2629 | </programlisting> | |
2630 | ||
2631 | <para>The Volume Server produces a message confirming that it created the volume on the specified partition. <indexterm> | |
2632 | <primary>commands</primary> | |
2633 | ||
2634 | <secondary>vos syncvldb</secondary> | |
2635 | </indexterm> <indexterm> | |
2636 | <primary>vos commands</primary> | |
2637 | ||
2638 | <secondary>syncvldb</secondary> | |
2639 | </indexterm> <indexterm> | |
2640 | <primary>commands</primary> | |
2641 | ||
2642 | <secondary>vos syncserv</secondary> | |
2643 | </indexterm> <indexterm> | |
2644 | <primary>vos commands</primary> | |
2645 | ||
2646 | <secondary>syncserv</secondary> | |
2647 | </indexterm></para> | |
2648 | </listitem> | |
2649 | </itemizedlist></para> | |
2650 | </listitem> | |
2651 | </orderedlist></para> | |
2652 | ||
2653 | <indexterm> | |
2654 | <primary>Update Server</primary> | |
2655 | ||
2656 | <secondary>starting server portion</secondary> | |
2657 | ||
2658 | <tertiary>first AFS machine</tertiary> | |
2659 | </indexterm> | |
2660 | ||
2661 | <indexterm> | |
2662 | <primary>upserver process</primary> | |
2663 | ||
2664 | <see>Update Server</see> | |
2665 | </indexterm> | |
2666 | ||
2667 | <indexterm> | |
2668 | <primary>starting</primary> | |
2669 | ||
2670 | <secondary>Update Server server portion</secondary> | |
2671 | ||
2672 | <tertiary>first AFS machine</tertiary> | |
2673 | </indexterm> | |
2674 | ||
2675 | <indexterm> | |
2676 | <primary>first AFS machine</primary> | |
2677 | ||
2678 | <secondary>Update Server server portion</secondary> | |
2679 | </indexterm> | |
2680 | ||
2681 | <indexterm> | |
2682 | <primary>first AFS machine</primary> | |
2683 | ||
2684 | <secondary>defining</secondary> | |
2685 | ||
2686 | <tertiary>as binary distribution machine</tertiary> | |
2687 | </indexterm> | |
2688 | ||
2689 | <indexterm> | |
2690 | <primary>first AFS machine</primary> | |
2691 | ||
2692 | <secondary>defining</secondary> | |
2693 | ||
2694 | <tertiary>as system control machine</tertiary> | |
2695 | </indexterm> | |
2696 | ||
2697 | <indexterm> | |
2698 | <primary>system control machine</primary> | |
2699 | </indexterm> | |
2700 | ||
2701 | <indexterm> | |
2702 | <primary>binary distribution machine</primary> | |
2703 | </indexterm> | |
2704 | </sect1> | |
2705 | ||
2706 | <sect1 id="HDRWQ62"> | |
2707 | <title>Clock Sync Considerations</title> | |
2708 | ||
2709 | <para>Keeping the clocks on all server and client machines in your cell synchronized is crucial to several functions, and in | |
2710 | particular to the correct operation of AFS's distributed database technology, Ubik. The chapter in the <emphasis>OpenAFS | |
2711 | Administration Guide</emphasis> about administering server machines explains how time skew can disturb Ubik's performance and | |
2712 | cause service outages in your cell.</para> | |
2713 | ||
2714 | <para>You should install and configure your time service independently of | |
2715 | AFS. Your Kerberos realm will also require a reliable time source, so your site | |
2716 | may already have one available.</para> | |
2717 | ||
2718 | <indexterm> | |
2719 | <primary>overview</primary> | |
2720 | ||
2721 | <secondary>installing client functionality on first machine</secondary> | |
2722 | </indexterm> | |
2723 | ||
2724 | <indexterm> | |
2725 | <primary>first AFS machine</primary> | |
2726 | ||
2727 | <secondary>client functionality</secondary> | |
2728 | ||
2729 | <tertiary>installing</tertiary> | |
2730 | </indexterm> | |
2731 | ||
2732 | <indexterm> | |
2733 | <primary>installing</primary> | |
2734 | ||
2735 | <secondary>client functionality</secondary> | |
2736 | ||
2737 | <tertiary>first AFS machine</tertiary> | |
2738 | </indexterm> | |
2739 | </sect1> | |
2740 | ||
2741 | <sect1 id="HDRWQ63"> | |
2742 | <title>Overview: Installing Client Functionality</title> | |
2743 | ||
2744 | <para>The machine you are installing is now an AFS file server machine | |
2745 | and database server machine. | |
2746 | Now make it a client machine by completing the following tasks: | |
2747 | <orderedlist> | |
2748 | <listitem> | |
2749 | <para>Define the machine's cell membership for client processes</para> | |
2750 | </listitem> | |
2751 | ||
2752 | <listitem> | |
2753 | <para>Create the client version of the <emphasis role="bold">CellServDB</emphasis> file</para> | |
2754 | </listitem> | |
2755 | ||
2756 | <listitem> | |
2757 | <para>Define cache location and size</para> | |
2758 | </listitem> | |
2759 | ||
2760 | <listitem> | |
2761 | <para>Create the <emphasis role="bold">/afs</emphasis> directory and start the Cache Manager</para> | |
2762 | </listitem> | |
2763 | </orderedlist></para> | |
2764 | ||
2765 | <indexterm> | |
2766 | <primary>Distribution</primary> | |
2767 | ||
2768 | <secondary>copying client files from</secondary> | |
2769 | ||
2770 | <tertiary>first AFS machine</tertiary> | |
2771 | </indexterm> | |
2772 | ||
2773 | <indexterm> | |
2774 | <primary>first AFS machine</primary> | |
2775 | ||
2776 | <secondary>copying</secondary> | |
2777 | ||
2778 | <tertiary>client files to local disk</tertiary> | |
2779 | </indexterm> | |
2780 | ||
2781 | <indexterm> | |
2782 | <primary>copying</primary> | |
2783 | ||
2784 | <secondary>client files to local disk</secondary> | |
2785 | ||
2786 | <tertiary>first AFS machine</tertiary> | |
2787 | </indexterm> | |
2788 | </sect1> | |
2789 | ||
2790 | <sect1 id="HDRWQ64"> | |
2791 | <title>Copying Client Files to the Local Disk</title> | |
2792 | ||
2793 | <para>You need only undertake the steps in this section, if you are using | |
2794 | a tar file distribution, or one built from scratch. Packaged distributions, | |
2795 | such as RPMs or DEBs will already have installed the necessary files in | |
2796 | the correct locations.</para> | |
2797 | ||
2798 | <para>Before installing and configuring the AFS client, copy the necessary files from the tarball to the local <emphasis | |
2799 | role="bold">/usr/vice/etc</emphasis> directory. <orderedlist> | |
2800 | <listitem> | |
2801 | <para>If you have not already done so, unpack the distribution | |
2802 | tarball for this machine's system type into a suitable location on | |
2803 | the filesystem, such as <emphasis role="bold">/tmp/afsdist</emphasis>. | |
2804 | If you use a different location, substitue that in the examples that | |
2805 | follow.</para> | |
2806 | </listitem> | |
2807 | ||
2808 | <listitem> | |
2809 | <para>Copy files to the local <emphasis role="bold">/usr/vice/etc</emphasis> directory.</para> | |
2810 | ||
2811 | <para>This step places a copy of the AFS initialization script (and related files, if applicable) into the <emphasis | |
2812 | role="bold">/usr/vice/etc</emphasis> directory. In the preceding instructions for incorporating AFS into the kernel, you | |
2813 | copied the script directly to the operating system's conventional location for initialization files. When you incorporate | |
2814 | AFS into the machine's startup sequence in a later step, you can choose to link the two files.</para> | |
2815 | ||
2816 | <para>On some system types that use a dynamic kernel loader program, you previously copied AFS library files into a | |
2817 | subdirectory of the <emphasis role="bold">/usr/vice/etc</emphasis> directory. On other system types, you copied the | |
2818 | appropriate AFS library file directly to the directory where the operating system accesses it. The following commands do | |
2819 | not copy or recopy the AFS library files into the <emphasis role="bold">/usr/vice/etc</emphasis> directory, because on | |
2820 | some system types the library files consume a large amount of space. If you want to copy them, add the <emphasis | |
2821 | role="bold">-r</emphasis> flag to the first <emphasis role="bold">cp</emphasis> command and skip the second <emphasis | |
2822 | role="bold">cp</emphasis> command.</para> | |
2823 | ||
2824 | <programlisting> | |
2825 | # <emphasis role="bold">cd /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis> | |
2826 | # <emphasis role="bold">cp -p * /usr/vice/etc</emphasis> | |
2827 | # <emphasis role="bold">cp -rp C /usr/vice/etc</emphasis> | |
2828 | </programlisting> | |
2829 | </listitem> | |
2830 | </orderedlist></para> | |
2831 | ||
2832 | <indexterm> | |
2833 | <primary>cell name</primary> | |
2834 | ||
2835 | <secondary>setting in client ThisCell file</secondary> | |
2836 | ||
2837 | <tertiary>first AFS machine</tertiary> | |
2838 | </indexterm> | |
2839 | ||
2840 | <indexterm> | |
2841 | <primary>setting</primary> | |
2842 | ||
2843 | <secondary>cell name in client ThisCell file</secondary> | |
2844 | ||
2845 | <tertiary>first AFS machine</tertiary> | |
2846 | </indexterm> | |
2847 | ||
2848 | <indexterm> | |
2849 | <primary>first AFS machine</primary> | |
2850 | ||
2851 | <secondary>ThisCell file (client)</secondary> | |
2852 | </indexterm> | |
2853 | ||
2854 | <indexterm> | |
2855 | <primary>first AFS machine</primary> | |
2856 | ||
2857 | <secondary>cell membership, defining</secondary> | |
2858 | ||
2859 | <tertiary>for client processes</tertiary> | |
2860 | </indexterm> | |
2861 | ||
2862 | <indexterm> | |
2863 | <primary>usr/vice/etc/ThisCell</primary> | |
2864 | ||
2865 | <see>ThisCell file (client)</see> | |
2866 | </indexterm> | |
2867 | ||
2868 | <indexterm> | |
2869 | <primary>ThisCell file (client)</primary> | |
2870 | ||
2871 | <secondary>first AFS machine</secondary> | |
2872 | </indexterm> | |
2873 | ||
2874 | <indexterm> | |
2875 | <primary>files</primary> | |
2876 | ||
2877 | <secondary>ThisCell (client)</secondary> | |
2878 | </indexterm> | |
2879 | </sect1> | |
2880 | ||
2881 | <sect1 id="HDRWQ65"> | |
2882 | <title>Defining Cell Membership for Client Processes</title> | |
2883 | ||
2884 | <para>Every AFS client machine has a copy of the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on its local disk | |
2885 | to define the machine's cell membership for the AFS client programs that run on it. The <emphasis | |
2886 | role="bold">ThisCell</emphasis> file you created in the <emphasis role="bold">/usr/afs/etc</emphasis> directory (in <link | |
2887 | linkend="HDRWQ51">Defining Cell Name and Membership for Server Processes</link>) is used only by server processes.</para> | |
2888 | ||
2889 | <para>Among other functions, the <emphasis role="bold">ThisCell</emphasis> file on a client machine determines the following: | |
2890 | <itemizedlist> | |
2891 | <listitem> | |
2892 | <para>The cell in which users gain tokens when they log onto the | |
2893 | machine, assuming it is using an AFS-modified login utility</para> | |
2894 | </listitem> | |
2895 | ||
2896 | <listitem> | |
2897 | <para>The cell in which users gain tokens by default when they issue | |
2898 | the <emphasis role="bold">aklog</emphasis> command</para> | |
2899 | </listitem> | |
2900 | ||
2901 | <listitem> | |
2902 | <para>The cell membership of the AFS server processes that the AFS | |
2903 | command interpreters on this machine contact by default</para> | |
2904 | </listitem> | |
2905 | </itemizedlist> | |
2906 | <orderedlist> | |
2907 | <listitem> | |
2908 | <para>Change to the <emphasis role="bold">/usr/vice/etc</emphasis> directory and remove the symbolic link created in <link | |
2909 | linkend="HDRWQ50">Starting the BOS Server</link>. <programlisting> | |
2910 | # <emphasis role="bold">cd /usr/vice/etc</emphasis> | |
2911 | # <emphasis role="bold">rm ThisCell</emphasis> | |
2912 | </programlisting></para> | |
2913 | </listitem> | |
2914 | ||
2915 | <listitem> | |
2916 | <para>Create the <emphasis role="bold">ThisCell</emphasis> file as a copy of the <emphasis | |
2917 | role="bold">/usr/afs/etc/ThisCell</emphasis> file. Defining the same local cell for both server and client processes leads | |
2918 | to the most consistent AFS performance. <programlisting> | |
2919 | # <emphasis role="bold">cp /usr/afs/etc/ThisCell ThisCell</emphasis> | |
2920 | </programlisting></para> | |
2921 | </listitem> | |
2922 | </orderedlist></para> | |
2923 | ||
2924 | <indexterm> | |
2925 | <primary>database server machine</primary> | |
2926 | ||
2927 | <secondary>entry in client CellServDB file</secondary> | |
2928 | ||
2929 | <tertiary>on first AFS machine</tertiary> | |
2930 | </indexterm> | |
2931 | ||
2932 | <indexterm> | |
2933 | <primary>usr/vice/etc/CellServDB</primary> | |
2934 | ||
2935 | <see>CellServDB file (client)</see> | |
2936 | </indexterm> | |
2937 | ||
2938 | <indexterm> | |
2939 | <primary>CellServDB file (client)</primary> | |
2940 | ||
2941 | <secondary>creating</secondary> | |
2942 | ||
2943 | <tertiary>on first AFS machine</tertiary> | |
2944 | </indexterm> | |
2945 | ||
2946 | <indexterm> | |
2947 | <primary>creating</primary> | |
2948 | ||
2949 | <secondary>CellServDB file (client)</secondary> | |
2950 | ||
2951 | <tertiary>first AFS machine</tertiary> | |
2952 | </indexterm> | |
2953 | ||
2954 | <indexterm> | |
2955 | <primary>CellServDB file (client)</primary> | |
2956 | ||
2957 | <secondary>required format</secondary> | |
2958 | </indexterm> | |
2959 | ||
2960 | <indexterm> | |
2961 | <primary>requirements</primary> | |
2962 | ||
2963 | <secondary>CellServDB file format (client version)</secondary> | |
2964 | </indexterm> | |
2965 | ||
2966 | <indexterm> | |
2967 | <primary>files</primary> | |
2968 | ||
2969 | <secondary>CellServDB (client)</secondary> | |
2970 | </indexterm> | |
2971 | ||
2972 | <indexterm> | |
2973 | <primary>first AFS machine</primary> | |
2974 | ||
2975 | <secondary>CellServDB file (client)</secondary> | |
2976 | </indexterm> | |
2977 | </sect1> | |
2978 | ||
2979 | <sect1 id="HDRWQ66"> | |
2980 | <title>Creating the Client CellServDB File</title> | |
2981 | ||
2982 | <para>The <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on a client machine's local disk lists the database | |
2983 | server machines for each cell that the local Cache Manager can contact. If there is no entry in the file for a cell, or if the | |
2984 | list of database server machines is wrong, then users working on this machine cannot access the cell. The chapter in the | |
2985 | <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines explains how to maintain the file after | |
2986 | creating it.</para> | |
2987 | ||
2988 | <para>As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it copies the contents of the | |
2989 | <emphasis role="bold">CellServDB</emphasis> file into kernel memory. The Cache Manager always consults the list in kernel memory | |
2990 | rather than the <emphasis role="bold">CellServDB</emphasis> file itself. Between reboots of the machine, you can use the | |
2991 | <emphasis role="bold">fs newcell</emphasis> command to update the list in kernel memory directly; see the chapter in the | |
2992 | <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines.</para> | |
2993 | ||
2994 | <para>The AFS distribution includes the file | |
2995 | <emphasis role="bold">CellServDB.dist</emphasis>. It includes an entry for | |
2996 | all AFS cells that agreed to share their database server machine | |
2997 | information at the time the distribution was | |
2998 | created. The definitive copy of this file is maintained at | |
2999 | grand.central.org, and updates may be obtained from | |
3000 | /afs/grand.central.org/service/CellServDB or | |
3001 | <ulink url="http://grand.central.org/dl/cellservdb/CellServDB"> | |
3002 | http://grand.central.org/dl/cellservdb/CellServDB</ulink></para> | |
3003 | ||
3004 | <para>The <emphasis role="bold">CellServDB.dist</emphasis> file can be a | |
3005 | good basis for the client <emphasis role="bold">CellServDB</emphasis> file, | |
3006 | because all of the entries in it use the correct format. You can add or | |
3007 | remove cell entries as you see fit. Depending on your cache manager | |
3008 | configuration, additional steps (as detailed in | |
3009 | <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>) may be | |
3010 | required to enable the Cache Manager to actually reach the cells.</para> | |
3011 | ||
3012 | <para>In this section, you add an entry for the local cell to the local <emphasis role="bold">CellServDB</emphasis> file. The | |
3013 | current working directory is still <emphasis role="bold">/usr/vice/etc</emphasis>. <orderedlist> | |
3014 | <listitem> | |
3015 | <para>Remove the symbolic link created in <link linkend="HDRWQ50">Starting the BOS Server</link> and rename the <emphasis | |
3016 | role="bold">CellServDB.sample</emphasis> file to <emphasis role="bold">CellServDB</emphasis>. <programlisting> | |
3017 | # <emphasis role="bold">rm CellServDB</emphasis> | |
3018 | # <emphasis role="bold">mv CellServDB.sample CellServDB</emphasis> | |
3019 | </programlisting></para> | |
3020 | </listitem> | |
3021 | ||
3022 | <listitem> | |
3023 | <para>Add an entry for the local cell to the <emphasis role="bold">CellServDB</emphasis> file. One easy method is to use | |
3024 | the <emphasis role="bold">cat</emphasis> command to append the contents of the server <emphasis | |
3025 | role="bold">/usr/afs/etc/CellServDB</emphasis> file to the client version. <programlisting> | |
3026 | # <emphasis role="bold">cat /usr/afs/etc/CellServDB >> CellServDB</emphasis> | |
3027 | </programlisting></para> | |
3028 | ||
3029 | <para>Then open the file in a text editor to verify that there are no blank lines, and that all entries have the required | |
3030 | format, which is described just following. The ordering of cells is not significant, but it can be convenient to have the | |
3031 | client machine's home cell at the top; move it there now if you wish. <itemizedlist> | |
3032 | <listitem> | |
3033 | <para>The first line of a cell's entry has the following format: <programlisting> | |
3034 | ><replaceable>cell_name</replaceable> #<replaceable>organization</replaceable> | |
3035 | </programlisting></para> | |
3036 | ||
3037 | <para>where <replaceable>cell_name</replaceable> is the cell's complete Internet domain name (for example, <emphasis | |
3038 | role="bold">example.com</emphasis>) and <replaceable>organization</replaceable> is an optional field that follows any | |
3039 | number of spaces and the number sign (<computeroutput>#</computeroutput>). By convention it names the organization | |
3040 | to which the cell corresponds (for example, the Example Corporation).</para> | |
3041 | </listitem> | |
3042 | ||
3043 | <listitem> | |
3044 | <para>After the first line comes a separate line for each database server machine. Each line has the following | |
3045 | format: <programlisting> | |
3046 | <replaceable>IP_address</replaceable> #<replaceable>machine_name</replaceable> | |
3047 | </programlisting></para> | |
3048 | ||
3049 | <para>where <replaceable>IP_address</replaceable> is the machine's IP address in dotted decimal format (for example, | |
3050 | 192.12.105.3). Following any number of spaces and the number sign (<computeroutput>#</computeroutput>) is | |
3051 | <replaceable>machine_name</replaceable>, the machine's fully-qualified hostname (for example, <emphasis | |
3052 | role="bold">db1.example.com</emphasis>). In this case, the number sign does not indicate a comment; | |
3053 | <replaceable>machine_name</replaceable> is a required field.</para> | |
3054 | </listitem> | |
3055 | </itemizedlist></para> | |
3056 | </listitem> | |
3057 | ||
3058 | <listitem> | |
3059 | <para>If the file includes cells that you do not wish users of this machine to access, remove their entries.</para> | |
3060 | </listitem> | |
3061 | </orderedlist></para> | |
3062 | ||
3063 | <para>The following example shows entries for two cells, each of which has three database server machines:</para> | |
3064 | ||
3065 | <programlisting> | |
3066 | >example.com #Example Corporation (home cell) | |
3067 | 192.12.105.3 #db1.example.com | |
3068 | 192.12.105.4 #db2.example.com | |
3069 | 192.12.105.55 #db3.example.com | |
3070 | >example.org #Example Organization cell | |
3071 | 138.255.68.93 #serverA.example.org | |
3072 | 138.255.68.72 #serverB.example.org | |
3073 | 138.255.33.154 #serverC.example.org | |
3074 | </programlisting> | |
3075 | ||
3076 | <indexterm> | |
3077 | <primary>cache</primary> | |
3078 | ||
3079 | <secondary>configuring</secondary> | |
3080 | ||
3081 | <tertiary>first AFS machine</tertiary> | |
3082 | </indexterm> | |
3083 | ||
3084 | <indexterm> | |
3085 | <primary>configuring</primary> | |
3086 | ||
3087 | <secondary>cache</secondary> | |
3088 | ||
3089 | <tertiary>first AFS machine</tertiary> | |
3090 | </indexterm> | |
3091 | ||
3092 | <indexterm> | |
3093 | <primary>setting</primary> | |
3094 | ||
3095 | <secondary>cache size and location</secondary> | |
3096 | ||
3097 | <tertiary>first AFS machine</tertiary> | |
3098 | </indexterm> | |
3099 | ||
3100 | <indexterm> | |
3101 | <primary>first AFS machine</primary> | |
3102 | ||
3103 | <secondary>cache size and location</secondary> | |
3104 | </indexterm> | |
3105 | </sect1> | |
3106 | ||
3107 | <sect1 id="HDRWQ67"> | |
3108 | <title>Configuring the Cache</title> | |
3109 | ||
3110 | <para>The Cache Manager uses a cache on the local disk or in machine memory to store local copies of files fetched from file | |
3111 | server machines. As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it sets basic cache | |
3112 | configuration parameters according to definitions in the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file. | |
3113 | The file has three fields: <orderedlist> | |
3114 | <listitem> | |
3115 | <para>The first field names the local directory on which to mount the AFS filespace. The conventional location is the | |
3116 | <emphasis role="bold">/afs</emphasis> directory.</para> | |
3117 | </listitem> | |
3118 | ||
3119 | <listitem> | |
3120 | <para>The second field defines the local disk directory to use for the disk cache. The conventional location is the | |
3121 | <emphasis role="bold">/usr/vice/cache</emphasis> directory, but you can specify an alternate directory if another | |
3122 | partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if the | |
3123 | machine uses a memory cache.</para> | |
3124 | </listitem> | |
3125 | ||
3126 | <listitem> | |
3127 | <para>The third field specifies the number of kilobyte (1024 byte) blocks to allocate for the cache.</para> | |
3128 | </listitem> | |
3129 | </orderedlist></para> | |
3130 | ||
3131 | <para>The values you define must meet the following requirements. <itemizedlist> | |
3132 | <listitem> | |
3133 | <para>On a machine using a disk cache, the Cache Manager expects always to be able to use the amount of space specified in | |
3134 | the third field. Failure to meet this requirement can cause serious problems, some of which can be repaired only by | |
3135 | rebooting. You must prevent non-AFS processes from filling up the cache partition. The simplest way is to devote a | |
3136 | partition to the cache exclusively.</para> | |
3137 | </listitem> | |
3138 | ||
3139 | <listitem> | |
3140 | <para>The amount of space available in memory or on the partition housing the disk cache directory imposes an absolute | |
3141 | limit on cache size.</para> | |
3142 | </listitem> | |
3143 | ||
3144 | <listitem> | |
3145 | <para>The maximum supported cache size can vary in each AFS release; see the <emphasis>OpenAFS Release Notes</emphasis> | |
3146 | for the current version.</para> | |
3147 | </listitem> | |
3148 | ||
3149 | <listitem> | |
3150 | <para>For a disk cache, you cannot specify a value in the third field that exceeds 95% of the space available on the | |
3151 | partition mounted at the directory named in the second field. If you violate this restriction, the <emphasis | |
3152 | role="bold">afsd</emphasis> program exits without starting the Cache Manager and prints an appropriate message on the | |
3153 | standard output stream. A value of 90% is more appropriate on most machines. Some operating systems do not | |
3154 | automatically reserve some space to prevent the partition from filling completely; for them, a smaller value (say, 80% to | |
3155 | 85% of the space available) is more appropriate.</para> | |
3156 | </listitem> | |
3157 | ||
3158 | <listitem> | |
3159 | <para>For a memory cache, you must leave enough memory for other processes and applications to run. If you try to allocate | |
3160 | more memory than is actually available, the <emphasis role="bold">afsd</emphasis> program exits without initializing the | |
3161 | Cache Manager and produces the following message on the standard output stream. <programlisting> | |
3162 | afsd: memCache allocation failure at <replaceable>number</replaceable> KB | |
3163 | </programlisting></para> | |
3164 | ||
3165 | <para>The <replaceable>number</replaceable> value is how many kilobytes were allocated just before the failure, and so | |
3166 | indicates the approximate amount of memory available.</para> | |
3167 | </listitem> | |
3168 | </itemizedlist></para> | |
3169 | ||
3170 | <para>Within these hard limits, the factors that determine appropriate cache size include the number of users working on the | |
3171 | machine, the size of the files with which they work, and (for a memory cache) the number of processes that run on the machine. | |
3172 | The higher the demand from these factors, the larger the cache needs to be to maintain good performance.</para> | |
3173 | ||
3174 | <para>Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better with | |
3175 | a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance depends on | |
3176 | the factors mentioned previously and is difficult to predict.</para> | |
3177 | ||
3178 | <para>Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually | |
3179 | unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on | |
3180 | memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can use | |
3181 | a smaller memory cache.</para> | |
3182 | ||
3183 | <sect2 id="HDRWQ68"> | |
3184 | <title>Configuring a Disk Cache</title> | |
3185 | ||
3186 | <note> | |
3187 | <para>Not all file system types that an operating system supports are necessarily supported for use as the cache partition. | |
3188 | For possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para> | |
3189 | </note> | |
3190 | ||
3191 | <para>To configure the disk cache, perform the following procedures: <orderedlist> | |
3192 | <listitem> | |
3193 | <para>Create the local directory to use for caching. The following instruction shows the conventional location, | |
3194 | <emphasis role="bold">/usr/vice/cache</emphasis>. If you are devoting a partition exclusively to caching, as | |
3195 | recommended, you must also configure it, make a file system on it, and mount it at the directory created in this step. | |
3196 | <programlisting> | |
3197 | # <emphasis role="bold">mkdir /usr/vice/cache</emphasis> | |
3198 | </programlisting></para> | |
3199 | </listitem> | |
3200 | ||
3201 | <listitem> | |
3202 | <para>Create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration parameters discussed | |
3203 | previously. The following instruction shows the standard mount location, <emphasis role="bold">/afs</emphasis>, and the | |
3204 | standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis>. <programlisting> | |
3205 | # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" > /usr/vice/etc/cacheinfo</emphasis> | |
3206 | </programlisting></para> | |
3207 | ||
3208 | <para>The following example defines the disk cache size as 50,000 KB:</para> | |
3209 | ||
3210 | <programlisting> | |
3211 | # <emphasis role="bold">echo "/afs:/usr/vice/cache:50000" > /usr/vice/etc/cacheinfo</emphasis> | |
3212 | </programlisting> | |
3213 | </listitem> | |
3214 | </orderedlist></para> | |
3215 | </sect2> | |
3216 | ||
3217 | <sect2 id="HDRWQ69"> | |
3218 | <title>Configuring a Memory Cache</title> | |
3219 | ||
3220 | <para>To configure a memory cache, create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration | |
3221 | parameters discussed previously. The following instruction shows the standard mount location, <emphasis | |
3222 | role="bold">/afs</emphasis>, and the standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis> (though the | |
3223 | exact value of the latter is irrelevant for a memory cache).</para> | |
3224 | ||
3225 | <programlisting> | |
3226 | # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" > /usr/vice/etc/cacheinfo</emphasis> | |
3227 | </programlisting> | |
3228 | ||
3229 | <para>The following example allocates 25,000 KB of memory for the cache.</para> | |
3230 | ||
3231 | <programlisting> | |
3232 | # <emphasis role="bold">echo "/afs:/usr/vice/cache:25000" > /usr/vice/etc/cacheinfo</emphasis> | |
3233 | </programlisting> | |
3234 | ||
3235 | <indexterm> | |
3236 | <primary>Cache Manager</primary> | |
3237 | ||
3238 | <secondary>first AFS machine</secondary> | |
3239 | </indexterm> | |
3240 | ||
3241 | <indexterm> | |
3242 | <primary>configuring</primary> | |
3243 | ||
3244 | <secondary>Cache Manager</secondary> | |
3245 | ||
3246 | <tertiary>first AFS machine</tertiary> | |
3247 | </indexterm> | |
3248 | ||
3249 | <indexterm> | |
3250 | <primary>first AFS machine</primary> | |
3251 | ||
3252 | <secondary>Cache Manager</secondary> | |
3253 | </indexterm> | |
3254 | ||
3255 | <indexterm> | |
3256 | <primary>afs (/afs) directory</primary> | |
3257 | ||
3258 | <secondary>creating</secondary> | |
3259 | ||
3260 | <tertiary>first AFS machine</tertiary> | |
3261 | </indexterm> | |
3262 | ||
3263 | <indexterm> | |
3264 | <primary>AFS initialization script</primary> | |
3265 | ||
3266 | <secondary>setting afsd parameters</secondary> | |
3267 | ||
3268 | <tertiary>first AFS machine</tertiary> | |
3269 | </indexterm> | |
3270 | ||
3271 | <indexterm> | |
3272 | <primary>first AFS machine</primary> | |
3273 | ||
3274 | <secondary>afsd command parameters</secondary> | |
3275 | </indexterm> | |
3276 | </sect2> | |
3277 | </sect1> | |
3278 | ||
3279 | <sect1 id="HDRWQ70"> | |
3280 | <title>Configuring the Cache Manager</title> | |
3281 | ||
3282 | <para>By convention, the Cache Manager mounts the AFS filespace on the local <emphasis role="bold">/afs</emphasis> directory. In | |
3283 | this section you create that directory.</para> | |
3284 | ||
3285 | <para>The <emphasis role="bold">afsd</emphasis> program sets several cache configuration parameters as it initializes the Cache | |
3286 | Manager, and starts daemons that improve performance. You can use the <emphasis role="bold">afsd</emphasis> command's arguments | |
3287 | to override the parameters' default values and to change the number of some of the daemons. Depending on the machine's cache | |
3288 | size, its amount of RAM, and how many people work on it, you can sometimes improve Cache Manager performance by overriding the | |
3289 | default values. For a discussion of all of the <emphasis role="bold">afsd</emphasis> command's arguments, see its reference page | |
3290 | in the <emphasis>OpenAFS Administration Reference</emphasis>.</para> | |
3291 | ||
3292 | <para>On platforms using the standard 'afs' initialisation script (this does not apply to Fedora or RHEL based distributions), the <emphasis role="bold">afsd</emphasis> command line in the AFS initialization script on each system type includes an | |
3293 | <computeroutput>OPTIONS</computeroutput> variable. You can use it to set nondefault values for the command's arguments, in one | |
3294 | of the following ways: <itemizedlist> | |
3295 | <listitem> | |
3296 | <para>You can create an <emphasis role="bold">afsd</emphasis> <emphasis>options file</emphasis> that sets values for | |
3297 | arguments to the <emphasis role="bold">afsd</emphasis> command. If the file exists, its contents are automatically | |
3298 | substituted for the <computeroutput>OPTIONS</computeroutput> variable in the AFS initialization script. The AFS | |
3299 | distribution for some system types includes an options file; on other system types, you must create it.</para> | |
3300 | ||
3301 | <para>You use two variables in the AFS initialization script to specify the path to the options file: | |
3302 | <computeroutput>CONFIG</computeroutput> and <computeroutput>AFSDOPT</computeroutput>. On system types that define a | |
3303 | conventional directory for configuration files, the <computeroutput>CONFIG</computeroutput> variable indicates it by | |
3304 | default; otherwise, the variable indicates an appropriate location.</para> | |
3305 | ||
3306 | <para>List the desired <emphasis role="bold">afsd</emphasis> options on a single line in the options file, separating each | |
3307 | option with one or more spaces. The following example sets the <emphasis role="bold">-stat</emphasis> argument to 2500, | |
3308 | the <emphasis role="bold">-daemons</emphasis> argument to 4, and the <emphasis role="bold">-volumes</emphasis> argument to | |
3309 | 100.</para> | |
3310 | ||
3311 | <programlisting> | |
3312 | -stat 2500 -daemons 4 -volumes 100 | |
3313 | </programlisting> | |
3314 | </listitem> | |
3315 | ||
3316 | <listitem> | |
3317 | <para>On a machine that uses a disk cache, you can set the <computeroutput>OPTIONS</computeroutput> variable in the AFS | |
3318 | initialization script to one of <computeroutput>$SMALL</computeroutput>, <computeroutput>$MEDIUM</computeroutput>, or | |
3319 | <computeroutput>$LARGE</computeroutput>. The AFS initialization script uses one of these settings if the <emphasis | |
3320 | role="bold">afsd</emphasis> options file named by the <computeroutput>AFSDOPT</computeroutput> variable does not exist. In | |
3321 | the script as distributed, the <computeroutput>OPTIONS</computeroutput> variable is set to the value | |
3322 | <computeroutput>$MEDIUM</computeroutput>.</para> | |
3323 | ||
3324 | <note> | |
3325 | <para>Do not set the <computeroutput>OPTIONS</computeroutput> variable to <computeroutput>$SMALL</computeroutput>, | |
3326 | <computeroutput>$MEDIUM</computeroutput>, or <computeroutput>$LARGE</computeroutput> on a machine that uses a memory | |
3327 | cache. The arguments it sets are appropriate only on a machine that uses a disk cache.</para> | |
3328 | </note> | |
3329 | ||
3330 | <para>The script (or on some system types the <emphasis role="bold">afsd</emphasis> options file named by the | |
3331 | <computeroutput>AFSDOPT</computeroutput> variable) defines a value for each of <computeroutput>SMALL</computeroutput>, | |
3332 | <computeroutput>MEDIUM</computeroutput>, and <computeroutput>LARGE</computeroutput> that sets <emphasis | |
3333 | role="bold">afsd</emphasis> command arguments appropriately for client machines of different sizes: <itemizedlist> | |
3334 | <listitem> | |
3335 | <para><computeroutput>SMALL</computeroutput> is suitable for a small machine that serves one or two users and has | |
3336 | approximately 8 MB of RAM and a 20-MB cache</para> | |
3337 | </listitem> | |
3338 | ||
3339 | <listitem> | |
3340 | <para><computeroutput>MEDIUM</computeroutput> is suitable for a medium-sized machine that serves two to six users | |
3341 | and has 16 MB of RAM and a 40-MB cache</para> | |
3342 | </listitem> | |
3343 | ||
3344 | <listitem> | |
3345 | <para><computeroutput>LARGE</computeroutput> is suitable for a large machine that serves five to ten users and has | |
3346 | 32 MB of RAM and a 100-MB cache</para> | |
3347 | </listitem> | |
3348 | </itemizedlist></para> | |
3349 | </listitem> | |
3350 | ||
3351 | <listitem> | |
3352 | <para>You can choose not to create an <emphasis role="bold">afsd</emphasis> options file and to set the | |
3353 | <computeroutput>OPTIONS</computeroutput> variable in the initialization script to a null value rather than to the default | |
3354 | <computeroutput>$MEDIUM</computeroutput> value. You can then either set arguments directly on the <emphasis | |
3355 | role="bold">afsd</emphasis> command line in the script, or set no arguments (and so accept default values for all Cache | |
3356 | Manager parameters).</para> | |
3357 | </listitem> | |
3358 | </itemizedlist> | |
3359 | ||
3360 | <note> | |
3361 | <para>If you are running on a Fedora or RHEL based system, the | |
3362 | openafs-client initialization script behaves differently from that | |
3363 | described above. It sources /etc/sysconfig/openafs, in which the | |
3364 | AFSD_ARGS variable may be set to contain any, or all, of the afsd options | |
3365 | detailed. Note that this script does not support setting an OPTIONS | |
3366 | variable, or the SMALL, MEDIUM and LARGE methods of defining cache size | |
3367 | </para> | |
3368 | </note> | |
3369 | ||
3370 | <orderedlist> | |
3371 | <listitem> | |
3372 | <para>Create the local directory on which to mount the AFS filespace, by convention <emphasis role="bold">/afs</emphasis>. | |
3373 | If the directory already exists, verify that it is empty. <programlisting> | |
3374 | # <emphasis role="bold">mkdir /afs</emphasis> | |
3375 | </programlisting></para> | |
3376 | </listitem> | |
3377 | ||
3378 | <listitem> | |
3379 | <para>On non-package based Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis | |
3380 | role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory, removing | |
3381 | the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting> | |
3382 | # <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis> | |
3383 | </programlisting></para> | |
3384 | </listitem> | |
3385 | ||
3386 | <listitem> | |
3387 | <para>Edit the machine's AFS initialization script or <emphasis role="bold">afsd</emphasis> options file to set | |
3388 | appropriate values for <emphasis role="bold">afsd</emphasis> command parameters. The script resides in the indicated | |
3389 | location on each system type: <itemizedlist> | |
3390 | <listitem> | |
3391 | <para>On Fedora and RHEL systems, <emphasis role="bold">/etc/sysconfg/openafs</emphasis></para> | |
3392 | </listitem> | |
3393 | ||
3394 | <listitem> | |
3395 | <para>On non-package based Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis | |
3396 | role="bold">afsd</emphasis> options file)</para> | |
3397 | </listitem> | |
3398 | ||
3399 | <listitem> | |
3400 | <para>On Solaris systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para> | |
3401 | </listitem> | |
3402 | </itemizedlist></para> | |
3403 | ||
3404 | <para>Use one of the methods described in the introduction to this section to add the following flags to the <emphasis | |
3405 | role="bold">afsd</emphasis> command line. If you intend for the machine to remain an AFS client, also set any | |
3406 | performance-related arguments you wish. <itemizedlist> | |
3407 | <listitem> | |
3408 | <para>Add the <emphasis role="bold">-memcache</emphasis> flag if the machine is to use a memory cache.</para> | |
3409 | </listitem> | |
3410 | ||
3411 | <listitem> | |
3412 | <para>Add the <emphasis role="bold">-verbose</emphasis> flag to display a trace of the Cache Manager's | |
3413 | initialization on the standard output stream.</para> | |
3414 | </listitem> | |
3415 | </itemizedlist></para> | |
3416 | </listitem> | |
3417 | </orderedlist> | |
3418 | <note><para>In order to successfully complete the instructions in the | |
3419 | remainder of this guide, it is important that the machine does not have | |
3420 | a synthetic root (as discussed in <link linkend="HDRWQ91">Enabling Access | |
3421 | to Foreign Cells</link>). As some distributions ship with this enabled, it | |
3422 | may be necessary to remove any occurences of the | |
3423 | <emphasis role="bold">-dynroot</emphasis> and | |
3424 | <emphasis role="bold">-afsdb</emphasis> options from both the AFS | |
3425 | initialisation script and options file. If this functionality is | |
3426 | required it may be renabled as detailed in | |
3427 | <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>. | |
3428 | </para></note> | |
3429 | </para> | |
3430 | ||
3431 | <indexterm> | |
3432 | <primary>overview</primary> | |
3433 | ||
3434 | <secondary>completing installation of first machine</secondary> | |
3435 | </indexterm> | |
3436 | ||
3437 | <indexterm> | |
3438 | <primary>first AFS machine</primary> | |
3439 | ||
3440 | <secondary>completion of installation</secondary> | |
3441 | </indexterm> | |
3442 | </sect1> | |
3443 | ||
3444 | <sect1 id="HDRWQ71"> | |
3445 | <title>Overview: Completing the Installation of the First AFS Machine</title> | |
3446 | ||
3447 | <para>The machine is now configured as an AFS file server and client machine. In this final phase of the installation, you | |
3448 | initialize the Cache Manager and then create the upper levels of your AFS filespace, among other procedures. The procedures are: | |
3449 | <orderedlist> | |
3450 | <listitem> | |
3451 | <para>Verify that the initialization script works correctly, and incorporate it into the operating system's startup and | |
3452 | shutdown sequence</para> | |
3453 | </listitem> | |
3454 | ||
3455 | <listitem> | |
3456 | <para>Create and mount top-level volumes</para> | |
3457 | </listitem> | |
3458 | ||
3459 | <listitem> | |
3460 | <para>Create and mount volumes to store system binaries in AFS</para> | |
3461 | </listitem> | |
3462 | ||
3463 | <listitem> | |
3464 | <para>Enable access to foreign cells</para> | |
3465 | </listitem> | |
3466 | ||
3467 | <listitem> | |
3468 | <para>Institute additional security measures</para> | |
3469 | </listitem> | |
3470 | ||
3471 | <listitem> | |
3472 | <para>Remove client functionality if desired</para> | |
3473 | </listitem> | |
3474 | </orderedlist></para> | |
3475 | ||
3476 | <indexterm> | |
3477 | <primary>AFS initialization script</primary> | |
3478 | ||
3479 | <secondary>verifying on first AFS machine</secondary> | |
3480 | </indexterm> | |
3481 | ||
3482 | <indexterm> | |
3483 | <primary>AFS initialization script</primary> | |
3484 | ||
3485 | <secondary>running</secondary> | |
3486 | ||
3487 | <tertiary>first AFS machine</tertiary> | |
3488 | </indexterm> | |
3489 | ||
3490 | <indexterm> | |
3491 | <primary>first AFS machine</primary> | |
3492 | ||
3493 | <secondary>AFS initialization script</secondary> | |
3494 | ||
3495 | <tertiary>running/verifying</tertiary> | |
3496 | </indexterm> | |
3497 | ||
3498 | <indexterm> | |
3499 | <primary>running AFS init. script</primary> | |
3500 | ||
3501 | <secondary>first AFS machine</secondary> | |
3502 | </indexterm> | |
3503 | ||
3504 | <indexterm> | |
3505 | <primary>invoking AFS init. script</primary> | |
3506 | ||
3507 | <see>running</see> | |
3508 | </indexterm> | |
3509 | </sect1> | |
3510 | ||
3511 | <sect1 id="HDRWQ72"> | |
3512 | <title>Verifying the AFS Initialization Script</title> | |
3513 | ||
3514 | <para>At this point you run the AFS initialization script to verify that it correctly invokes all of the necessary programs and | |
3515 | AFS processes, and that they start correctly. The following are the relevant commands: <itemizedlist> | |
3516 | <listitem> | |
3517 | <para>The command that dynamically loads AFS modifications into the kernel, on some system types (not applicable if the | |
3518 | kernel has AFS modifications built in)</para> | |
3519 | </listitem> | |
3520 | ||
3521 | <listitem> | |
3522 | <para>The <emphasis role="bold">bosserver</emphasis> command, which starts the BOS Server; it in turn starts the server | |
3523 | processes for which you created entries in the <emphasis role="bold">/usr/afs/local/BosConfig</emphasis> file</para> | |
3524 | </listitem> | |
3525 | ||
3526 | <listitem> | |
3527 | <para>The <emphasis role="bold">afsd</emphasis> command, which initializes the Cache Manager</para> | |
3528 | </listitem> | |
3529 | </itemizedlist></para> | |
3530 | ||
3531 | <para>On system types that use a dynamic loader program, you must reboot the machine before running the initialization script, | |
3532 | so that it can freshly load AFS modifications into the kernel.</para> | |
3533 | ||
3534 | <para>If there are problems during the initialization, attempt to resolve them. The OpenAFS mailing lists can provide assistance if necessary. | |
3535 | ||
3536 | <orderedlist> | |
3537 | <indexterm> | |
3538 | <primary>commands</primary> | |
3539 | ||
3540 | <secondary>bos shutdown</secondary> | |
3541 | </indexterm> | |
3542 | ||
3543 | <indexterm> | |
3544 | <primary>bos commands</primary> | |
3545 | ||
3546 | <secondary>shutdown</secondary> | |
3547 | </indexterm> | |
3548 | ||
3549 | <listitem> | |
3550 | <para>Issue the <emphasis role="bold">bos shutdown</emphasis> command to shut down the AFS server processes other than the | |
3551 | BOS Server. Include the <emphasis role="bold">-wait</emphasis> flag to delay return of the command shell prompt until all | |
3552 | processes shut down completely. <programlisting> | |
3553 | # <emphasis role="bold">/usr/afs/bin/bos shutdown</emphasis> <<replaceable>machine name</replaceable>> <emphasis | |
3554 | role="bold">-wait</emphasis> | |
3555 | </programlisting></para> | |
3556 | </listitem> | |
3557 | ||
3558 | <listitem> | |
3559 | <para>Issue the <emphasis role="bold">ps</emphasis> command to learn the <emphasis role="bold">bosserver</emphasis> | |
3560 | process's process ID number (PID), and then the <emphasis role="bold">kill</emphasis> command to stop it. <programlisting> | |
3561 | # <emphasis role="bold">ps</emphasis> <replaceable>appropriate_ps_options</replaceable> <emphasis role="bold">| grep bosserver</emphasis> | |
3562 | # <emphasis role="bold">kill</emphasis> <replaceable>bosserver_PID</replaceable> | |
3563 | </programlisting></para> | |
3564 | </listitem> | |
3565 | ||
3566 | <listitem> | |
3567 | <para>Issue the appropriate commands to run the AFS initialization script for this system type.</para> | |
3568 | ||
3569 | <para><emphasis role="bold">On Linux systems:</emphasis> <orderedlist> | |
3570 | <listitem> | |
3571 | <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. | |
3572 | <programlisting> | |
3573 | # <emphasis role="bold">cd /</emphasis> | |
3574 | # <emphasis role="bold">shutdown -r now</emphasis> | |
3575 | login: <emphasis role="bold">root</emphasis> | |
3576 | Password: <replaceable>root_password</replaceable> | |
3577 | </programlisting></para> | |
3578 | </listitem> | |
3579 | ||
3580 | <listitem> | |
3581 | <para>Run the AFS initialization scripts. | |
3582 | <programlisting> | |
3583 | # <emphasis role="bold">/etc/rc.d/init.d/openafs-client start</emphasis> | |
3584 | # <emphasis role="bold">/etc/rc.d/init.d/openafs-server start</emphasis> | |
3585 | </programlisting></para> | |
3586 | </listitem> | |
3587 | </orderedlist></para> | |
3588 | ||
3589 | <indexterm> | |
3590 | <primary>Solaris</primary> | |
3591 | ||
3592 | <secondary>AFS initialization script</secondary> | |
3593 | ||
3594 | <tertiary>on first AFS machine</tertiary> | |
3595 | </indexterm> | |
3596 | ||
3597 | <para><emphasis role="bold">On Solaris systems:</emphasis> <orderedlist> | |
3598 | <listitem> | |
3599 | <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. | |
3600 | <programlisting> | |
3601 | # <emphasis role="bold">cd /</emphasis> | |
3602 | # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis> | |
3603 | login: <emphasis role="bold">root</emphasis> | |
3604 | Password: <replaceable>root_password</replaceable> | |
3605 | </programlisting></para> | |
3606 | </listitem> | |
3607 | ||
3608 | <listitem> | |
3609 | <para>Run the AFS initialization script. <programlisting> | |
3610 | # <emphasis role="bold">/etc/init.d/afs start</emphasis> | |
3611 | </programlisting></para> | |
3612 | </listitem> | |
3613 | </orderedlist></para> | |
3614 | </listitem> | |
3615 | ||
3616 | <listitem> | |
3617 | <para>Wait for the message that confirms that Cache Manager initialization is complete.</para> | |
3618 | ||
3619 | <para>On machines that use a disk cache, it can take a while to initialize the Cache Manager for the first time, because | |
3620 | the <emphasis role="bold">afsd</emphasis> program must create all of the <emphasis | |
3621 | role="bold">V</emphasis><replaceable>n</replaceable> files in the cache directory. Subsequent Cache Manager | |
3622 | initializations do not take nearly as long, because the <emphasis role="bold">V</emphasis><replaceable>n</replaceable> | |
3623 | files already exist.</para> | |
3624 | </listitem> | |
3625 | <listitem> | |
3626 | ||
3627 | <indexterm> | |
3628 | <primary>commands</primary> | |
3629 | <secondary>aklog</secondary> | |
3630 | </indexterm> | |
3631 | ||
3632 | <indexterm> | |
3633 | <primary>aklog command</primary> | |
3634 | </indexterm> | |
3635 | ||
3636 | <para>If you are working with an existing cell which uses | |
3637 | <emphasis role="bold">kaserver</emphasis> for authentication, | |
3638 | please recall the note in | |
3639 | <link linkend="KAS003">Using this Appendix</link> detailing the | |
3640 | substitution of <emphasis role="bold">kinit</emphasis> and | |
3641 | <emphasis role="bold">aklog</emphasis> with | |
3642 | <emphasis role="bold">klog</emphasis>.</para> | |
3643 | ||
3644 | <para>As a basic test of correct AFS functioning, issue the | |
3645 | <emphasis role="bold">kinit</emphasis> and | |
3646 | <emphasis role="bold">aklog</emphasis> commands to authenticate | |
3647 | as the <emphasis role="bold">admin</emphasis> user. | |
3648 | Provide the password (<replaceable>admin_passwd</replaceable>) you | |
3649 | defined in <link linkend="HDRWQ53">Initializing Cell Security</link>.</para> | |
3650 | ||
3651 | <programlisting> | |
3652 | # <emphasis role="bold">kinit admin</emphasis> | |
3653 | Password: <replaceable>admin_passwd</replaceable> | |
3654 | # <emphasis role="bold">aklog</emphasis> | |
3655 | </programlisting> | |
3656 | ||
3657 | <indexterm> | |
3658 | <primary>commands</primary> | |
3659 | ||
3660 | <secondary>tokens</secondary> | |
3661 | </indexterm> | |
3662 | ||
3663 | <indexterm> | |
3664 | <primary>tokens command</primary> | |
3665 | </indexterm> | |
3666 | </listitem> | |
3667 | ||
3668 | <listitem> | |
3669 | <para>Issue the <emphasis role="bold">tokens</emphasis> command to | |
3670 | verify that the <emphasis role="bold">aklog</emphasis> | |
3671 | command worked correctly. If it did, the output looks similar to the following example for the <emphasis | |
3672 | role="bold">example.com</emphasis> cell, where <emphasis role="bold">admin</emphasis>'s AFS UID is 1. If the output does not | |
3673 | seem correct, resolve the problem. Changes to the AFS initialization script are possibly necessary. The OpenAFS mailing lists can provide assistance as necessary. <programlisting> | |
3674 | # <emphasis role="bold">tokens</emphasis> | |
3675 | Tokens held by the Cache Manager: | |
3676 | User's (AFS ID 1) tokens for afs@example.com [Expires May 22 11:52] | |
3677 | --End of list-- | |
3678 | </programlisting></para> | |
3679 | </listitem> | |
3680 | ||
3681 | <listitem> | |
3682 | <para>Issue the <emphasis role="bold">bos status</emphasis> command to verify that the output for each process reads | |
3683 | <computeroutput>Currently running normally</computeroutput>. <programlisting> | |
3684 | # <emphasis role="bold">/usr/afs/bin/bos status</emphasis> <<replaceable>machine name</replaceable>> | |
3685 | </programlisting> <indexterm> | |
3686 | <primary>fs commands</primary> | |
3687 | ||
3688 | <secondary>checkvolumes</secondary> | |
3689 | </indexterm> <indexterm> | |
3690 | <primary>commands</primary> | |
3691 | ||
3692 | <secondary>fs checkvolumes</secondary> | |
3693 | </indexterm></para> | |
3694 | </listitem> | |
3695 | ||
3696 | <listitem> | |
3697 | <para>Change directory to the local file system root (<emphasis role="bold">/</emphasis>) and issue the <emphasis | |
3698 | role="bold">fs checkvolumes</emphasis> command. <programlisting> | |
3699 | # <emphasis role="bold">cd /</emphasis> | |
3700 | # <emphasis role="bold">/usr/afs/bin/fs checkvolumes</emphasis> | |
3701 | </programlisting></para> | |
3702 | </listitem> | |
3703 | </orderedlist></para> | |
3704 | ||
3705 | <indexterm> | |
3706 | <primary>AFS initialization script</primary> | |
3707 | ||
3708 | <secondary>adding to machine startup sequence</secondary> | |
3709 | ||
3710 | <tertiary>first AFS machine</tertiary> | |
3711 | </indexterm> | |
3712 | ||
3713 | <indexterm> | |
3714 | <primary>installing</primary> | |
3715 | ||
3716 | <secondary>AFS initialization script</secondary> | |
3717 | ||
3718 | <tertiary>first AFS machine</tertiary> | |
3719 | </indexterm> | |
3720 | ||
3721 | <indexterm> | |
3722 | <primary>first AFS machine</primary> | |
3723 | ||
3724 | <secondary>AFS initialization script</secondary> | |
3725 | ||
3726 | <tertiary>activating</tertiary> | |
3727 | </indexterm> | |
3728 | ||
3729 | <indexterm> | |
3730 | <primary>activating AFS init. script</primary> | |
3731 | ||
3732 | <see>installing</see> | |
3733 | </indexterm> | |
3734 | </sect1> | |
3735 | ||
3736 | <sect1 id="HDRWQ73"> | |
3737 | <title>Activating the AFS Initialization Script</title> | |
3738 | ||
3739 | <para>Now that you have confirmed that the AFS initialization script works correctly, take the action necessary to have it run | |
3740 | automatically at each reboot. Proceed to the instructions for your system type: <itemizedlist> | |
3741 | <listitem> | |
3742 | <para><link linkend="HDRWQ78">Activating the Script on Linux Systems</link></para> | |
3743 | </listitem> | |
3744 | ||
3745 | <listitem> | |
3746 | <para><link linkend="HDRWQ79">Activating the Script on Solaris Systems</link></para> | |
3747 | </listitem> | |
3748 | </itemizedlist></para> | |
3749 | <indexterm> | |
3750 | <primary>Linux</primary> | |
3751 | ||
3752 | <secondary>AFS initialization script</secondary> | |
3753 | ||
3754 | <tertiary>on first AFS machine</tertiary> | |
3755 | </indexterm> | |
3756 | ||
3757 | <sect2 id="HDRWQ78"> | |
3758 | <title>Activating the Script on Linux Systems</title> | |
3759 | ||
3760 | <orderedlist> | |
3761 | <listitem> | |
3762 | <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis role="bold">openafs-client</emphasis> and <emphasis role="bold">openafs-server</emphasis> | |
3763 | configuration variables. Based on the instruction in the AFS initialization file that begins with the string | |
3764 | <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic links that incorporate the | |
3765 | script into the Linux startup and shutdown sequence. <programlisting> | |
3766 | # <emphasis role="bold">/sbin/chkconfig --add openafs-client</emphasis> | |
3767 | # <emphasis role="bold">/sbin/chkconfig --add openafs-server</emphasis> | |
3768 | </programlisting></para> | |
3769 | </listitem> | |
3770 | ||
3771 | <listitem> | |
3772 | <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the | |
3773 | <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/rc.d/init.d</emphasis> directories, and | |
3774 | copies of the <emphasis role="bold">afsd</emphasis> options file in both the <emphasis | |
3775 | role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/sysconfig</emphasis> directories. If you want to avoid | |
3776 | potential confusion by guaranteeing that the two copies of each file are always the same, create a link between them. You | |
3777 | can always retrieve the original script or options file from the AFS CD-ROM if necessary. <programlisting> | |
3778 | # <emphasis role="bold">cd /usr/vice/etc</emphasis> | |
3779 | # <emphasis role="bold">rm afs.rc afs.conf</emphasis> | |
3780 | # <emphasis role="bold">ln -s /etc/rc.d/init.d/afs afs.rc</emphasis> | |
3781 | # <emphasis role="bold">ln -s /etc/sysconfig/afs afs.conf</emphasis> | |
3782 | </programlisting></para> | |
3783 | </listitem> | |
3784 | ||
3785 | <listitem> | |
3786 | <para>Proceed to <link linkend="HDRWQ80">Configuring the Top Levels of the AFS Filespace</link>.</para> | |
3787 | </listitem> | |
3788 | </orderedlist> | |
3789 | ||
3790 | <indexterm> | |
3791 | <primary>Solaris</primary> | |
3792 | ||
3793 | <secondary>AFS initialization script</secondary> | |
3794 | ||
3795 | <tertiary>on first AFS machine</tertiary> | |
3796 | </indexterm> | |
3797 | </sect2> | |
3798 | ||
3799 | <sect2 id="HDRWQ79"> | |
3800 | <title>Activating the Script on Solaris Systems</title> | |
3801 | ||
3802 | <orderedlist> | |
3803 | <listitem> | |
3804 | <para>Change to the <emphasis role="bold">/etc/init.d</emphasis> directory and issue the <emphasis role="bold">ln | |
3805 | -s</emphasis> command to create symbolic links that incorporate the AFS initialization script into the Solaris startup and | |
3806 | shutdown sequence. <programlisting> | |
3807 | # <emphasis role="bold">cd /etc/init.d</emphasis> | |
3808 | # <emphasis role="bold">ln -s ../init.d/afs /etc/rc3.d/S99afs</emphasis> | |
3809 | # <emphasis role="bold">ln -s ../init.d/afs /etc/rc0.d/K66afs</emphasis> | |
3810 | </programlisting></para> | |
3811 | </listitem> | |
3812 | ||
3813 | <listitem> | |
3814 | <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the | |
3815 | <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If you want | |
3816 | to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always | |
3817 | retrieve the original script from the AFS CD-ROM if necessary. <programlisting> | |
3818 | # <emphasis role="bold">cd /usr/vice/etc</emphasis> | |
3819 | # <emphasis role="bold">rm afs.rc</emphasis> | |
3820 | # <emphasis role="bold">ln -s /etc/init.d/afs afs.rc</emphasis> | |
3821 | </programlisting></para> | |
3822 | </listitem> | |
3823 | </orderedlist> | |
3824 | ||
3825 | <indexterm> | |
3826 | <primary>AFS filespace</primary> | |
3827 | ||
3828 | <secondary>configuring top levels</secondary> | |
3829 | </indexterm> | |
3830 | ||
3831 | <indexterm> | |
3832 | <primary>configuring</primary> | |
3833 | ||
3834 | <secondary>AFS filespace (top levels)</secondary> | |
3835 | </indexterm> | |
3836 | </sect2> | |
3837 | </sect1> | |
3838 | ||
3839 | <sect1 id="HDRWQ80"> | |
3840 | <title>Configuring the Top Levels of the AFS Filespace</title> | |
3841 | ||
3842 | <para>If you have not previously run AFS in your cell, you now configure the top levels of your cell's AFS filespace. If you | |
3843 | have run a previous version of AFS, the filespace is already configured. Proceed to <link linkend="HDRWQ83">Storing AFS Binaries | |
3844 | in AFS</link>. <indexterm> | |
3845 | <primary>root.cell volume</primary> | |
3846 | ||
3847 | <secondary>creating and replicating</secondary> | |
3848 | </indexterm> <indexterm> | |
3849 | <primary>volume</primary> | |
3850 | ||
3851 | <secondary>creating</secondary> | |
3852 | ||
3853 | <tertiary>root.cell</tertiary> | |
3854 | </indexterm> <indexterm> | |
3855 | <primary>creating</primary> | |
3856 | ||
3857 | <secondary>root.cell volume</secondary> | |
3858 | </indexterm></para> | |
3859 | ||
3860 | <para>You created the <emphasis role="bold">root.afs</emphasis> volume in <link linkend="HDRWQ60">Starting the File Server, | |
3861 | Volume Server, and Salvager</link>, and the Cache Manager mounted it automatically on the local <emphasis | |
3862 | role="bold">/afs</emphasis> directory when you ran the AFS initialization script in <link linkend="HDRWQ72">Verifying the AFS | |
3863 | Initialization Script</link>. You now set the access control list (ACL) on the <emphasis role="bold">/afs</emphasis> directory; | |
3864 | creating, mounting, and setting the ACL are the three steps required when creating any volume.</para> | |
3865 | ||
3866 | <para>After setting the ACL on the <emphasis role="bold">root.afs</emphasis> volume, you create your cell's <emphasis | |
3867 | role="bold">root.cell</emphasis> volume, mount it as a subdirectory of the <emphasis role="bold">/afs</emphasis> directory, and | |
3868 | set the ACL. Create both a read/write and a regular mount point for the <emphasis role="bold">root.cell</emphasis> volume. The | |
3869 | read/write mount point enables you to access the read/write version of replicated volumes when necessary. Creating both mount | |
3870 | points essentially creates separate read-only and read-write copies of your filespace, and enables the Cache Manager to traverse | |
3871 | the filespace on a read-only path or read/write path as appropriate. For further discussion of these concepts, see the chapter | |
3872 | in the <emphasis>OpenAFS Administration Guide</emphasis> about administering volumes. <indexterm> | |
3873 | <primary>root.afs volume</primary> | |
3874 | ||
3875 | <secondary>replicating</secondary> | |
3876 | </indexterm> <indexterm> | |
3877 | <primary>volume</primary> | |
3878 | ||
3879 | <secondary>replicating root.afs and root.cell</secondary> | |
3880 | </indexterm> <indexterm> | |
3881 | <primary>replicating volumes</primary> | |
3882 | </indexterm></para> | |
3883 | ||
3884 | <para>Then replicate both the <emphasis role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes. | |
3885 | This is required if you want to replicate any other volumes in your cell, because all volumes mounted above a replicated volume | |
3886 | must themselves be replicated in order for the Cache Manager to access the replica.</para> | |
3887 | ||
3888 | <para>When the <emphasis role="bold">root.afs</emphasis> volume is replicated, the Cache Manager is programmed to access its | |
3889 | read-only version (<emphasis role="bold">root.afs.readonly</emphasis>) whenever possible. To make changes to the contents of the | |
3890 | <emphasis role="bold">root.afs</emphasis> volume (when, for example, you mount another cell's <emphasis | |
3891 | role="bold">root.cell</emphasis> volume at the second level in your filespace), you must mount the <emphasis | |
3892 | role="bold">root.afs</emphasis> volume temporarily, make the changes, release the volume and remove the temporary mount point. | |
3893 | For instructions, see <link linkend="HDRWQ91">Enabling Access to Foreign Cells</link>. <indexterm> | |
3894 | <primary>fs commands</primary> | |
3895 | ||
3896 | <secondary>setacl</secondary> | |
3897 | </indexterm> <indexterm> | |
3898 | <primary>commands</primary> | |
3899 | ||
3900 | <secondary>fs setacl</secondary> | |
3901 | </indexterm> <indexterm> | |
3902 | <primary>access control list (ACL), setting</primary> | |
3903 | </indexterm> <indexterm> | |
3904 | <primary>setting</primary> | |
3905 | ||
3906 | <secondary>ACL</secondary> | |
3907 | </indexterm> <orderedlist> | |
3908 | <listitem> | |
3909 | <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to edit the ACL on the <emphasis | |
3910 | role="bold">/afs</emphasis> directory. Add an entry that grants the <emphasis role="bold">l</emphasis> (<emphasis | |
3911 | role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permissions | |
3912 | to the <emphasis role="bold">system:anyuser</emphasis> group, to enable all AFS users who can reach your cell to traverse | |
3913 | through the directory. If you prefer to enable access only to locally authenticated users, substitute the <emphasis | |
3914 | role="bold">system:authuser</emphasis> group.</para> | |
3915 | ||
3916 | <para>Note that there is already an ACL entry that grants all seven access rights to the <emphasis | |
3917 | role="bold">system:administrators</emphasis> group. It is a default entry that AFS places on every new volume's root | |
3918 | directory.</para> | |
3919 | ||
3920 | <para>The top-level AFS directory, typically /afs, is a special case: | |
3921 | when the client is configured to run in dynroot mode (e.g. | |
3922 | <emphasis role="bold">afsd -dynroot</emphasis>, attempts to set | |
3923 | the ACL on this directory will return <emphasis role="bold"> | |
3924 | Connection timed out</emphasis>. This is because the dynamically- | |
3925 | generated root directory is not a part of the global AFS space, | |
3926 | and cannot have an access control list set on it.</para> | |
3927 | ||
3928 | <programlisting> | |
3929 | # <emphasis role="bold">/usr/afs/bin/fs setacl /afs system:anyuser rl</emphasis> | |
3930 | </programlisting> | |
3931 | ||
3932 | <indexterm> | |
3933 | <primary>commands</primary> | |
3934 | ||
3935 | <secondary>vos create</secondary> | |
3936 | ||
3937 | <tertiary>root.cell volume</tertiary> | |
3938 | </indexterm> | |
3939 | ||
3940 | <indexterm> | |
3941 | <primary>vos commands</primary> | |
3942 | ||
3943 | <secondary>create</secondary> | |
3944 | ||
3945 | <tertiary>root.cell volume</tertiary> | |
3946 | </indexterm> | |
3947 | ||
3948 | <indexterm> | |
3949 | <primary>fs commands</primary> | |
3950 | ||
3951 | <secondary>mkmount</secondary> | |
3952 | </indexterm> | |
3953 | ||
3954 | <indexterm> | |
3955 | <primary>commands</primary> | |
3956 | ||
3957 | <secondary>fs mkmount</secondary> | |
3958 | </indexterm> | |
3959 | ||
3960 | <indexterm> | |
3961 | <primary>mount point</primary> | |
3962 | </indexterm> | |
3963 | ||
3964 | <indexterm> | |
3965 | <primary>creating</primary> | |
3966 | ||
3967 | <secondary>mount point</secondary> | |
3968 | </indexterm> | |
3969 | ||
3970 | <indexterm> | |
3971 | <primary>volume</primary> | |
3972 | ||
3973 | <secondary>mounting</secondary> | |
3974 | </indexterm> | |
3975 | </listitem> | |
3976 | ||
3977 | <listitem id="LIWQ81"> | |
3978 | <para>Issue the <emphasis role="bold">vos create</emphasis> command to create the <emphasis | |
3979 | role="bold">root.cell</emphasis> volume. Then issue the <emphasis role="bold">fs mkmount</emphasis> command to mount it as | |
3980 | a subdirectory of the <emphasis role="bold">/afs</emphasis> directory, where it serves as the root of your cell's local | |
3981 | AFS filespace. Finally, issue the <emphasis role="bold">fs setacl</emphasis> command to create an ACL entry for the | |
3982 | <emphasis role="bold">system:anyuser</emphasis> group (or <emphasis role="bold">system:authuser</emphasis> group).</para> | |
3983 | ||
3984 | <para>For the <replaceable>partition name</replaceable> argument, substitute the name of one of the machine's AFS server | |
3985 | partitions (such as <emphasis role="bold">/vicepa</emphasis>). For the <replaceable>cellname</replaceable> argument, | |
3986 | substitute your cell's fully-qualified Internet domain name (such as <emphasis role="bold">example.com</emphasis>).</para> | |
3987 | ||
3988 | <programlisting> | |
3989 | # <emphasis role="bold">/usr/afs/bin/vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <emphasis | |
3990 | role="bold">root.cell</emphasis> | |
3991 | # <emphasis role="bold">/usr/afs/bin/fs mkmount /afs/</emphasis><replaceable>cellname</replaceable> <emphasis role="bold">root.cell</emphasis> | |
3992 | # <emphasis role="bold">/usr/afs/bin/fs setacl /afs/</emphasis><replaceable>cellname</replaceable> <emphasis role="bold">system:anyuser rl</emphasis> | |
3993 | </programlisting> | |
3994 | ||
3995 | <indexterm> | |
3996 | <primary>creating</primary> | |
3997 | ||
3998 | <secondary>symbolic link</secondary> | |
3999 | ||
4000 | <tertiary>for abbreviated cell name</tertiary> | |
4001 | </indexterm> | |
4002 | ||
4003 | <indexterm> | |
4004 | <primary>symbolic link</primary> | |
4005 | ||
4006 | <secondary>for abbreviated cell name</secondary> | |
4007 | </indexterm> | |
4008 | ||
4009 | <indexterm> | |
4010 | <primary>cell name</primary> | |
4011 | ||
4012 | <secondary>symbolic link for abbreviated</secondary> | |
4013 | </indexterm> | |
4014 | </listitem> | |
4015 | ||
4016 | <listitem> | |
4017 | <para><emphasis role="bold">(Optional)</emphasis> Create a symbolic link to a shortened cell name, to reduce the length of | |
4018 | pathnames for users in the local cell. For example, in the <emphasis role="bold">example.com</emphasis> cell, <emphasis | |
4019 | role="bold">/afs/example</emphasis> is a link to <emphasis role="bold">/afs/example.com</emphasis>. <programlisting> | |
4020 | # <emphasis role="bold">cd /afs</emphasis> | |
4021 | # <emphasis role="bold">ln -s</emphasis> <replaceable>full_cellname</replaceable> <replaceable>short_cellname</replaceable> | |
4022 | </programlisting> <indexterm> | |
4023 | <primary>read/write mount point for root.afs volume</primary> | |
4024 | </indexterm> <indexterm> | |
4025 | <primary>root.afs volume</primary> | |
4026 | ||
4027 | <secondary>read/write mount point</secondary> | |
4028 | </indexterm> <indexterm> | |
4029 | <primary>creating</primary> | |
4030 | ||
4031 | <secondary>read/write mount point</secondary> | |
4032 | </indexterm></para> | |
4033 | </listitem> | |
4034 | ||
4035 | <listitem> | |
4036 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to create a read/write mount point for the <emphasis | |
4037 | role="bold">root.cell</emphasis> volume (you created a regular mount point in Step <link | |
4038 | linkend="LIWQ81">2</link>).</para> | |
4039 | ||
4040 | <para>By convention, the name of a read/write mount point begins with a period, both to distinguish it from the regular | |
4041 | mount point and to make it visible only when the <emphasis role="bold">-a</emphasis> flag is used on the <emphasis | |
4042 | role="bold">ls</emphasis> command.</para> | |
4043 | ||
4044 | <para>Change directory to <emphasis role="bold">/usr/afs/bin</emphasis> to make it easier to access the command | |
4045 | binaries.</para> | |
4046 | ||
4047 | <programlisting> | |
4048 | # <emphasis role="bold">cd /usr/afs/bin</emphasis> | |
4049 | # <emphasis role="bold">./fs mkmount /afs/.</emphasis><replaceable>cellname</replaceable> <emphasis role="bold">root.cell -rw</emphasis> | |
4050 | </programlisting> | |
4051 | ||
4052 | <indexterm> | |
4053 | <primary>commands</primary> | |
4054 | ||
4055 | <secondary>vos addsite</secondary> | |
4056 | </indexterm> | |
4057 | ||
4058 | <indexterm> | |
4059 | <primary>vos commands</primary> | |
4060 | ||
4061 | <secondary>addsite</secondary> | |
4062 | </indexterm> | |
4063 | ||
4064 | <indexterm> | |
4065 | <primary>volume</primary> | |
4066 | ||
4067 | <secondary>defining replication site</secondary> | |
4068 | </indexterm> | |
4069 | ||
4070 | <indexterm> | |
4071 | <primary>defining</primary> | |
4072 | ||
4073 | <secondary>replication site for volume</secondary> | |
4074 | </indexterm> | |
4075 | </listitem> | |
4076 | ||
4077 | <listitem id="LIWQ82"> | |
4078 | <para>Issue the <emphasis role="bold">vos addsite</emphasis> command to define a replication site | |
4079 | for both the <emphasis role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes. In each | |
4080 | case, substitute for the <replaceable>partition name</replaceable> argument the partition where the volume's read/write | |
4081 | version resides. When you install additional file server machines, it is a good idea to create replication sites on them | |
4082 | as well. <programlisting> | |
4083 | # <emphasis role="bold">./vos addsite</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <emphasis | |
4084 | role="bold">root.afs</emphasis> | |
4085 | # <emphasis role="bold">./vos addsite</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <emphasis | |
4086 | role="bold">root.cell</emphasis> | |
4087 | </programlisting> <indexterm> | |
4088 | <primary>fs commands</primary> | |
4089 | ||
4090 | <secondary>examine</secondary> | |
4091 | </indexterm> <indexterm> | |
4092 | <primary>commands</primary> | |
4093 | ||
4094 | <secondary>fs examine</secondary> | |
4095 | </indexterm></para> | |
4096 | </listitem> | |
4097 | ||
4098 | <listitem> | |
4099 | <para>Issue the <emphasis role="bold">fs examine</emphasis> command to verify that the Cache Manager can access both the | |
4100 | <emphasis role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes, before you attempt to | |
4101 | replicate them. The output lists each volume's name, volumeID number, quota, size, and the size of the partition that | |
4102 | houses them. If you get an error message instead, do not continue before taking corrective action. <programlisting> | |
4103 | # <emphasis role="bold">./fs examine /afs</emphasis> | |
4104 | # <emphasis role="bold">./fs examine /afs/</emphasis><replaceable>cellname</replaceable> | |
4105 | </programlisting> <indexterm> | |
4106 | <primary>commands</primary> | |
4107 | ||
4108 | <secondary>vos release</secondary> | |
4109 | </indexterm> <indexterm> | |
4110 | <primary>vos commands</primary> | |
4111 | ||
4112 | <secondary>release</secondary> | |
4113 | </indexterm> <indexterm> | |
4114 | <primary>volume</primary> | |
4115 | ||
4116 | <secondary>releasing replicated</secondary> | |
4117 | </indexterm> <indexterm> | |
4118 | <primary>releasing replicated volume</primary> | |
4119 | </indexterm></para> | |
4120 | </listitem> | |
4121 | ||
4122 | <listitem> | |
4123 | <para>Issue the <emphasis role="bold">vos release</emphasis> command to release a replica of the <emphasis | |
4124 | role="bold">root.afs</emphasis> and <emphasis role="bold">root.cell</emphasis> volumes to the sites you defined in Step | |
4125 | <link linkend="LIWQ82">5</link>. <programlisting> | |
4126 | # <emphasis role="bold">./vos release root.afs</emphasis> | |
4127 | # <emphasis role="bold">./vos release root.cell</emphasis> | |
4128 | </programlisting> <indexterm> | |
4129 | <primary>fs commands</primary> | |
4130 | ||
4131 | <secondary>checkvolumes</secondary> | |
4132 | </indexterm> <indexterm> | |
4133 | <primary>commands</primary> | |
4134 | ||
4135 | <secondary>fs checkvolumes</secondary> | |
4136 | </indexterm></para> | |
4137 | </listitem> | |
4138 | ||
4139 | <listitem> | |
4140 | <para>Issue the <emphasis role="bold">fs checkvolumes</emphasis> to force the Cache Manager to notice that you have | |
4141 | released read-only versions of the volumes, then issue the <emphasis role="bold">fs examine</emphasis> command again. This | |
4142 | time its output mentions the read-only version of the volumes (<emphasis role="bold">root.afs.readonly</emphasis> and | |
4143 | <emphasis role="bold">root.cell.readonly</emphasis>) instead of the read/write versions, because of the Cache Manager's | |
4144 | bias to access the read-only version of the <emphasis role="bold">root.afs</emphasis> volume if it exists. | |
4145 | <programlisting> | |
4146 | # <emphasis role="bold">./fs checkvolumes</emphasis> | |
4147 | # <emphasis role="bold">./fs examine /afs</emphasis> | |
4148 | # <emphasis role="bold">./fs examine /afs/</emphasis><replaceable>cellname</replaceable> | |
4149 | </programlisting></para> | |
4150 | </listitem> | |
4151 | </orderedlist></para> | |
4152 | ||
4153 | <indexterm> | |
4154 | <primary>storing</primary> | |
4155 | ||
4156 | <secondary>AFS binaries in volumes</secondary> | |
4157 | </indexterm> | |
4158 | ||
4159 | <indexterm> | |
4160 | <primary>creating</primary> | |
4161 | ||
4162 | <secondary>volume</secondary> | |
4163 | ||
4164 | <tertiary>for AFS binaries</tertiary> | |
4165 | </indexterm> | |
4166 | ||
4167 | <indexterm> | |
4168 | <primary>volume</primary> | |
4169 | ||
4170 | <secondary>for AFS binaries</secondary> | |
4171 | </indexterm> | |
4172 | ||
4173 | <indexterm> | |
4174 | <primary>binaries</primary> | |
4175 | ||
4176 | <secondary>storing AFS in volume</secondary> | |
4177 | </indexterm> | |
4178 | ||
4179 | <indexterm> | |
4180 | <primary>usr/afsws directory</primary> | |
4181 | </indexterm> | |
4182 | ||
4183 | <indexterm> | |
4184 | <primary>directories</primary> | |
4185 | ||
4186 | <secondary>/usr/afsws</secondary> | |
4187 | </indexterm> | |
4188 | </sect1> | |
4189 | ||
4190 | <sect1 id="HDRWQ83"> | |
4191 | <title>Storing AFS Binaries in AFS</title> | |
4192 | ||
4193 | <note><para>Sites with existing binary distribution mechanisms, including | |
4194 | those which use packaging systems such as RPM, may wish to skip this step, | |
4195 | and use tools native to their operating system to manage AFS configuration | |
4196 | information.</para></note> | |
4197 | ||
4198 | <para>In the conventional configuration, you make AFS client binaries and configuration files available in the subdirectories of | |
4199 | the <emphasis role="bold">/usr/afsws</emphasis> directory on client machines (<emphasis role="bold">afsws</emphasis> is an | |
4200 | acronym for <emphasis role="bold">AFS w</emphasis><emphasis>ork</emphasis><emphasis | |
4201 | role="bold">s</emphasis><emphasis>tation</emphasis>). You can conserve local disk space by creating <emphasis | |
4202 | role="bold">/usr/afsws</emphasis> as a link to an AFS volume that houses the AFS client binaries and configuration files for | |
4203 | this system type.</para> | |
4204 | ||
4205 | <para>In this section you create the necessary volumes. The conventional location to which to link <emphasis | |
4206 | role="bold">/usr/afsws</emphasis> is <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4207 | role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis>, where | |
4208 | <replaceable>sysname</replaceable> is the appropriate system type name as specified in the <emphasis>OpenAFS Release | |
4209 | Notes</emphasis>. The instructions in <link linkend="HDRWQ133">Installing Additional Client Machines</link> assume that you have | |
4210 | followed the instructions in this section.</para> | |
4211 | ||
4212 | <para>If you have previously run AFS in the cell, the volumes possibly already exist. If so, you need to perform Step <link | |
4213 | linkend="LIWQ86">8</link> only.</para> | |
4214 | ||
4215 | <para>The current working directory is still <emphasis role="bold">/usr/afs/bin</emphasis>, which houses the <emphasis | |
4216 | role="bold">fs</emphasis> and <emphasis role="bold">vos</emphasis> command suite binaries. In the following commands, it is | |
4217 | possible you still need to specify the pathname to the commands, depending on how your PATH environment variable is set. | |
4218 | <orderedlist> | |
4219 | <indexterm> | |
4220 | <primary>commands</primary> | |
4221 | ||
4222 | <secondary>vos create</secondary> | |
4223 | ||
4224 | <tertiary>volume for AFS binaries</tertiary> | |
4225 | </indexterm> | |
4226 | ||
4227 | <indexterm> | |
4228 | <primary>vos commands</primary> | |
4229 | ||
4230 | <secondary>create</secondary> | |
4231 | ||
4232 | <tertiary>volume for AFS binaries</tertiary> | |
4233 | </indexterm> | |
4234 | ||
4235 | <listitem id="LIWQ84"> | |
4236 | <para>Issue the <emphasis role="bold">vos create</emphasis> command to create volumes for storing | |
4237 | the AFS client binaries for this system type. The following example instruction creates volumes called | |
4238 | <replaceable>sysname</replaceable>, <replaceable>sysname</replaceable>.<emphasis role="bold">usr</emphasis>, and | |
4239 | <replaceable>sysname</replaceable>.<emphasis role="bold">usr.afsws</emphasis>. Refer to the <emphasis>OpenAFS Release | |
4240 | Notes</emphasis> to learn the proper value of <replaceable>sysname</replaceable> for this system type. <programlisting> | |
4241 | # <emphasis role="bold">vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <replaceable>sysname</replaceable> | |
4242 | # <emphasis role="bold">vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <replaceable>sysname</replaceable><emphasis | |
4243 | role="bold">.usr</emphasis> | |
4244 | # <emphasis role="bold">vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <replaceable>sysname</replaceable><emphasis | |
4245 | role="bold">.usr.afsws</emphasis> | |
4246 | </programlisting></para> | |
4247 | </listitem> | |
4248 | ||
4249 | <listitem> | |
4250 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the newly created volumes. Because the | |
4251 | <emphasis role="bold">root.cell</emphasis> volume is replicated, you must precede the <emphasis>cellname</emphasis> part | |
4252 | of the pathname with a period to specify the read/write mount point, as shown. Then issue the <emphasis role="bold">vos | |
4253 | release</emphasis> command to release a new replica of the <emphasis role="bold">root.cell</emphasis> volume, and the | |
4254 | <emphasis role="bold">fs checkvolumes</emphasis> command to force the local Cache Manager to access them. <programlisting> | |
4255 | # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable> <emphasis | |
4256 | role="bold">-vol</emphasis> <replaceable>sysname</replaceable> | |
4257 | # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis | |
4258 | role="bold">/usr</emphasis> <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis | |
4259 | role="bold">.usr</emphasis> | |
4260 | # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis | |
4261 | role="bold">/usr/afsws</emphasis> <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis | |
4262 | role="bold">.usr.afsws</emphasis> | |
4263 | # <emphasis role="bold">vos release root.cell</emphasis> | |
4264 | # <emphasis role="bold">fs checkvolumes</emphasis> | |
4265 | </programlisting></para> | |
4266 | </listitem> | |
4267 | ||
4268 | <listitem> | |
4269 | <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to grant the <emphasis role="bold">l</emphasis> | |
4270 | (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) | |
4271 | permissions to the <emphasis role="bold">system:anyuser</emphasis> group on each new directory's ACL. <programlisting> | |
4272 | # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable> | |
4273 | # <emphasis role="bold">fs setacl -dir . usr usr/afsws -acl system:anyuser rl</emphasis> | |
4274 | </programlisting> <indexterm> | |
4275 | <primary>commands</primary> | |
4276 | ||
4277 | <secondary>fs setquota</secondary> | |
4278 | </indexterm> <indexterm> | |
4279 | <primary>fs commands</primary> | |
4280 | ||
4281 | <secondary>setquota</secondary> | |
4282 | </indexterm> <indexterm> | |
4283 | <primary>quota for volume</primary> | |
4284 | </indexterm> <indexterm> | |
4285 | <primary>volume</primary> | |
4286 | ||
4287 | <secondary>setting quota</secondary> | |
4288 | </indexterm> <indexterm> | |
4289 | <primary>setting</primary> | |
4290 | ||
4291 | <secondary>volume quota</secondary> | |
4292 | </indexterm></para> | |
4293 | </listitem> | |
4294 | ||
4295 | <listitem id="LIWQ85"> | |
4296 | <para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set an unlimited quota on | |
4297 | the volume mounted at the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4298 | role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory. This | |
4299 | enables you to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's | |
4300 | quota.</para> | |
4301 | ||
4302 | <para>If you wish, you can set the volume's quota to a finite value after you complete the copying operation. At that | |
4303 | point, use the <emphasis role="bold">vos examine</emphasis> command to determine how much space the volume is occupying. | |
4304 | Then issue the <emphasis role="bold">fs setquota</emphasis> command to set a quota that is slightly larger.</para> | |
4305 | ||
4306 | <programlisting> | |
4307 | # <emphasis role="bold">fs setquota /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis | |
4308 | role="bold">/usr/afsws 0</emphasis> | |
4309 | </programlisting> | |
4310 | </listitem> | |
4311 | ||
4312 | <listitem> | |
4313 | <para>Unpack the distribution tarball into the <emphasis role="bold">/tmp/afsdist</emphasis> directory, | |
4314 | if it is not already. <indexterm> | |
4315 | <primary>copying</primary> | |
4316 | ||
4317 | <secondary>AFS binaries into volume</secondary> | |
4318 | </indexterm> <indexterm> | |
4319 | <primary>CD-ROM</primary> | |
4320 | ||
4321 | <secondary>copying AFS binaries into volume</secondary> | |
4322 | </indexterm> <indexterm> | |
4323 | <primary>first AFS machine</primary> | |
4324 | ||
4325 | <secondary>copying</secondary> | |
4326 | ||
4327 | <tertiary>AFS binaries into volume</tertiary> | |
4328 | </indexterm></para> | |
4329 | </listitem> | |
4330 | ||
4331 | <listitem> | |
4332 | <para>Copy the contents of the indicated directories from the | |
4333 | distribution into the <emphasis | |
4334 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4335 | role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory. | |
4336 | <programlisting> | |
4337 | # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis | |
4338 | role="bold">/usr/afsws</emphasis> | |
4339 | # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/bin .</emphasis> | |
4340 | # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/etc .</emphasis> | |
4341 | # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/include .</emphasis> | |
4342 | # <emphasis role="bold">cp -rp /tmp/afsdist/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/lib .</emphasis> | |
4343 | </programlisting> | |
4344 | <indexterm> | |
4345 | <primary>creating</primary> | |
4346 | ||
4347 | <secondary>symbolic link</secondary> | |
4348 | ||
4349 | <tertiary>to AFS binaries</tertiary> | |
4350 | </indexterm> <indexterm> | |
4351 | <primary>symbolic link</primary> | |
4352 | ||
4353 | <secondary>to AFS binaries from local disk</secondary> | |
4354 | </indexterm></para> | |
4355 | </listitem> | |
4356 | ||
4357 | <listitem id="LIWQ86"> | |
4358 | <para>Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the | |
4359 | directory <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4360 | role="bold">/@sys/usr/afsws</emphasis>. You can specify the actual system name instead of <emphasis | |
4361 | role="bold">@sys</emphasis> if you wish, but the advantage of using <emphasis role="bold">@sys</emphasis> is that it | |
4362 | remains valid if you upgrade this machine to a different system type. <programlisting> | |
4363 | # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws /usr/afsws</emphasis> | |
4364 | </programlisting> <indexterm> | |
4365 | <primary>PATH environment variable for users</primary> | |
4366 | </indexterm> <indexterm> | |
4367 | <primary>variables</primary> | |
4368 | ||
4369 | <secondary>PATH, setting for users</secondary> | |
4370 | </indexterm></para> | |
4371 | </listitem> | |
4372 | ||
4373 | <listitem> | |
4374 | <para><emphasis role="bold">(Optional)</emphasis> To enable users to issue commands from the AFS suites (such as <emphasis | |
4375 | role="bold">fs</emphasis>) without having to specify a pathname to their binaries, include the <emphasis | |
4376 | role="bold">/usr/afsws/bin</emphasis> and <emphasis role="bold">/usr/afsws/etc</emphasis> directories in the PATH | |
4377 | environment variable you define in each user's shell initialization file (such as <emphasis | |
4378 | role="bold">.cshrc</emphasis>).</para> | |
4379 | </listitem> | |
4380 | </orderedlist></para> | |
4381 | ||
4382 | <indexterm> | |
4383 | <primary>storing</primary> | |
4384 | ||
4385 | <secondary>AFS documentation in volumes</secondary> | |
4386 | </indexterm> | |
4387 | ||
4388 | <indexterm> | |
4389 | <primary>creating</primary> | |
4390 | ||
4391 | <secondary>volume</secondary> | |
4392 | ||
4393 | <tertiary>for AFS documentation</tertiary> | |
4394 | </indexterm> | |
4395 | ||
4396 | <indexterm> | |
4397 | <primary>volume</primary> | |
4398 | ||
4399 | <secondary>for AFS documentation</secondary> | |
4400 | </indexterm> | |
4401 | ||
4402 | <indexterm> | |
4403 | <primary>documentation, creating volume for AFS</primary> | |
4404 | </indexterm> | |
4405 | ||
4406 | <indexterm> | |
4407 | <primary>usr/afsdoc directory</primary> | |
4408 | </indexterm> | |
4409 | ||
4410 | <indexterm> | |
4411 | <primary>directories</primary> | |
4412 | ||
4413 | <secondary>/usr/afsdoc</secondary> | |
4414 | </indexterm> | |
4415 | </sect1> | |
4416 | ||
4417 | <sect1 id="HDRWQ87"> | |
4418 | <title>Storing AFS Documents in AFS</title> | |
4419 | ||
4420 | <para>The AFS distribution includes the following documents: <itemizedlist> | |
4421 | <listitem> | |
4422 | <para><emphasis>OpenAFS Release Notes</emphasis></para> | |
4423 | </listitem> | |
4424 | ||
4425 | <listitem> | |
4426 | <para><emphasis>OpenAFS Quick Beginnings</emphasis></para> | |
4427 | </listitem> | |
4428 | ||
4429 | <listitem> | |
4430 | <para><emphasis>OpenAFS User Guide</emphasis></para> | |
4431 | </listitem> | |
4432 | ||
4433 | <listitem> | |
4434 | <para><emphasis>OpenAFS Administration Reference</emphasis></para> | |
4435 | </listitem> | |
4436 | ||
4437 | <listitem> | |
4438 | <para><emphasis>OpenAFS Administration Guide</emphasis></para> | |
4439 | </listitem> | |
4440 | </itemizedlist></para> | |
4441 | ||
4442 | <note><para>OpenAFS Documentation is not currently provided with all | |
4443 | distributions, but may be downloaded separately from the OpenAFS | |
4444 | website</para></note> | |
4445 | ||
4446 | <para>The OpenAFS Documentation Distribution has a directory for each | |
4447 | document format provided. The different formats are suitable for online | |
4448 | viewing, printing, or both.</para> | |
4449 | ||
4450 | <para>This section explains how to create and mount a volume to house the documents, making them available to your users. The | |
4451 | recommended mount point for the volume is <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4452 | role="bold">/afsdoc</emphasis>. If you wish, you can create a link to the mount point on each client machine's local disk, | |
4453 | called <emphasis role="bold">/usr/afsdoc</emphasis>. Alternatively, you can create a link to the mount point in each user's home | |
4454 | directory. You can also choose to permit users to access only certain documents (most probably, the <emphasis>OpenAFS User | |
4455 | Guide</emphasis>) by creating different mount points or setting different ACLs on different document directories.</para> | |
4456 | ||
4457 | <para>The current working directory is still <emphasis role="bold">/usr/afs/bin</emphasis>, which houses the <emphasis | |
4458 | role="bold">fs</emphasis> and <emphasis role="bold">vos</emphasis> command suite binaries you use to create and mount volumes. | |
4459 | In the following commands, it is possible you still need to specify the pathname to the commands, depending on how your PATH | |
4460 | environment variable is set. <orderedlist> | |
4461 | <indexterm> | |
4462 | <primary>commands</primary> | |
4463 | ||
4464 | <secondary>vos create</secondary> | |
4465 | ||
4466 | <tertiary>volume for AFS documentation</tertiary> | |
4467 | </indexterm> | |
4468 | ||
4469 | <indexterm> | |
4470 | <primary>vos commands</primary> | |
4471 | ||
4472 | <secondary>create</secondary> | |
4473 | ||
4474 | <tertiary>volume for AFS documentation</tertiary> | |
4475 | </indexterm> | |
4476 | ||
4477 | <listitem> | |
4478 | <para>Issue the <emphasis role="bold">vos create</emphasis> command to create a volume for storing the AFS documentation. | |
4479 | Include the <emphasis role="bold">-maxquota</emphasis> argument to set an unlimited quota on the volume. This enables you | |
4480 | to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's quota.</para> | |
4481 | ||
4482 | <para>If you wish, you can set the volume's quota to a finite value after you complete the copying operations. At that | |
4483 | point, use the <emphasis role="bold">vos examine</emphasis> command to determine how much space the volume is occupying. | |
4484 | Then issue the <emphasis role="bold">fs setquota</emphasis> command to set a quota that is slightly larger.</para> | |
4485 | ||
4486 | <programlisting> | |
4487 | # <emphasis role="bold">vos create</emphasis> <<replaceable>machine name</replaceable>> <<replaceable>partition name</replaceable>> <emphasis | |
4488 | role="bold">afsdoc -maxquota 0</emphasis> | |
4489 | </programlisting> | |
4490 | </listitem> | |
4491 | ||
4492 | <listitem> | |
4493 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the new volume. Because the <emphasis | |
4494 | role="bold">root.cell</emphasis> volume is replicated, you must precede the <emphasis>cellname</emphasis> with a period to | |
4495 | specify the read/write mount point, as shown. Then issue the <emphasis role="bold">vos release</emphasis> command to | |
4496 | release a new replica of the <emphasis role="bold">root.cell</emphasis> volume, and the <emphasis role="bold">fs | |
4497 | checkvolumes</emphasis> command to force the local Cache Manager to access them. <programlisting> | |
4498 | # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc</emphasis> <emphasis | |
4499 | role="bold">-vol</emphasis> <emphasis role="bold">afsdoc</emphasis> | |
4500 | # <emphasis role="bold">vos release root.cell</emphasis> | |
4501 | # <emphasis role="bold">fs checkvolumes</emphasis> | |
4502 | </programlisting></para> | |
4503 | </listitem> | |
4504 | ||
4505 | <listitem> | |
4506 | <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to grant the <emphasis role="bold">rl</emphasis> | |
4507 | permissions to the <emphasis role="bold">system:anyuser</emphasis> group on the new directory's ACL. <programlisting> | |
4508 | # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc</emphasis> | |
4509 | # <emphasis role="bold">fs setacl . system:anyuser rl</emphasis> | |
4510 | </programlisting></para> | |
4511 | </listitem> | |
4512 | ||
4513 | <listitem> | |
4514 | <para>Unpack the OpenAFS documentation distribution into the | |
4515 | <emphasis role="bold">/tmp/afsdocs</emphasis> directory. You may use | |
4516 | a different directory, in which case the location you use should be | |
4517 | subsituted in the following examples. For instructions on unpacking | |
4518 | the distribution, consult the documentation for your operating | |
4519 | system's <emphasis role="bold">tar</emphasis> command. | |
4520 | <indexterm> | |
4521 | <primary>copying</primary> | |
4522 | ||
4523 | <secondary>AFS documentation from distribution</secondary> | |
4524 | </indexterm> <indexterm> | |
4525 | <primary>OpenAFS Distribution</primary> | |
4526 | ||
4527 | <secondary>copying AFS documentation from</secondary> | |
4528 | </indexterm> <indexterm> | |
4529 | <primary>first AFS machine</primary> | |
4530 | ||
4531 | <secondary>copying</secondary> | |
4532 | ||
4533 | <tertiary>AFS documentation from OpenAFS distribution</tertiary> | |
4534 | </indexterm> <indexterm> | |
4535 | <primary>index.htm file</primary> | |
4536 | </indexterm> <indexterm> | |
4537 | <primary>files</primary> | |
4538 | ||
4539 | <secondary>index.htm</secondary> | |
4540 | </indexterm></para> | |
4541 | </listitem> | |
4542 | ||
4543 | <listitem> | |
4544 | <para>Copy the AFS documents in one or more formats from the unpacked distribution into subdirectories of the <emphasis | |
4545 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc</emphasis> directory. Repeat | |
4546 | the commands for each format. <programlisting> | |
4547 | # <emphasis role="bold">mkdir</emphasis> <replaceable>format_name</replaceable> | |
4548 | # <emphasis role="bold">cd</emphasis> <replaceable>format_name</replaceable> | |
4549 | # <emphasis role="bold">cp -rp /tmp/afsdocs/</emphasis><replaceable>format</replaceable> <emphasis role="bold">.</emphasis> | |
4550 | </programlisting></para> | |
4551 | ||
4552 | <para>If you choose to store the HTML version of the documents in AFS, note that in addition to a subdirectory for each | |
4553 | document there are several files with a <emphasis role="bold">.gif</emphasis> extension, which enable readers to move | |
4554 | easily between sections of a document. The file called <emphasis role="bold">index.htm</emphasis> is an introductory HTML | |
4555 | page that contains a hyperlink to each of the documents. For online viewing to work properly, these files must remain in | |
4556 | the top-level HTML directory (the one named, for example, <emphasis | |
4557 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/html</emphasis>).</para> | |
4558 | </listitem> | |
4559 | ||
4560 | <listitem> | |
4561 | <para><emphasis role="bold">(Optional)</emphasis> If you believe it is helpful to your users to access the AFS documents | |
4562 | in a certain format via a local disk directory, create <emphasis role="bold">/usr/afsdoc</emphasis> on the local disk as a | |
4563 | symbolic link to the documentation directory in AFS (<emphasis | |
4564 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4565 | role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable>). <programlisting> | |
4566 | # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> <emphasis | |
4567 | role="bold">/usr/afsdoc</emphasis> | |
4568 | </programlisting></para> | |
4569 | ||
4570 | <para>An alternative is to create a link in each user's home directory to the <emphasis | |
4571 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4572 | role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> directory.</para> | |
4573 | </listitem> | |
4574 | </orderedlist></para> | |
4575 | ||
4576 | <indexterm> | |
4577 | <primary>storing</primary> | |
4578 | ||
4579 | <secondary>system binaries in volumes</secondary> | |
4580 | </indexterm> | |
4581 | ||
4582 | <indexterm> | |
4583 | <primary>creating</primary> | |
4584 | ||
4585 | <secondary>volume</secondary> | |
4586 | ||
4587 | <tertiary>for system binaries</tertiary> | |
4588 | </indexterm> | |
4589 | ||
4590 | <indexterm> | |
4591 | <primary>volume</primary> | |
4592 | ||
4593 | <secondary>for system binaries</secondary> | |
4594 | </indexterm> | |
4595 | ||
4596 | <indexterm> | |
4597 | <primary>binaries</primary> | |
4598 | ||
4599 | <secondary>storing system in volumes</secondary> | |
4600 | </indexterm> | |
4601 | </sect1> | |
4602 | ||
4603 | <sect1 id="HDRWQ88"> | |
4604 | <title>Storing System Binaries in AFS</title> | |
4605 | ||
4606 | <para>You can also choose to store other system binaries in AFS volumes, such as the standard UNIX programs conventionally | |
4607 | located in local disk directories such as <emphasis role="bold">/etc</emphasis>, <emphasis role="bold">/bin</emphasis>, and | |
4608 | <emphasis role="bold">/lib</emphasis>. Storing such binaries in an AFS volume not only frees local disk space, but makes it | |
4609 | easier to update binaries on all client machines.</para> | |
4610 | ||
4611 | <para>The following is a suggested scheme for storing system binaries in AFS. It does not include instructions, but you can use | |
4612 | the instructions in <link linkend="HDRWQ83">Storing AFS Binaries in AFS</link> (which are for AFS-specific binaries) as a | |
4613 | template.</para> | |
4614 | ||
4615 | <para>Some files must remain on the local disk for use when AFS is inaccessible (during bootup and file server or network | |
4616 | outages). The required binaries include the following: <itemizedlist> | |
4617 | <listitem> | |
4618 | <para>A text editor, network commands, and so on</para> | |
4619 | </listitem> | |
4620 | ||
4621 | <listitem> | |
4622 | <para>Files used during the boot sequence before the <emphasis role="bold">afsd</emphasis> program runs, such as | |
4623 | initialization and configuration files, and binaries for commands that mount file systems</para> | |
4624 | </listitem> | |
4625 | ||
4626 | <listitem> | |
4627 | <para>Files used by dynamic kernel loader programs</para> | |
4628 | </listitem> | |
4629 | </itemizedlist></para> | |
4630 | ||
4631 | <para>In most cases, it is more secure to enable only locally authenticated users to access system binaries, by granting the | |
4632 | <emphasis role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis | |
4633 | role="bold">read</emphasis>) permissions to the <emphasis role="bold">system:authuser</emphasis> group on the ACLs of | |
4634 | directories that contain the binaries. If users need to access a binary while unauthenticated, however, the ACL on its directory | |
4635 | must grant those permissions to the <emphasis role="bold">system:anyuser</emphasis> group.</para> | |
4636 | ||
4637 | <para>The following chart summarizes the suggested volume and mount point names for storing system binaries. It uses a separate | |
4638 | volume for each directory. You already created a volume called <replaceable>sysname</replaceable> for this machine's system type | |
4639 | when you followed the instructions in <link linkend="HDRWQ83">Storing AFS Binaries in AFS</link>.</para> | |
4640 | ||
4641 | <para>You can name volumes in any way you wish, and mount them at other locations than those suggested here. However, this | |
4642 | scheme has several advantages: <itemizedlist> | |
4643 | <listitem> | |
4644 | <para>Volume names clearly identify volume contents</para> | |
4645 | </listitem> | |
4646 | ||
4647 | <listitem> | |
4648 | <para>Using the <replaceable>sysname</replaceable> prefix on every volume makes it is easy to back up all of the volumes | |
4649 | together, because the AFS Backup System enables you to define sets of volumes based on a string included in all of their | |
4650 | names</para> | |
4651 | </listitem> | |
4652 | ||
4653 | <listitem> | |
4654 | <para>It makes it easy to track related volumes, keeping them together on the same file server machine if desired</para> | |
4655 | </listitem> | |
4656 | ||
4657 | <listitem> | |
4658 | <para>There is a clear relationship between volume name and mount point name</para> | |
4659 | </listitem> | |
4660 | </itemizedlist></para> | |
4661 | ||
4662 | <informaltable frame="none"> | |
4663 | <tgroup cols="2"> | |
4664 | <colspec colwidth="50*" /> | |
4665 | ||
4666 | <colspec colwidth="50*" /> | |
4667 | ||
4668 | <thead> | |
4669 | <row> | |
4670 | <entry><emphasis role="bold">Volume Name</emphasis></entry> | |
4671 | ||
4672 | <entry><emphasis role="bold">Mount Point</emphasis></entry> | |
4673 | </row> | |
4674 | </thead> | |
4675 | ||
4676 | <tbody> | |
4677 | <row> | |
4678 | <entry><replaceable>sysname</replaceable></entry> | |
4679 | ||
4680 | <entry><emphasis | |
4681 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable></entry> | |
4682 | </row> | |
4683 | ||
4684 | <row> | |
4685 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">bin</emphasis></entry> | |
4686 | ||
4687 | <entry><emphasis | |
4688 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4689 | role="bold">/bin</emphasis></entry> | |
4690 | </row> | |
4691 | ||
4692 | <row> | |
4693 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">etc</emphasis></entry> | |
4694 | ||
4695 | <entry><emphasis | |
4696 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4697 | role="bold">/etc</emphasis></entry> | |
4698 | </row> | |
4699 | ||
4700 | <row> | |
4701 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr</emphasis></entry> | |
4702 | ||
4703 | <entry><emphasis | |
4704 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4705 | role="bold">/usr</emphasis></entry> | |
4706 | </row> | |
4707 | ||
4708 | <row> | |
4709 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.afsws</emphasis></entry> | |
4710 | ||
4711 | <entry><emphasis | |
4712 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4713 | role="bold">/usr/afsws</emphasis></entry> | |
4714 | </row> | |
4715 | ||
4716 | <row> | |
4717 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.bin</emphasis></entry> | |
4718 | ||
4719 | <entry><emphasis | |
4720 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4721 | role="bold">/usr/bin</emphasis></entry> | |
4722 | </row> | |
4723 | ||
4724 | <row> | |
4725 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.etc</emphasis></entry> | |
4726 | ||
4727 | <entry><emphasis | |
4728 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4729 | role="bold">/usr/etc</emphasis></entry> | |
4730 | </row> | |
4731 | ||
4732 | <row> | |
4733 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.inc</emphasis></entry> | |
4734 | ||
4735 | <entry><emphasis | |
4736 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4737 | role="bold">/usr/include</emphasis></entry> | |
4738 | </row> | |
4739 | ||
4740 | <row> | |
4741 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.lib</emphasis></entry> | |
4742 | ||
4743 | <entry><emphasis | |
4744 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4745 | role="bold">/usr/lib</emphasis></entry> | |
4746 | </row> | |
4747 | ||
4748 | <row> | |
4749 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.loc</emphasis></entry> | |
4750 | ||
4751 | <entry><emphasis | |
4752 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4753 | role="bold">/usr/local</emphasis></entry> | |
4754 | </row> | |
4755 | ||
4756 | <row> | |
4757 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.man</emphasis></entry> | |
4758 | ||
4759 | <entry><emphasis | |
4760 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4761 | role="bold">/usr/man</emphasis></entry> | |
4762 | </row> | |
4763 | ||
4764 | <row> | |
4765 | <entry><replaceable>sysname</replaceable>.<emphasis role="bold">usr.sys</emphasis></entry> | |
4766 | ||
4767 | <entry><emphasis | |
4768 | role="bold">/afs/</emphasis><replaceable>cellname</replaceable>/<replaceable>sysname</replaceable><emphasis | |
4769 | role="bold">/usr/sys</emphasis></entry> | |
4770 | </row> | |
4771 | </tbody> | |
4772 | </tgroup> | |
4773 | </informaltable> | |
4774 | ||
4775 | <indexterm> | |
4776 | <primary>foreign cell, enabling access</primary> | |
4777 | </indexterm> | |
4778 | ||
4779 | <indexterm> | |
4780 | <primary>cell</primary> | |
4781 | ||
4782 | <secondary>enabling access to foreign</secondary> | |
4783 | </indexterm> | |
4784 | ||
4785 | <indexterm> | |
4786 | <primary>access</primary> | |
4787 | ||
4788 | <secondary>to local and foreign cells</secondary> | |
4789 | </indexterm> | |
4790 | ||
4791 | <indexterm> | |
4792 | <primary>AFS filespace</primary> | |
4793 | ||
4794 | <secondary>enabling access to foreign cells</secondary> | |
4795 | </indexterm> | |
4796 | ||
4797 | <indexterm> | |
4798 | <primary>root.cell volume</primary> | |
4799 | ||
4800 | <secondary>mounting for foreign cells in local filespace</secondary> | |
4801 | </indexterm> | |
4802 | ||
4803 | <indexterm> | |
4804 | <primary>database server machine</primary> | |
4805 | ||
4806 | <secondary>entry in client CellServDB file</secondary> | |
4807 | ||
4808 | <tertiary>for foreign cell</tertiary> | |
4809 | </indexterm> | |
4810 | ||
4811 | <indexterm> | |
4812 | <primary>CellServDB file (client)</primary> | |
4813 | ||
4814 | <secondary>adding entry</secondary> | |
4815 | ||
4816 | <tertiary>for foreign cell</tertiary> | |
4817 | </indexterm> | |
4818 | </sect1> | |
4819 | ||
4820 | <sect1 id="HDRWQ91"> | |
4821 | <title>Enabling Access to Foreign Cells</title> | |
4822 | ||
4823 | <para>With current OpenAFS releases, there exist a number of mechanisms for | |
4824 | providing access to foreign cells. You may add mount points in your AFS | |
4825 | filespace for each foreign cell you wish users to access, or you can | |
4826 | enable a 'synthetic' AFS root, which contains mountpoints for either all | |
4827 | AFS cells defined in the client machine's local | |
4828 | <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis>, or for all cells | |
4829 | providing location information in the DNS. | |
4830 | </para> | |
4831 | ||
4832 | <sect2> | |
4833 | <title>Enabling a Synthetic AFS root</title> | |
4834 | ||
4835 | <para>When a synthetic root is enabled, the client cache machine creates its | |
4836 | own root.afs volume, rather than using the one provided with your cell. This | |
4837 | allows clients to access all cells in the | |
4838 | <emphasis role="bold">CellServDB</emphasis> file and, optionally, all cells | |
4839 | registered in the DNS, without requiring system administrator action to | |
4840 | enable this access. Using a synthetic root has the additional advantage that | |
4841 | it allows a client to start its AFS service without a network available, as | |
4842 | it is no longer necessary to contact a fileserver to obtain the root volume. | |
4843 | </para> | |
4844 | ||
4845 | <para>OpenAFS supports two complimentary mechanisms for creating the | |
4846 | synthetic root. Starting the cache manager with the | |
4847 | <emphasis role="bold">-dynroot</emphasis> option adds all cells listed | |
4848 | in <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> to the client's | |
4849 | AFS root. Adding the <emphasis role="bold">-afsdb</emphasis> option in | |
4850 | addition to this enables DNS lookups for any cells that are not found in | |
4851 | the client's CellServDB file. Both of these options are added to the AFS | |
4852 | initialisation script, or options file, as detailed in | |
4853 | <link linkend="HDRWQ70">Configuring the Cache Manager</link>.</para> | |
4854 | </sect2> | |
4855 | <sect2> | |
4856 | <title>Adding foreign cells to a conventional root volume</title> | |
4857 | ||
4858 | <para>In this section you create a mount point in your AFS filespace for the <emphasis role="bold">root.cell</emphasis> volume | |
4859 | of each foreign cell that you want to enable your users to access. For users working on a client machine to access the cell, | |
4860 | there must in addition be an entry for it in the client machine's local <emphasis | |
4861 | role="bold">/usr/vice/etc/CellServDB</emphasis> file. (The instructions in <link linkend="HDRWQ66">Creating the Client | |
4862 | CellServDB File</link> suggest that you use the <emphasis role="bold">CellServDB.sample</emphasis> file included in the AFS | |
4863 | distribution as the basis for your cell's client <emphasis role="bold">CellServDB</emphasis> file. The sample file lists all of | |
4864 | the cells that had agreed to participate in the AFS global namespace at the time your AFS CD-ROM was created. As mentioned in | |
4865 | that section, the AFS Product Support group also maintains a copy of the file, updating it as necessary.)</para> | |
4866 | ||
4867 | <para>The chapter in the <emphasis>OpenAFS Administration Guide</emphasis> about cell administration and configuration issues | |
4868 | discusses the implications of participating in the global AFS namespace. The chapter about administering client machines | |
4869 | explains how to maintain knowledge of foreign cells on client machines, and includes suggestions for maintaining a central | |
4870 | version of the file in AFS. <orderedlist> | |
4871 | <listitem> | |
4872 | <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount each foreign cell's <emphasis | |
4873 | role="bold">root.cell</emphasis> volume on a directory called <emphasis | |
4874 | role="bold">/afs/</emphasis><replaceable>foreign_cell</replaceable>. Because the <emphasis role="bold">root.afs</emphasis> | |
4875 | volume is replicated, you must create a temporary mount point for its read/write version in a directory to which you have | |
4876 | write access (such as your cell's <emphasis role="bold">/afs/.</emphasis><replaceable>cellname</replaceable> directory). | |
4877 | Create the mount points, issue the <emphasis role="bold">vos release</emphasis> command to release new replicas to the | |
4878 | read-only sites for the <emphasis role="bold">root.afs</emphasis> volume, and issue the <emphasis role="bold">fs | |
4879 | checkvolumes</emphasis> command to force the local Cache Manager to access the new replica.</para> | |
4880 | ||
4881 | <note> | |
4882 | <para>You need to issue the <emphasis role="bold">fs mkmount</emphasis> command only once for each foreign cell's | |
4883 | <emphasis role="bold">root.cell</emphasis> volume. You do not need to repeat the command on each client machine.</para> | |
4884 | </note> | |
4885 | ||
4886 | <para>Substitute your cell's name for <replaceable>cellname</replaceable>.</para> | |
4887 | ||
4888 | <programlisting> | |
4889 | # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable> | |
4890 | # <emphasis role="bold">/usr/afs/bin/fs mkmount temp root.afs</emphasis> | |
4891 | </programlisting> | |
4892 | ||
4893 | <para>Repeat the <emphasis role="bold">fs mkmount</emphasis> command for each foreign cell you wish to mount at this | |
4894 | time.</para> | |
4895 | ||
4896 | <programlisting> | |
4897 | # <emphasis role="bold">/usr/afs/bin/fs mkmount temp/</emphasis><replaceable>foreign_cell</replaceable> <emphasis role="bold">root.cell -c</emphasis> <replaceable>foreign_cell</replaceable> | |
4898 | </programlisting> | |
4899 | ||
4900 | <para>Issue the following commands only once.</para> | |
4901 | ||
4902 | <programlisting> | |
4903 | # <emphasis role="bold">/usr/afs/bin/fs rmmount temp</emphasis> | |
4904 | # <emphasis role="bold">/usr/afs/bin/vos release root.afs</emphasis> | |
4905 | # <emphasis role="bold">/usr/afs/bin/fs checkvolumes</emphasis> | |
4906 | </programlisting> | |
4907 | ||
4908 | <indexterm> | |
4909 | <primary>fs commands</primary> | |
4910 | ||
4911 | <secondary>newcell</secondary> | |
4912 | </indexterm> | |
4913 | ||
4914 | <indexterm> | |
4915 | <primary>commands</primary> | |
4916 | ||
4917 | <secondary>fs newcell</secondary> | |
4918 | </indexterm> | |
4919 | </listitem> | |
4920 | ||
4921 | <listitem id="LIWQ92"> | |
4922 | <para>If this machine is going to remain an AFS client after you complete the installation, verify | |
4923 | that the local <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file includes an entry for each foreign | |
4924 | cell.</para> | |
4925 | ||
4926 | <para>For each cell that does not already have an entry, complete the following instructions: <orderedlist> | |
4927 | <listitem> | |
4928 | <para>Create an entry in the <emphasis role="bold">CellServDB</emphasis> file. Be sure to comply with the formatting | |
4929 | instructions in <link linkend="HDRWQ66">Creating the Client CellServDB File</link>.</para> | |
4930 | </listitem> | |
4931 | ||
4932 | <listitem> | |
4933 | <para>Issue the <emphasis role="bold">fs newcell</emphasis> command to add an entry for the cell directly to the | |
4934 | list that the Cache Manager maintains in kernel memory. Provide each database server machine's fully qualified | |
4935 | hostname. <programlisting> | |
4936 | # <emphasis role="bold">/usr/afs/bin/fs newcell</emphasis> <<replaceable>foreign_cell</replaceable>> <<replaceable>dbserver1></replaceable> \ | |
4937 | [<<replaceable>dbserver2></replaceable>] [<<replaceable>dbserver3></replaceable>] | |
4938 | </programlisting></para> | |
4939 | </listitem> | |
4940 | ||
4941 | <listitem> | |
4942 | <para>If you plan to maintain a central version of the <emphasis role="bold">CellServDB</emphasis> file (the | |
4943 | conventional location is <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis | |
4944 | role="bold">/common/etc/CellServDB</emphasis>), create it now as a copy of the local <emphasis | |
4945 | role="bold">/usr/vice/etc/CellServDB</emphasis> file. Verify that it includes an entry for each foreign cell you | |
4946 | want your users to be able to access. <programlisting> | |
4947 | # <emphasis role="bold">mkdir common</emphasis> | |
4948 | # <emphasis role="bold">mkdir common/etc</emphasis> | |
4949 | # <emphasis role="bold">cp /usr/vice/etc/CellServDB common/etc</emphasis> | |
4950 | # <emphasis role="bold">/usr/afs/bin/vos release root.cell</emphasis> | |
4951 | </programlisting></para> | |
4952 | </listitem> | |
4953 | </orderedlist></para> | |
4954 | </listitem> | |
4955 | ||
4956 | <listitem> | |
4957 | <para>Issue the <emphasis role="bold">ls</emphasis> command to verify that the new cell's mount point is visible in your | |
4958 | filespace. The output lists the directories at the top level of the new cell's AFS filespace. <programlisting> | |
4959 | # <emphasis role="bold">ls /afs/</emphasis><replaceable>foreign_cell</replaceable> | |
4960 | </programlisting></para> | |
4961 | </listitem> | |
4962 | ||
4963 | <listitem> | |
4964 | <para>If you wish to participate in the global AFS namespace, and only | |
4965 | intend running one database server, please | |
4966 | register your cell with grand.central.org at this time. | |
4967 | To do so, email the <emphasis role="bold">CellServDB</emphasis> fragment | |
4968 | describing your cell, together with a contact name and email address | |
4969 | for any queries, to cellservdb@grand.central.org. If you intend | |
4970 | on deploying multiple database servers, please wait until you have | |
4971 | installed all of them before registering your cell.</para> | |
4972 | </listitem> | |
4973 | <listitem> | |
4974 | <para>If you wish to allow your cell to be located through DNS lookups, | |
4975 | at this time you should also add the necessary configuration to your | |
4976 | DNS.</para> | |
4977 | ||
4978 | <para>AFS database servers may be located by creating AFSDB records | |
4979 | in the DNS for the domain name corresponding to the name of your cell. | |
4980 | It's outside the scope of this guide to give an indepth description of | |
4981 | managing, or configuring, your site's DNS. You should consult the | |
4982 | documentation for your DNS server for further details on AFSDB | |
4983 | records.</para> | |
4984 | </listitem> | |
4985 | </orderedlist></para> | |
4986 | </sect2> | |
4987 | </sect1> | |
4988 | ||
4989 | <sect1 id="HDRWQ93"> | |
4990 | <title>Improving Cell Security</title> | |
4991 | ||
4992 | <indexterm> | |
4993 | <primary>cell</primary> | |
4994 | ||
4995 | <secondary>improving security</secondary> | |
4996 | </indexterm> | |
4997 | ||
4998 | <indexterm> | |
4999 | <primary>security</primary> | |
5000 | ||
5001 | <secondary>improving</secondary> | |
5002 | </indexterm> | |
5003 | ||
5004 | <indexterm> | |
5005 | <primary>root superuser</primary> | |
5006 | ||
5007 | <secondary>controlling access</secondary> | |
5008 | </indexterm> | |
5009 | ||
5010 | <indexterm> | |
5011 | <primary>access</primary> | |
5012 | ||
5013 | <secondary>to root and admin accounts</secondary> | |
5014 | </indexterm> | |
5015 | ||
5016 | <indexterm> | |
5017 | <primary>admin account</primary> | |
5018 | ||
5019 | <secondary>controlling access to</secondary> | |
5020 | </indexterm> | |
5021 | ||
5022 | <indexterm> | |
5023 | <primary>AFS filespace</primary> | |
5024 | ||
5025 | <secondary>controlling access by root superuser</secondary> | |
5026 | </indexterm> | |
5027 | ||
5028 | <para>This section discusses ways to improve the security of AFS data | |
5029 | in your cell. Also see the chapter in the <emphasis>OpenAFS | |
5030 | Administration Guide</emphasis> about configuration and administration | |
5031 | issues.</para> | |
5032 | ||
5033 | <sect2 id="HDRWQ94"> | |
5034 | <title>Controlling root Access</title> | |
5035 | ||
5036 | <para>As on any machine, it is important to prevent unauthorized users from logging onto an AFS server or client machine as | |
5037 | the local superuser <emphasis role="bold">root</emphasis>. Take care to keep the <emphasis role="bold">root</emphasis> | |
5038 | password secret.</para> | |
5039 | ||
5040 | <para>The local <emphasis role="bold">root</emphasis> superuser does not have special access to AFS data through the Cache | |
5041 | Manager (as members of the <emphasis role="bold">system:administrators</emphasis> group do), but it does have the following | |
5042 | privileges: <itemizedlist> | |
5043 | <listitem> | |
5044 | <para>On client machines, the ability to issue commands from the <emphasis role="bold">fs</emphasis> suite that affect | |
5045 | AFS performance</para> | |
5046 | </listitem> | |
5047 | ||
5048 | <listitem> | |
5049 | <para>On server machines, the ability to disable authorization checking, or to install rogue process binaries</para> | |
5050 | </listitem> | |
5051 | </itemizedlist></para> | |
5052 | </sect2> | |
5053 | ||
5054 | <sect2 id="HDRWQ95"> | |
5055 | <title>Controlling System Administrator Access</title> | |
5056 | ||
5057 | <para>Following are suggestions for managing AFS administrative privilege: <itemizedlist> | |
5058 | <listitem> | |
5059 | <para>Create an administrative account for each administrator named | |
5060 | something like | |
5061 | <replaceable>username</replaceable><emphasis role="bold">.admin</emphasis>. | |
5062 | Administrators authenticate under these identities only when | |
5063 | performing administrative tasks, and destroy the administrative | |
5064 | tokens immediately after finishing the task (either by issuing the | |
5065 | <emphasis role="bold">unlog</emphasis> command, or the | |
5066 | <emphasis role="bold">kinit</emphasis> and | |
5067 | <emphasis role="bold">aklog</emphasis> commands to adopt their | |
5068 | regular identity).</para> | |
5069 | </listitem> | |
5070 | ||
5071 | <listitem> | |
5072 | <para>Set a short ticket lifetime for administrator accounts (for example, 20 minutes) by using the | |
5073 | facilities of your KDC. For instance, with a MIT Kerberos KDC, this | |
5074 | can be performed using the | |
5075 | <emphasis role="bold">--max-ticket-life</emphasis> argument to | |
5076 | the <emphasis role="bold">kadmin modify_principal</emphasis> | |
5077 | command. Do not however, use a short lifetime for users | |
5078 | who issue long-running <emphasis role="bold">backup</emphasis> commands.</para> | |
5079 | </listitem> | |
5080 | ||
5081 | <listitem> | |
5082 | <para>Limit the number of system administrators in your cell, especially those who belong to the <emphasis | |
5083 | role="bold">system:administrators</emphasis> group. By default they have all ACL rights on all directories in the local | |
5084 | AFS filespace, and therefore must be trusted not to examine private files.</para> | |
5085 | </listitem> | |
5086 | ||
5087 | <listitem> | |
5088 | <para>Limit the use of system administrator accounts on machines in public areas. It is especially important not to | |
5089 | leave such machines unattended without first destroying the administrative tokens.</para> | |
5090 | </listitem> | |
5091 | ||
5092 | <listitem> | |
5093 | <para>Limit the use by administrators of standard UNIX commands that make connections to remote machines (such as the | |
5094 | <emphasis role="bold">telnet</emphasis> utility). Many of these programs send passwords across the network without | |
5095 | encrypting them.</para> | |
5096 | </listitem> | |
5097 | </itemizedlist></para> | |
5098 | ||
5099 | <indexterm> | |
5100 | <primary>BOS Server</primary> | |
5101 | ||
5102 | <secondary>checking mode bits on AFS directories</secondary> | |
5103 | </indexterm> | |
5104 | ||
5105 | <indexterm> | |
5106 | <primary>mode bits on local AFS directories</primary> | |
5107 | </indexterm> | |
5108 | ||
5109 | <indexterm> | |
5110 | <primary>UNIX mode bits on local AFS directories</primary> | |
5111 | </indexterm> | |
5112 | </sect2> | |
5113 | ||
5114 | <sect2 id="HDRWQ96"> | |
5115 | <title>Protecting Sensitive AFS Directories</title> | |
5116 | ||
5117 | <para>Some subdirectories of the <emphasis role="bold">/usr/afs</emphasis> directory contain files crucial to cell security. | |
5118 | Unauthorized users must not read or write to these files because of the potential for misuse of the information they | |
5119 | contain.</para> | |
5120 | ||
5121 | <para>As the BOS Server initializes for the first time on a server machine, it creates several files and directories (as | |
5122 | mentioned in <link linkend="HDRWQ50">Starting the BOS Server</link>). It sets their owner to the local superuser <emphasis | |
5123 | role="bold">root</emphasis> and sets their mode bits to enable writing by the owner only; in some cases, it also restricts | |
5124 | reading.</para> | |
5125 | ||
5126 | <para>At each subsequent restart, the BOS Server checks that the owner and mode bits on these files are still set | |
5127 | appropriately. If they are not, it write the following message to the <emphasis role="bold">/usr/afs/logs/BosLog</emphasis> | |
5128 | file:</para> | |
5129 | ||
5130 | <programlisting> | |
5131 | Bosserver reports inappropriate access on server directories | |
5132 | </programlisting> | |
5133 | ||
5134 | <para>The BOS Server does not reset the mode bits, which enables you to set alternate values if you wish.</para> | |
5135 | ||
5136 | <para>The following charts lists the expected mode bit settings. A question mark indicates that the BOS Server does not check | |
5137 | that mode bit.</para> | |
5138 | ||
5139 | <informaltable frame="none"> | |
5140 | <tgroup cols="2"> | |
5141 | <colspec colwidth="30*" /> | |
5142 | ||
5143 | <colspec colwidth="70*" /> | |
5144 | ||
5145 | <tbody> | |
5146 | <row> | |
5147 | <entry><emphasis role="bold">/usr/afs</emphasis></entry> | |
5148 | ||
5149 | <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry> | |
5150 | </row> | |
5151 | ||
5152 | <row> | |
5153 | <entry><emphasis role="bold">/usr/afs/backup</emphasis></entry> | |
5154 | ||
5155 | <entry><computeroutput>drwx</computeroutput>???<computeroutput>---</computeroutput></entry> | |
5156 | </row> | |
5157 | ||
5158 | <row> | |
5159 | <entry><emphasis role="bold">/usr/afs/bin</emphasis></entry> | |
5160 | ||
5161 | <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry> | |
5162 | </row> | |
5163 | ||
5164 | <row> | |
5165 | <entry><emphasis role="bold">/usr/afs/db</emphasis></entry> | |
5166 | ||
5167 | <entry><computeroutput>drwx</computeroutput>???<computeroutput>---</computeroutput></entry> | |
5168 | </row> | |
5169 | ||
5170 | <row> | |
5171 | <entry><emphasis role="bold">/usr/afs/etc</emphasis></entry> | |
5172 | ||
5173 | <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry> | |
5174 | </row> | |
5175 | ||
5176 | <row> | |
5177 | <entry><emphasis role="bold">/usr/afs/etc/KeyFile</emphasis></entry> | |
5178 | ||
5179 | <entry><computeroutput>-rw</computeroutput>????<computeroutput>---</computeroutput></entry> | |
5180 | </row> | |
5181 | ||
5182 | <row> | |
5183 | <entry><emphasis role="bold">/usr/afs/etc/UserList</emphasis></entry> | |
5184 | ||
5185 | <entry><computeroutput>-rw</computeroutput>?????<computeroutput>--</computeroutput></entry> | |
5186 | </row> | |
5187 | ||
5188 | <row> | |
5189 | <entry><emphasis role="bold">/usr/afs/local</emphasis></entry> | |
5190 | ||
5191 | <entry><computeroutput>drwx</computeroutput>???<computeroutput>---</computeroutput></entry> | |
5192 | </row> | |
5193 | ||
5194 | <row> | |
5195 | <entry><emphasis role="bold">/usr/afs/logs</emphasis></entry> | |
5196 | ||
5197 | <entry><computeroutput>drwxr</computeroutput>?<computeroutput>xr-x</computeroutput></entry> | |
5198 | </row> | |
5199 | </tbody> | |
5200 | </tgroup> | |
5201 | </informaltable> | |
5202 | ||
5203 | <indexterm> | |
5204 | <primary>first AFS machine</primary> | |
5205 | ||
5206 | <secondary>client functionality</secondary> | |
5207 | ||
5208 | <tertiary>removing</tertiary> | |
5209 | </indexterm> | |
5210 | ||
5211 | <indexterm> | |
5212 | <primary>removing</primary> | |
5213 | ||
5214 | <secondary>client functionality from first AFS machine</secondary> | |
5215 | </indexterm> | |
5216 | </sect2> | |
5217 | </sect1> | |
5218 | ||
5219 | <sect1 id="HDRWQ98"> | |
5220 | <title>Removing Client Functionality</title> | |
5221 | ||
5222 | <para>Follow the instructions in this section only if you do not wish this machine to remain an AFS client. Removing client | |
5223 | functionality means that you cannot use this machine to access AFS files. <orderedlist> | |
5224 | <listitem> | |
5225 | <para>Remove the files from the <emphasis role="bold">/usr/vice/etc</emphasis> directory. The command does not remove the | |
5226 | directory for files used by the dynamic kernel loader program, if it exists on this system type. Those files are still | |
5227 | needed on a server-only machine. <programlisting> | |
5228 | # <emphasis role="bold">cd /usr/vice/etc</emphasis> | |
5229 | # <emphasis role="bold">rm *</emphasis> | |
5230 | # <emphasis role="bold">rm -rf C</emphasis> | |
5231 | </programlisting></para> | |
5232 | </listitem> | |
5233 | ||
5234 | <listitem> | |
5235 | <para>Create symbolic links to the <emphasis role="bold">ThisCell</emphasis> and <emphasis | |
5236 | role="bold">CellServDB</emphasis> files in the <emphasis role="bold">/usr/afs/etc</emphasis> directory. This makes it | |
5237 | possible to issue commands from the AFS command suites (such as <emphasis role="bold">bos</emphasis> and <emphasis | |
5238 | role="bold">fs</emphasis>) on this machine. <programlisting> | |
5239 | # <emphasis role="bold">ln -s /usr/afs/etc/ThisCell ThisCell</emphasis> | |
5240 | # <emphasis role="bold">ln -s /usr/afs/etc/CellServDB CellServDB</emphasis> | |
5241 | </programlisting></para> | |
5242 | </listitem> | |
5243 | ||
5244 | <listitem> | |
5245 | <para>Reboot the machine. Most system types use the <emphasis role="bold">shutdown</emphasis> command, but the appropriate | |
5246 | options vary. <programlisting> | |
5247 | # <emphasis role="bold">cd /</emphasis> | |
5248 | # <emphasis role="bold">shutdown</emphasis> <replaceable>appropriate_options</replaceable> | |
5249 | </programlisting></para> | |
5250 | </listitem> | |
5251 | </orderedlist></para> | |
5252 | </sect1> | |
5253 | </chapter> |