doc/xml/QuickStartUnix/auqbg007.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter id="HDRWQ133">
   3   <title>Installing Additional Client Machines</title>
   4
   5   <para>
   6   <indexterm>
   7     <primary>instructions</primary>
   8
   9     <secondary>client machine</secondary>
  10   </indexterm>
  11
  12   <indexterm>
  13     <primary>installing</primary>
  14
  15     <secondary>client functionality</secondary>
  16
  17     <tertiary>client machine</tertiary>
  18   </indexterm>
  19
  20   This chapter describes how to install AFS client machines after you have installed the first AFS machine. Some parts of the
  21   installation differ depending on whether or not the new client is of the same AFS system type (uses the same AFS binaries) as a
  22   previously installed client machine. <indexterm>
  23       <primary>overview</primary>
  24
  25       <secondary>installing client machine</secondary>
  26     </indexterm></para>
  27
  28   <sect1 id="Header_116">
  29     <title>Summary of Procedures</title>
  30
  31     <orderedlist>
  32       <listitem>
  33         <para>Incorporate AFS into the machine's kernel</para>
  34       </listitem>
  35
  36       <listitem>
  37         <para>Define the machine's cell membership</para>
  38       </listitem>
  39
  40       <listitem>
  41         <para>Define cache location and size</para>
  42       </listitem>
  43
  44       <listitem>
  45         <para>Create the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file, which determines which foreign cells the
  46         client can access in addition to the local cell</para>
  47       </listitem>
  48
  49       <listitem>
  50         <para>Create the <emphasis role="bold">/afs</emphasis> directory and start the Cache Manager</para>
  51       </listitem>
  52
  53       <listitem>
  54         <para>Create and mount volumes for housing AFS client binaries (necessary only for clients of a new system type)</para>
  55       </listitem>
  56
  57       <listitem>
  58         <para>Create a link from the local <emphasis role="bold">/usr/afsws</emphasis> directory to the AFS directory housing the
  59         AFS client binaries</para>
  60       </listitem>
  61
  62       <listitem>
  63         <para>Modify the machine's authentication system to enable AFS users to obtain tokens at login</para>
  64       </listitem>
  65     </orderedlist>
  66
  67     <indexterm>
  68       <primary>Binary Distribution</primary>
  69
  70       <secondary>creating /tmp/afsdist directory</secondary>
  71
  72       <tertiary>client machine</tertiary>
  73     </indexterm>
  74
  75     <indexterm>
  76       <primary>afsdist directory</primary>
  77
  78       <secondary>client machine</secondary>
  79     </indexterm>
  80
  81     <indexterm>
  82       <primary>client machine</primary>
  83
  84       <secondary>/tmp/afsdist directory</secondary>
  85     </indexterm>
  86
  87     <indexterm>
  88       <primary>creating</primary>
  89
  90       <secondary>/tmp/afsdist directory</secondary>
  91
  92       <tertiary>client machine</tertiary>
  93     </indexterm>
  94
  95     <indexterm>
  96       <primary>usr/vice/etc directory</primary>
  97
  98       <secondary>client machine</secondary>
  99     </indexterm>
 100
 101     <indexterm>
 102       <primary>client machine</primary>
 103
 104       <secondary>/usr/vice/etc directory</secondary>
 105     </indexterm>
 106
 107     <indexterm>
 108       <primary>creating</primary>
 109
 110       <secondary>/usr/vice/etc directory</secondary>
 111
 112       <tertiary>client machine</tertiary>
 113     </indexterm>
 114   </sect1>
 115
 116   <sect1 id="HDRWQ134">
 117     <title>Creating AFS Directories on the Local Disk</title>
 118
 119     <para>If you are not installing from a packaged distribution, create the <emphasis role="bold">/usr/vice/etc</emphasis> directory on the local disk, to house client binaries and
 120     configuration files. Subsequent instructions copy files from the OpenAFS binary distribution into them. Create the <emphasis
 121     role="bold">/tmp/afsdist</emphasis> directory as a location to uncompress this distribution, if it does not already exist.</para>
 122
 123     <programlisting>
 124    # <emphasis role="bold">mkdir /usr/vice</emphasis>
 125    # <emphasis role="bold">mkdir /usr/vice/etc</emphasis>
 126    # <emphasis role="bold">mkdir /tmp/afsdist</emphasis>
 127 </programlisting>
 128   </sect1>
 129
 130   <sect1 id="HDRWQ135">
 131     <title>Performing Platform-Specific Procedures</title>
 132
 133     <para>Every AFS client machine's kernel must incorporate AFS modifications. Some system types use a dynamic kernel loader
 134     program, whereas on other system types you build AFS modifications into a static kernel. Some system types support both
 135     methods.</para>
 136
 137     <para>Also modify the machine's authentication system so that users obtain an AFS token as they log into the local file system.
 138     Using AFS is simpler and more convenient for your users if you make the modifications on all client machines. Otherwise, users
 139     must perform a two or three step login procedure (login to the local system, obtain Kerberos credentials, and then issue the <emphasis role="bold">klog</emphasis>
 140     command). For further discussion of AFS authentication, see the chapter in the <emphasis>OpenAFS Administration Guide</emphasis>
 141     about cell configuration and administration issues.</para>
 142
 143     <para>For convenience, the following sections group the two procedures by system type. Proceed to the appropriate section.
 144     <itemizedlist>
 145         <listitem>
 146           <para><link linkend="HDRWQ143">Getting Started on Linux Systems</link></para>
 147         </listitem>
 148
 149         <listitem>
 150           <para><link linkend="HDRWQ144">Getting Started on Solaris Systems</link></para>
 151         </listitem>
 152       </itemizedlist>
 153
 154       <indexterm>
 155           <primary>incorporating AFS kernel extensions</primary>
 156
 157           <secondary>client machine</secondary>
 158
 159           <tertiary>Linux</tertiary>
 160         </indexterm> <indexterm>
 161           <primary>AFS kernel extensions</primary>
 162
 163           <secondary>on client machine</secondary>
 164
 165           <tertiary>Linux</tertiary>
 166         </indexterm> <indexterm>
 167           <primary>client machine</primary>
 168
 169           <secondary>AFS kernel extensions</secondary>
 170
 171           <tertiary>on Linux</tertiary>
 172         </indexterm> <indexterm>
 173           <primary>Linux</primary>
 174
 175           <secondary>AFS kernel extensions</secondary>
 176
 177           <tertiary>on client machine</tertiary>
 178         </indexterm> <indexterm>
 179           <primary>enabling AFS login</primary>
 180
 181           <secondary>client machine</secondary>
 182
 183           <tertiary>Linux</tertiary>
 184         </indexterm> <indexterm>
 185           <primary>AFS login</primary>
 186
 187           <secondary>on client machine</secondary>
 188
 189           <tertiary>Linux</tertiary>
 190         </indexterm> <indexterm>
 191           <primary>client machine</primary>
 192
 193           <secondary>AFS login</secondary>
 194
 195           <tertiary>on Linux</tertiary>
 196         </indexterm> <indexterm>
 197           <primary>Linux</primary>
 198
 199           <secondary>AFS login</secondary>
 200
 201           <tertiary>on client machine</tertiary>
 202         </indexterm> <indexterm>
 203           <primary>PAM</primary>
 204
 205           <secondary>on Linux</secondary>
 206
 207           <tertiary>client machine</tertiary>
 208         </indexterm>
 209       </para>
 210   </sect1>
 211
 212   <sect1 id="HDRWQ143">
 213     <title>Getting Started on Linux Systems</title>
 214
 215     <para>In this section you load AFS into the Linux kernel. Then incorporate AFS modifications into the machine's Pluggable
 216     Authentication Module (PAM) system, if you wish to enable AFS login.</para>
 217
 218     <sect2 id="Header_133">
 219       <title>Loading AFS into the Linux Kernel</title>
 220
 221       <para>The <emphasis role="bold">modprobe</emphasis> program is the dynamic kernel loader for Linux. Linux does not support
 222       incorporation of AFS modifications during a kernel build.</para>
 223
 224       <para>For AFS to function correctly, the <emphasis role="bold">modprobe</emphasis> program must run each time the machine
 225       reboots, so your distributions's AFS initialization script invokes it automatically. The script also includes
 226       commands that select the appropriate AFS library file automatically. In this section you run the script.</para>
 227
 228       <para>In a later section you also verify that the script correctly initializes the Cache Manager, then activate a
 229       configuration variable, which results in the script being incorporated into the Linux startup and shutdown sequence.</para>
 230
 231       <para>The procedure for starting up OpenAFS depends upon your distribution</para>
 232       <sect3>
 233         <title>Fedora and RedHat Enterprise Linux</title>
 234         <para>OpenAFS ships RPMS for all current Fedora and RHEL releases.
 235         <orderedlist>
 236           <listitem>
 237             <para>Download and install the RPM set for your operating system.
 238             RPMs are available from the OpenAFS web site. You will need the
 239             <emphasis role="bold">openafs</emphasis>, <emphasis role="bold">openafs-server</emphasis>,
 240             <emphasis role="bold">openafs-client</emphasis> and
 241             <emphasis role="bold">openafs-krb5</emphasis> packages, along
 242             with an <emphasis role="bold">kmod-openafs</emphasis> package
 243             matching your current, running ,kernel.</para>
 244
 245             <para>You can find the version of your current kernel by running
 246 <programlisting>
 247   # uname -r
 248 <replaceable>2.6.20-1.2933.fc6</replaceable>
 249 </programlisting></para>
 250
 251             <para>Once downloaded, the packages may be installed with the
 252             <emphasis role="bold">rpm</emphasis> command
 253 <programlisting>
 254   # rpm -U openafs-* openafs-client-* openafs-server-* openafs-krb5-* kmod-openafs-*
 255 </programlisting></para>
 256           </listitem>
 257         </orderedlist>
 258       </para>
 259       </sect3>
 260       <sect3>
 261         <title>Systems packaged as tar files</title>
 262         <para>If you are running a system where the OpenAFS Binary Distribution
 263         is provided as a tar file, or where you have built the system from
 264         source yourself, you need to install the relevant components by hand
 265         </para>
 266         <orderedlist>
 267           <listitem>
 268             <para>Unpack the distribution tarball. The examples below assume
 269             that you have unpacked the files into the
 270             <emphasis role="bold">/tmp/afsdist</emphasis>directory. If you
 271             pick a different location, substitute this in all of the following
 272             examples. Once you have unpacked the distribution,
 273             change directory as indicated.
 274 <programlisting>
 275   # <emphasis role="bold">cd /tmp/afsdist/linux/dest/root.client/usr/vice/etc</emphasis>
 276 </programlisting></para>
 277           </listitem>
 278
 279           <listitem>
 280             <para>Copy the AFS kernel library files to the local <emphasis role="bold">/usr/vice/etc/modload</emphasis> directory.
 281             The filenames for the libraries have the format <emphasis
 282             role="bold">libafs-</emphasis><replaceable>version</replaceable><emphasis role="bold">.o</emphasis>, where
 283             <replaceable>version</replaceable> indicates the kernel build level. The string <emphasis role="bold">.mp</emphasis> in
 284             the <replaceable>version</replaceable> indicates that the file is appropriate for machines running a multiprocessor
 285             kernel. <programlisting>
 286    # <emphasis role="bold">cp -rp  modload  /usr/vice/etc</emphasis>
 287 </programlisting></para>
 288           </listitem>
 289
 290           <listitem>
 291             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
 292             role="bold">/etc/rc.d/init.d</emphasis> on Linux machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
 293             extension as you copy the script. <programlisting>
 294    # <emphasis role="bold">cp -p   afs.rc  /etc/rc.d/init.d/afs</emphasis>
 295 </programlisting></para>
 296           </listitem>
 297
 298 <!--
 299           <listitem>
 300             <para>Run the AFS initialization script to load AFS extensions into the kernel. You can ignore any error messages about
 301             the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
 302    # <emphasis role="bold">/etc/rc.d/init.d/afs  start</emphasis>
 303 </programlisting></para>
 304           </listitem>
 305 -->
 306         </orderedlist>
 307       </sect3>
 308     </sect2>
 309
 310     <sect2 id="Header_134">
 311       <title>Enabling AFS Login on Linux Systems</title>
 312
 313       <para>At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM
 314       integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
 315       authenticated access to and from the machine.</para>
 316
 317       <para>At this time, we recommend that new sites requiring AFS credentials
 318       to be gained as part of PAM authentication use Russ Alberry's
 319       pam_afs_session, rather than utilising the bundled pam_afs2 module.
 320       A typical PAM stack should authenticate the user using an external
 321       Kerberos V service, and then use the AFS PAM module to obtain AFS
 322       credentials in the <computeroutput>session</computeroutput> section</para>
 323
 324       <para>If you are at a site which still requires
 325       <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based
 326       authentication, please consult
 327       <link linkend="KAS015">Enabling kaserver based AFS Login on Linux Systems</link>
 328       for further installation instructions.</para>
 329
 330       <para>Proceed to
 331       <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
 332
 333       <indexterm>
 334         <primary>incorporating AFS kernel extensions</primary>
 335
 336         <secondary>client machine</secondary>
 337
 338         <tertiary>Solaris</tertiary>
 339       </indexterm>
 340
 341       <indexterm>
 342         <primary>AFS kernel extensions</primary>
 343
 344         <secondary>on client machine</secondary>
 345
 346         <tertiary>Solaris</tertiary>
 347       </indexterm>
 348
 349       <indexterm>
 350         <primary>client machine</primary>
 351
 352         <secondary>AFS kernel extensions</secondary>
 353
 354         <tertiary>on Solaris</tertiary>
 355       </indexterm>
 356
 357       <indexterm>
 358         <primary>Solaris</primary>
 359
 360         <secondary>AFS kernel extensions</secondary>
 361
 362         <tertiary>on client machine</tertiary>
 363       </indexterm>
 364
 365       <indexterm>
 366         <primary>enabling AFS login</primary>
 367
 368         <secondary>client machine</secondary>
 369
 370         <tertiary>Solaris</tertiary>
 371       </indexterm>
 372
 373       <indexterm>
 374         <primary>AFS login</primary>
 375
 376         <secondary>on client machine</secondary>
 377
 378         <tertiary>Solaris</tertiary>
 379       </indexterm>
 380
 381       <indexterm>
 382         <primary>client machine</primary>
 383
 384         <secondary>AFS login</secondary>
 385
 386         <tertiary>on Solaris</tertiary>
 387       </indexterm>
 388
 389       <indexterm>
 390         <primary>Solaris</primary>
 391
 392         <secondary>AFS login</secondary>
 393
 394         <tertiary>on client machine</tertiary>
 395       </indexterm>
 396
 397       <indexterm>
 398         <primary>PAM</primary>
 399
 400         <secondary>on Solaris</secondary>
 401
 402         <tertiary>client machine</tertiary>
 403       </indexterm>
 404
 405       <indexterm>
 406         <primary>Solaris</primary>
 407
 408         <secondary>file systems clean-up script</secondary>
 409
 410         <tertiary>on client machine</tertiary>
 411       </indexterm>
 412
 413       <indexterm>
 414         <primary>file systems clean-up script (Solaris)</primary>
 415
 416         <secondary>client machine</secondary>
 417       </indexterm>
 418
 419       <indexterm>
 420         <primary>scripts</primary>
 421
 422         <secondary>file systems clean-up (Solaris)</secondary>
 423
 424         <tertiary>client machine</tertiary>
 425       </indexterm>
 426     </sect2>
 427   </sect1>
 428
 429   <sect1 id="HDRWQ144">
 430     <title>Getting Started on Solaris Systems</title>
 431
 432     <para>In this section you load AFS into the Solaris kernel. Then incorporate AFS modifications into the machine's Pluggable
 433     Authentication Module (PAM) system, if you wish to enable AFS login.</para>
 434
 435     <sect2 id="Header_136">
 436       <title>Loading AFS into the Solaris Kernel</title>
 437
 438       <para>The <emphasis role="bold">modload</emphasis> program is the dynamic kernel loader provided by Sun Microsystems for
 439       Solaris systems. Solaris does not support incorporation of AFS modifications during a kernel build.</para>
 440
 441       <para>For AFS to function correctly, the <emphasis role="bold">modload</emphasis> program must run each time the machine
 442       reboots, so the AFS initialization script (included on the AFS CD-ROM) invokes it automatically. In this section you copy the
 443       appropriate AFS library file to the location where the <emphasis role="bold">modload</emphasis> program accesses it and then
 444       run the script.</para>
 445
 446       <para>In a later section you verify that the script correctly initializes the Cache Manager, then create the links that
 447       incorporate AFS into the Solaris startup and shutdown sequence. <orderedlist>
 448           <listitem>
 449             <para>Unpack the OpenAFS Solaris distribution tarball. The examples
 450             below assume that you have unpacked the files into the
 451             <emphasis role="bold">/tmp/afsdist</emphasis> directory. If you
 452             pick a diferent location, substitute this in all of the following
 453             exmaples. Once you have unpacked the distribution, change directory
 454             as indicated.
 455 <programlisting>
 456    # <emphasis role="bold">cd  /tmp/afsdist/sun4x_56/dest/root.client/usr/vice/etc</emphasis>
 457 </programlisting></para>
 458           </listitem>
 459
 460           <listitem>
 461             <para>Copy the AFS initialization script to the local directory for initialization files (by convention, <emphasis
 462             role="bold">/etc/init.d</emphasis> on Solaris machines). Note the removal of the <emphasis role="bold">.rc</emphasis>
 463             extension as you copy the script. <programlisting>
 464    # <emphasis role="bold">cp -p  afs.rc  /etc/init.d/afs</emphasis>
 465 </programlisting></para>
 466           </listitem>
 467
 468           <listitem>
 469             <para>Copy the appropriate AFS kernel library file to the local file <emphasis
 470             role="bold">/kernel/fs/afs</emphasis>.</para>
 471
 472             <para>If the machine is running Solaris 11 on the x86_64 platform:</para>
 473
 474             <programlisting>
 475    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/drv/amd64/afs</emphasis>
 476 </programlisting>
 477
 478             <para>If the machine is running Solaris 10 on the x86_64 platform:</para>
 479
 480             <programlisting>
 481    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/amd64/afs</emphasis>
 482 </programlisting>
 483
 484             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, its kernel supports NFS server
 485             functionality, and the <emphasis role="bold">nfsd</emphasis> process is running:</para>
 486
 487             <programlisting>
 488    # <emphasis role="bold">cp -p modload/libafs.o /kernel/fs/afs</emphasis>
 489 </programlisting>
 490
 491             <para>If the machine is running Solaris 2.6 or the 32-bit version of Solaris 7, and its kernel does not support NFS
 492             server functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
 493
 494             <programlisting>
 495    # <emphasis role="bold">cp -p modload/libafs.nonfs.o /kernel/fs/afs</emphasis>
 496 </programlisting>
 497
 498             <para>If the machine is running the 64-bit version of Solaris 7, its kernel supports NFS server functionality, and the
 499             <emphasis role="bold">nfsd</emphasis> process is running:</para>
 500
 501             <programlisting>
 502    # <emphasis role="bold">cp -p modload/libafs64.o /kernel/fs/sparcv9/afs</emphasis>
 503 </programlisting>
 504
 505             <para>If the machine is running the 64-bit version of Solaris 7, and its kernel does not support NFS server
 506             functionality or the <emphasis role="bold">nfsd</emphasis> process is not running:</para>
 507
 508             <programlisting>
 509    # <emphasis role="bold">cp -p modload/libafs64.nonfs.o /kernel/fs/sparcv9/afs</emphasis>
 510 </programlisting>
 511           </listitem>
 512
 513           <listitem>
 514             <para>Run the AFS initialization script to load AFS modifications into the kernel. You can ignore any error messages
 515             about the inability to start the BOS Server or the Cache Manager or AFS client. <programlisting>
 516    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
 517 </programlisting></para>
 518
 519             <para>When an entry called <computeroutput>afs</computeroutput> does not already exist in the local <emphasis
 520             role="bold">/etc/name_to_sysnum</emphasis> file, the script automatically creates it and reboots the machine to start
 521             using the new version of the file. If this happens, log in again as the superuser <emphasis role="bold">root</emphasis>
 522             after the reboot and run the initialization script again. This time the required entry exists in the <emphasis
 523             role="bold">/etc/name_to_sysnum</emphasis> file, and the <emphasis role="bold">modload</emphasis> program runs.</para>
 524
 525             <programlisting>
 526    login: <emphasis role="bold">root</emphasis>
 527    Password: <replaceable>root_password</replaceable>
 528    # <emphasis role="bold">/etc/init.d/afs start</emphasis>
 529 </programlisting>
 530           </listitem>
 531         </orderedlist></para>
 532     </sect2>
 533
 534     <sect2 id="Header_137">
 535       <title>Enabling AFS Login on Solaris Systems</title>
 536
 537       <para>At this point you incorporate AFS into the operating system's Pluggable Authentication Module (PAM) scheme. PAM
 538       integrates all authentication mechanisms on the machine, including login, to provide the security infrastructure for
 539       authenticated access to and from the machine.</para>
 540
 541       <para>In modern AFS installations, you should be using Kerberos v5
 542       for user login, and obtaining AFS tokens subsequent to this authentication
 543       step. OpenAFS does not currently distribute a PAM module allowing AFS
 544       tokens to be automatically gained at login. Some of these, such as
 545       pam-krb5 and pam-afs-session from http://www.eyrie.org/~eagle/software/
 546       or pam_afs2 from ftp://achilles.ctd.anl.gov/pub/DEE/pam_afs2-0.1.tar,
 547       have been tested with Solaris.</para>
 548
 549       <para>If you are at a site which still requires
 550       <emphasis role="bold">kaserver</emphasis> or external Kerberos v4 based
 551       authentication, please consult
 552       <link linkend="KAS016">Enabling kaserver based AFS Login on Solaris Systems</link>
 553       for further installation instructions.</para>
 554     </sect2>
 555     <sect2 id="Header_137a">
 556       <title>Editing the File Systems Clean-up Script on Solaris Systems</title>
 557       <para>
 558         <orderedlist>
 559           <listitem>
 560             <para>Some Solaris distributions include a script that locates
 561             and removes unneeded files from various file systems. Its
 562             conventional location is
 563             <emphasis role="bold">/usr/lib/fs/nfs/nfsfind</emphasis>. The
 564             script generally uses an argument to the
 565             <emphasis role="bold">find</emphasis> command to define which file
 566             systems to search. In this step you modify the
 567             command to exclude the <emphasis role="bold">/afs</emphasis>
 568             directory. Otherwise, the command traverses the AFS
 569             filespace of every cell that is accessible from the machine, which can take many hours. The following alterations are
 570             possibilities, but you must verify that they are appropriate for your cell.</para>
 571
 572             <para>The first possible alteration is to add the <emphasis role="bold">-local</emphasis> flag to the existing command,
 573             so that it looks like the following:</para>
 574
 575             <programlisting>
 576    find $dir -local -name .nfs\* -mtime +7 -mount -exec rm -f {} \;
 577 </programlisting>
 578
 579             <para>Another alternative is to exclude any directories whose names begin with the lowercase letter <emphasis
 580             role="bold">a</emphasis> or a non-alphabetic character.</para>
 581
 582             <programlisting>
 583    find /[A-Zb-z]*  <replaceable>remainder of existing command</replaceable>
 584 </programlisting>
 585
 586             <para>Do not use the following command, which still searches under the <emphasis role="bold">/afs</emphasis> directory,
 587             looking for a subdirectory of type <emphasis role="bold">4.2</emphasis>.</para>
 588
 589             <programlisting>
 590    find / -fstype 4.2     /* <replaceable>do not use</replaceable> */
 591 </programlisting>
 592           </listitem>
 593
 594           <listitem>
 595             <para>Proceed to <link linkend="HDRWQ145">Loading and Creating Client Files</link>.</para>
 596           </listitem>
 597         </orderedlist></para>
 598
 599       <indexterm>
 600         <primary>Binary Distribution</primary>
 601
 602         <secondary>copying client files from</secondary>
 603
 604         <tertiary>client machine</tertiary>
 605       </indexterm>
 606
 607       <indexterm>
 608         <primary>client machine</primary>
 609
 610         <secondary>copying client files to local disk</secondary>
 611       </indexterm>
 612
 613       <indexterm>
 614         <primary>copying</primary>
 615
 616         <secondary>client files to local disk</secondary>
 617
 618         <tertiary>client machine</tertiary>
 619       </indexterm>
 620
 621       <indexterm>
 622         <primary>cell name</primary>
 623
 624         <secondary>setting in client ThisCell file</secondary>
 625
 626         <tertiary>client machine</tertiary>
 627       </indexterm>
 628
 629       <indexterm>
 630         <primary>setting</primary>
 631
 632         <secondary>cell name in client ThisCell file</secondary>
 633
 634         <tertiary>client machine</tertiary>
 635       </indexterm>
 636
 637       <indexterm>
 638         <primary>client machine</primary>
 639
 640         <secondary>cell membership</secondary>
 641       </indexterm>
 642
 643       <indexterm>
 644         <primary>client machine</primary>
 645
 646         <secondary>ThisCell file</secondary>
 647       </indexterm>
 648
 649       <indexterm>
 650         <primary>ThisCell file (client)</primary>
 651
 652         <secondary>client machine</secondary>
 653       </indexterm>
 654
 655       <indexterm>
 656         <primary>CellServDB file (client)</primary>
 657
 658         <secondary>creating</secondary>
 659
 660         <tertiary>on client machine</tertiary>
 661       </indexterm>
 662
 663       <indexterm>
 664         <primary>database server machine</primary>
 665
 666         <secondary>entry in client CellServDB file</secondary>
 667
 668         <tertiary>on client machine</tertiary>
 669       </indexterm>
 670
 671       <indexterm>
 672         <primary>creating</primary>
 673
 674         <secondary>CellServDB file (client)</secondary>
 675
 676         <tertiary>client machine</tertiary>
 677       </indexterm>
 678
 679       <indexterm>
 680         <primary>client machine</primary>
 681
 682         <secondary>CellServDB file</secondary>
 683
 684         <tertiary>creating during initial installation</tertiary>
 685       </indexterm>
 686     </sect2>
 687   </sect1>
 688
 689   <sect1 id="HDRWQ145">
 690     <title>Loading and Creating Client Files</title>
 691
 692     <para>If you are using a non-packaged distribution (that is, one provided as
 693     a tarball) you should now copy files from the istribution to the
 694     <emphasis role="bold">/usr/vice/etc</emphasis> directory. On some platforms
 695     that use a dynamic loader program to incorporate AFS modifications into the
 696     kernel, you have already copied over some the files.
 697     Copying them again does no harm.</para>
 698
 699     <para>Every AFS client machine has a copy of the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on its local disk
 700     to define the machine's cell membership for the AFS client programs that run on it. Among other functions, this file determines
 701     the following: <itemizedlist>
 702         <listitem>
 703           <para>The cell in which users authenticate when they log onto the machine, assuming it is using an AFS-modified login
 704           utility</para>
 705         </listitem>
 706
 707         <listitem>
 708           <para>The cell in which users authenticate by default when they issue the <emphasis role="bold">aklog</emphasis>
 709           command</para>
 710         </listitem>
 711
 712         <listitem>
 713           <para>The cell membership of the AFS server processes that the AFS command interpreters on this machine contact by
 714           default</para>
 715         </listitem>
 716       </itemizedlist></para>
 717
 718     <para>Similarly, the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on a client machine's local disk lists the
 719     database server machines in each cell that the local Cache Manager can contact. If there is no entry in the file for a cell, or
 720     the list of database server machines is wrong, then users working on this machine cannot access the cell. The chapter in the
 721     <emphasis>OpenAFS Administration Guide</emphasis> about administering client machines explains how to maintain the file after
 722     creating it. A version of the client <emphasis role="bold">CellServDB</emphasis> file was created during the installation of
 723     your cell's first machine (in <link linkend="HDRWQ66">Creating the Client CellServDB File</link>). It is probably also
 724     appropriate for use on this machine.</para>
 725
 726     <para>Remember that the Cache Manager consults the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file only at
 727     reboot, when it copies the information into the kernel. For the Cache Manager to perform properly, the <emphasis
 728     role="bold">CellServDB</emphasis> file must be accurate at all times. Refer to the chapter in the <emphasis>OpenAFS
 729     Administration Guide</emphasis> about administering client machines for instructions on updating this file, with or without
 730     rebooting. <orderedlist>
 731         <listitem>
 732           <para>If you have not already done so, unpack the distribution
 733           tarball for this machine's system type into a suitable location on
 734           the filesystem, such as <emphasis role="bold">/tmp/afsdist</emphasis>.
 735           If you use a different location, substitue that in the examples that
 736           follow.</para>
 737         </listitem>
 738
 739         <listitem>
 740           <para>Copy files to the local <emphasis role="bold">/usr/vice/etc</emphasis> directory.</para>
 741
 742           <para>This step places a copy of the AFS initialization script (and related files, if applicable) into the <emphasis
 743           role="bold">/usr/vice/etc</emphasis> directory. In the preceding instructions for incorporating AFS into the kernel, you
 744           copied the script directly to the operating system's conventional location for initialization files. When you incorporate
 745           AFS into the machine's startup sequence in a later step, you can choose to link the two files.</para>
 746
 747           <para>On some system types that use a dynamic kernel loader program, you previously copied AFS library files into a
 748           subdirectory of the <emphasis role="bold">/usr/vice/etc</emphasis> directory. On other system types, you copied the
 749           appropriate AFS library file directly to the directory where the operating system accesses it. The following commands do
 750           not copy or recopy the AFS library files into the <emphasis role="bold">/usr/vice/etc</emphasis> directory, because on
 751           some system types the library files consume a large amount of space. If you want to copy them, add the <emphasis
 752           role="bold">-r</emphasis> flag to the first <emphasis role="bold">cp</emphasis> command and skip the second <emphasis
 753           role="bold">cp</emphasis> command.</para>
 754
 755           <programlisting>
 756    # <emphasis role="bold">cd /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
 757    # <emphasis role="bold">cp -p  *  /usr/vice/etc</emphasis>
 758    # <emphasis role="bold">cp -rp  C  /usr/vice/etc</emphasis>
 759 </programlisting>
 760         </listitem>
 761
 762         <listitem>
 763           <para>Create the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file. <programlisting>
 764    # <emphasis role="bold">echo "</emphasis><replaceable>cellname</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/ThisCell</emphasis>
 765 </programlisting></para>
 766         </listitem>
 767
 768         <listitem>
 769           <para>Create the
 770           <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file. Use a
 771           network file transfer program such as
 772           <emphasis role="bold">sftp</emphasis> or
 773           <emphasis role="bold">scp</emphasis> to copy it from one of the
 774           following sources, which are listed in decreasing order of
 775           preference: <itemizedlist>
 776               <listitem>
 777                 <para>Your cell's central <emphasis role="bold">CellServDB</emphasis> source file (the conventional location is
 778                 <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
 779                 role="bold">/common/etc/CellServDB</emphasis>)</para>
 780               </listitem>
 781
 782               <listitem>
 783                 <para>The global <emphasis role="bold">CellServDB</emphasis>
 784                 file maintained at grand.central.org</para>
 785               </listitem>
 786
 787               <listitem>
 788                 <para>An existing client machine in your cell</para>
 789               </listitem>
 790
 791               <listitem>
 792                 <para>The <emphasis role="bold">CellServDB.sample</emphasis>
 793                 file included in the
 794                 <replaceable>sysname</replaceable><emphasis role="bold">/root.client/usr/vice/etc</emphasis>
 795                 directory of each OpenAFS distribution; add an entry for the
 796                 local cell by following the instructions in
 797                 <link linkend="HDRWQ66">Creating the Client CellServDB File</link>
 798                 </para>
 799               </listitem>
 800             </itemizedlist></para>
 801         </listitem>
 802       </orderedlist></para>
 803
 804     <indexterm>
 805       <primary>client cache</primary>
 806
 807       <see>cache</see>
 808     </indexterm>
 809
 810     <indexterm>
 811       <primary>AFS cache</primary>
 812
 813       <see>cache</see>
 814     </indexterm>
 815
 816     <indexterm>
 817       <primary>disk cache</primary>
 818
 819       <see>cache</see>
 820     </indexterm>
 821
 822     <indexterm>
 823       <primary>memory cache</primary>
 824
 825       <see>cache</see>
 826     </indexterm>
 827
 828     <indexterm>
 829       <primary>cache</primary>
 830
 831       <secondary>requirements</secondary>
 832     </indexterm>
 833
 834     <indexterm>
 835       <primary>cache</primary>
 836
 837       <secondary>choosing size</secondary>
 838     </indexterm>
 839
 840     <indexterm>
 841       <primary>requirements</primary>
 842
 843       <secondary>cache</secondary>
 844     </indexterm>
 845
 846     <indexterm>
 847       <primary>usr/vice/etc/cacheinfo</primary>
 848
 849       <see>cacheinfo file</see>
 850     </indexterm>
 851
 852     <indexterm>
 853       <primary>cacheinfo file</primary>
 854     </indexterm>
 855
 856     <indexterm>
 857       <primary>files</primary>
 858
 859       <secondary>cacheinfo</secondary>
 860     </indexterm>
 861
 862     <indexterm>
 863       <primary>usr/vice/cache directory</primary>
 864     </indexterm>
 865
 866     <indexterm>
 867       <primary>directories</primary>
 868
 869       <secondary>/usr/vice/cache</secondary>
 870     </indexterm>
 871
 872     <indexterm>
 873       <primary>cache</primary>
 874
 875       <secondary>configuring</secondary>
 876
 877       <tertiary>client machine</tertiary>
 878     </indexterm>
 879
 880     <indexterm>
 881       <primary>configuring</primary>
 882
 883       <secondary>cache</secondary>
 884
 885       <tertiary>client machine</tertiary>
 886     </indexterm>
 887
 888     <indexterm>
 889       <primary>setting</primary>
 890
 891       <secondary>cache size and location</secondary>
 892
 893       <tertiary>client machine</tertiary>
 894     </indexterm>
 895
 896     <indexterm>
 897       <primary>client machine</primary>
 898
 899       <secondary>cache size and location</secondary>
 900     </indexterm>
 901   </sect1>
 902
 903   <sect1 id="HDRWQ146">
 904     <title>Configuring the Cache</title>
 905
 906     <para>The Cache Manager uses a cache on the local disk or in machine memory to store local copies of files fetched from file
 907     server machines. As the <emphasis role="bold">afsd</emphasis> program initializes the Cache Manager, it sets basic cache
 908     configuration parameters according to definitions in the local <emphasis role="bold">/usr/vice/etc/cacheinfo</emphasis> file.
 909     The file has three fields: <orderedlist>
 910         <listitem>
 911           <para>The first field names the local directory on which to mount the AFS filespace. The conventional location is the
 912           <emphasis role="bold">/afs</emphasis> directory.</para>
 913         </listitem>
 914
 915         <listitem>
 916           <para>The second field defines the local disk directory to use for the disk cache. The conventional location is the
 917           <emphasis role="bold">/usr/vice/cache</emphasis> directory, but you can specify an alternate directory if another
 918           partition has more space available. There must always be a value in this field, but the Cache Manager ignores it if the
 919           machine uses a memory cache.</para>
 920         </listitem>
 921
 922         <listitem>
 923           <para>The third field specifies the number of kilobyte (1024 byte) blocks to allocate for the cache.</para>
 924         </listitem>
 925       </orderedlist></para>
 926
 927     <para>The values you define must meet the following requirements. <itemizedlist>
 928         <listitem>
 929           <para>On a machine using a disk cache, the Cache Manager expects always to be able to use the amount of space specified in
 930           the third field. Failure to meet this requirement can cause serious problems, some of which can be repaired only by
 931           rebooting. You must prevent non-AFS processes from filling up the cache partition. The simplest way is to devote a
 932           partition to the cache exclusively.</para>
 933         </listitem>
 934
 935         <listitem>
 936           <para>The amount of space available in memory or on the partition housing the disk cache directory imposes an absolute
 937           limit on cache size.</para>
 938         </listitem>
 939
 940         <listitem>
 941           <para>The maximum supported cache size can vary in each AFS release; see the <emphasis>OpenAFS Release Notes</emphasis>
 942           for the current version.</para>
 943         </listitem>
 944
 945         <listitem>
 946           <para>For a disk cache, you cannot specify a value in the third field that exceeds 95% of the space available on the
 947           partition mounted at the directory named in the second field. If you violate this restriction, the <emphasis
 948           role="bold">afsd</emphasis> program exits without starting the Cache Manager and prints an appropriate message on the
 949           standard output stream. A value of 90% is more appropriate on most machines. Some operating systems do not
 950           automatically reserve some space to prevent the partition from filling completely; for them, a smaller value (say, 80% to
 951           85% of the space available) is more appropriate.</para>
 952         </listitem>
 953
 954         <listitem>
 955           <para>For a memory cache, you must leave enough memory for other processes and applications to run. If you try to allocate
 956           more memory than is actually available, the <emphasis role="bold">afsd</emphasis> program exits without initializing the
 957           Cache Manager and produces the following message on the standard output stream. <programlisting>
 958    afsd: memCache allocation failure at <replaceable>number</replaceable> KB
 959 </programlisting></para>
 960
 961           <para>The <replaceable>number</replaceable> value is how many kilobytes were allocated just before the failure, and so
 962           indicates the approximate amount of memory available.</para>
 963         </listitem>
 964       </itemizedlist></para>
 965
 966     <para>Within these hard limits, the factors that determine appropriate cache size include the number of users working on the
 967     machine, the size of the files with which they work, and (for a memory cache) the number of processes that run on the machine.
 968     The higher the demand from these factors, the larger the cache needs to be to maintain good performance.</para>
 969
 970     <para>Disk caches smaller than 10 MB do not generally perform well. Machines serving multiple users usually perform better with
 971     a cache of at least 60 to 70 MB. The point at which enlarging the cache further does not really improve performance depends on
 972     the factors mentioned previously and is difficult to predict.</para>
 973
 974     <para>Memory caches smaller than 1 MB are nonfunctional, and the performance of caches smaller than 5 MB is usually
 975     unsatisfactory. Suitable upper limits are similar to those for disk caches but are probably determined more by the demands on
 976     memory from other sources on the machine (number of users and processes). Machines running only a few processes possibly can use
 977     a smaller memory cache.</para>
 978
 979     <sect2 id="HDRWQ147">
 980       <title>Configuring a Disk Cache</title>
 981
 982       <note>
 983         <para>Not all file system types that an operating system supports are necessarily supported for use as the cache partition.
 984         For possible restrictions, see the <emphasis>OpenAFS Release Notes</emphasis>.</para>
 985       </note>
 986
 987       <para>To configure the disk cache, perform the following procedures: <orderedlist>
 988           <listitem>
 989             <para>Create the local directory to use for caching. The following instruction shows the conventional location,
 990             <emphasis role="bold">/usr/vice/cache</emphasis>. If you are devoting a partition exclusively to caching, as
 991             recommended, you must also configure it, make a file system on it, and mount it at the directory created in this step.
 992             <programlisting>
 993    # <emphasis role="bold">mkdir /usr/vice/cache</emphasis>
 994 </programlisting></para>
 995           </listitem>
 996
 997           <listitem>
 998             <para>Create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration parameters discussed
 999             previously. The following instruction shows the standard mount location, <emphasis role="bold">/afs</emphasis>, and the
1000             standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis>. <programlisting>
1001    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
1002 </programlisting></para>
1003
1004             <para>The following example defines the disk cache size as 50,000 KB:</para>
1005
1006             <programlisting>
1007    # <emphasis role="bold">echo "/afs:/usr/vice/cache:50000" &gt; /usr/vice/etc/cacheinfo</emphasis>
1008 </programlisting>
1009           </listitem>
1010         </orderedlist></para>
1011     </sect2>
1012
1013     <sect2 id="HDRWQ148">
1014       <title>Configuring a Memory Cache</title>
1015
1016       <para>To configure a memory cache, create the <emphasis role="bold">cacheinfo</emphasis> file to define the configuration
1017       parameters discussed previously. The following instruction shows the standard mount location, <emphasis
1018       role="bold">/afs</emphasis>, and the standard cache location, <emphasis role="bold">/usr/vice/cache</emphasis> (though the
1019       exact value of the latter is irrelevant for a memory cache).</para>
1020
1021       <programlisting>
1022    # <emphasis role="bold">echo "/afs:/usr/vice/cache:</emphasis><replaceable>#blocks</replaceable><emphasis role="bold">" &gt; /usr/vice/etc/cacheinfo</emphasis>
1023 </programlisting>
1024
1025       <para>The following example allocates 25,000 KB of memory for the cache.</para>
1026
1027       <programlisting>
1028    # <emphasis role="bold">echo "/afs:/usr/vice/cache:25000" &gt; /usr/vice/etc/cacheinfo</emphasis>
1029 </programlisting>
1030
1031       <indexterm>
1032         <primary>afs (/afs) directory</primary>
1033
1034         <secondary>creating</secondary>
1035
1036         <tertiary>client machine</tertiary>
1037       </indexterm>
1038
1039       <indexterm>
1040         <primary>afs (/afs) directory</primary>
1041
1042         <secondary>as root of AFS filespace</secondary>
1043       </indexterm>
1044
1045       <indexterm>
1046         <primary>AFS filespace</primary>
1047
1048         <secondary>root at /afs directory</secondary>
1049       </indexterm>
1050
1051       <indexterm>
1052         <primary>directories</primary>
1053
1054         <secondary>/afs</secondary>
1055       </indexterm>
1056
1057       <indexterm>
1058         <primary>afsd</primary>
1059
1060         <secondary>options file (Linux)</secondary>
1061       </indexterm>
1062
1063       <indexterm>
1064         <primary>files</primary>
1065
1066         <secondary>afsd options file (Linux)</secondary>
1067       </indexterm>
1068
1069       <indexterm>
1070         <primary>files</primary>
1071
1072         <secondary>afs</secondary>
1073
1074         <tertiary>afsd options file (Linux)</tertiary>
1075       </indexterm>
1076
1077       <indexterm>
1078         <primary>afs file</primary>
1079
1080         <secondary>afsd options file (Linux)</secondary>
1081       </indexterm>
1082
1083       <indexterm>
1084         <primary>etc/sysconfig/afs</primary>
1085
1086         <see>afs file</see>
1087       </indexterm>
1088
1089       <indexterm>
1090         <primary>Linux</primary>
1091
1092         <secondary>afsd options file</secondary>
1093       </indexterm>
1094
1095       <indexterm>
1096         <primary>client machine</primary>
1097
1098         <secondary>afsd options file (Linux)</secondary>
1099       </indexterm>
1100
1101       <indexterm>
1102         <primary>afsd</primary>
1103
1104         <secondary>command in AFS init. script</secondary>
1105       </indexterm>
1106
1107       <indexterm>
1108         <primary>commands</primary>
1109
1110         <secondary>afsd</secondary>
1111       </indexterm>
1112
1113       <indexterm>
1114         <primary>OPTIONS variable in AFS initialization file</primary>
1115       </indexterm>
1116
1117       <indexterm>
1118         <primary>files</primary>
1119
1120         <secondary>AFS initialization</secondary>
1121
1122         <see>AFS initialization script</see>
1123       </indexterm>
1124
1125       <indexterm>
1126         <primary>scripts</primary>
1127
1128         <secondary>AFS initialization</secondary>
1129
1130         <see>AFS initialization script</see>
1131       </indexterm>
1132
1133       <indexterm>
1134         <primary>AFS initialization script</primary>
1135
1136         <secondary>setting afsd parameters</secondary>
1137
1138         <tertiary>client machine</tertiary>
1139       </indexterm>
1140
1141       <indexterm>
1142         <primary>client machine</primary>
1143
1144         <secondary>afsd command parameters</secondary>
1145       </indexterm>
1146
1147       <indexterm>
1148         <primary>variables</primary>
1149
1150         <secondary>OPTIONS (in AFS initialization file)</secondary>
1151       </indexterm>
1152
1153       <indexterm>
1154         <primary>environment variables</primary>
1155
1156         <see>variables</see>
1157       </indexterm>
1158
1159       <indexterm>
1160         <primary>Cache Manager</primary>
1161
1162         <secondary>client machine</secondary>
1163       </indexterm>
1164
1165       <indexterm>
1166         <primary>configuring</primary>
1167
1168         <secondary>Cache Manager</secondary>
1169
1170         <tertiary>client machine</tertiary>
1171       </indexterm>
1172
1173       <indexterm>
1174         <primary>client machine</primary>
1175
1176         <secondary>Cache Manager</secondary>
1177       </indexterm>
1178
1179     </sect2>
1180   </sect1>
1181
1182   <sect1 id="HDRWQ149">
1183     <title>Configuring the Cache Manager</title>
1184
1185     <para>By convention, the Cache Manager mounts the AFS filespace on the local <emphasis role="bold">/afs</emphasis> directory. In
1186     this section you create that directory.</para>
1187
1188     <para>The <emphasis role="bold">afsd</emphasis> program sets several cache configuration parameters as it initializes the Cache
1189     Manager, and starts daemons that improve performance. You can use the <emphasis role="bold">afsd</emphasis> command's arguments
1190     to override the parameters' default values and to change the number of some of the daemons. Depending on the machine's cache
1191     size, its amount of RAM, and how many people work on it, you can sometimes improve Cache Manager performance by overriding the
1192     default values. For a discussion of all of the <emphasis role="bold">afsd</emphasis> command's arguments, see its reference page
1193     in the <emphasis>OpenAFS Administration Reference</emphasis>.</para>
1194
1195     <para>On platforms using the standard 'afs' initialisation script (this does
1196     not apply to Fedora or RHEL based distributions), the
1197     <emphasis role="bold">afsd</emphasis> command line in the AFS
1198     initialization script on each system type includes an
1199     <computeroutput>OPTIONS</computeroutput> variable. You can use it to set
1200     nondefault values for the command's arguments, in one
1201     of the following ways: <itemizedlist>
1202         <listitem>
1203           <para>You can create an <emphasis role="bold">afsd</emphasis> <emphasis>options file</emphasis> that sets values for
1204           arguments to the <emphasis role="bold">afsd</emphasis> command. If the file exists, its contents are automatically
1205           substituted for the <computeroutput>OPTIONS</computeroutput> variable in the AFS initialization script. The AFS
1206           distribution for some system types includes an options file; on other system types, you must create it.</para>
1207
1208           <para>You use two variables in the AFS initialization script to specify the path to the options file:
1209           <computeroutput>CONFIG</computeroutput> and <computeroutput>AFSDOPT</computeroutput>. On system types that define a
1210           conventional directory for configuration files, the <computeroutput>CONFIG</computeroutput> variable indicates it by
1211           default; otherwise, the variable indicates an appropriate location.</para>
1212
1213           <para>List the desired <emphasis role="bold">afsd</emphasis> options on a single line in the options file, separating each
1214           option with one or more spaces. The following example sets the <emphasis role="bold">-stat</emphasis> argument to 2500,
1215           the <emphasis role="bold">-daemons</emphasis> argument to 4, and the <emphasis role="bold">-volumes</emphasis> argument to
1216           100.</para>
1217
1218           <programlisting>
1219    -stat 2500 -daemons 4 -volumes 100
1220 </programlisting>
1221         </listitem>
1222
1223         <listitem>
1224           <para>On a machine that uses a disk cache, you can set the <computeroutput>OPTIONS</computeroutput> variable in the AFS
1225           initialization script to one of <computeroutput>$SMALL</computeroutput>, <computeroutput>$MEDIUM</computeroutput>, or
1226           <computeroutput>$LARGE</computeroutput>. The AFS initialization script uses one of these settings if the <emphasis
1227           role="bold">afsd</emphasis> options file named by the <computeroutput>AFSDOPT</computeroutput> variable does not exist. In
1228           the script as distributed, the <computeroutput>OPTIONS</computeroutput> variable is set to the value
1229           <computeroutput>$MEDIUM</computeroutput>.</para>
1230
1231           <note>
1232             <para>Do not set the <computeroutput>OPTIONS</computeroutput> variable to <computeroutput>$SMALL</computeroutput>,
1233             <computeroutput>$MEDIUM</computeroutput>, or <computeroutput>$LARGE</computeroutput> on a machine that uses a memory
1234             cache. The arguments it sets are appropriate only on a machine that uses a disk cache.</para>
1235           </note>
1236
1237           <para>The script (or on some system types the <emphasis role="bold">afsd</emphasis> options file named by the
1238           <computeroutput>AFSDOPT</computeroutput> variable) defines a value for each of <computeroutput>SMALL</computeroutput>,
1239           <computeroutput>MEDIUM</computeroutput>, and <computeroutput>LARGE</computeroutput> that sets <emphasis
1240           role="bold">afsd</emphasis> command arguments appropriately for client machines of different sizes: <itemizedlist>
1241               <listitem>
1242                 <para><computeroutput>SMALL</computeroutput> is suitable for a small machine that serves one or two users and has
1243                 approximately 8 MB of RAM and a 20-MB cache</para>
1244               </listitem>
1245
1246               <listitem>
1247                 <para><computeroutput>MEDIUM</computeroutput> is suitable for a medium-sized machine that serves two to six users
1248                 and has 16 MB of RAM and a 40-MB cache</para>
1249               </listitem>
1250
1251               <listitem>
1252                 <para><computeroutput>LARGE</computeroutput> is suitable for a large machine that serves five to ten users and has
1253                 32 MB of RAM and a 100-MB cache</para>
1254               </listitem>
1255             </itemizedlist></para>
1256         </listitem>
1257
1258         <listitem>
1259           <para>You can choose not to create an <emphasis role="bold">afsd</emphasis> options file and to set the
1260           <computeroutput>OPTIONS</computeroutput> variable in the initialization script to a null value rather than to the default
1261           <computeroutput>$MEDIUM</computeroutput> value. You can then either set arguments directly on the <emphasis
1262           role="bold">afsd</emphasis> command line in the script, or set no arguments (and so accept default values for all Cache
1263           Manager parameters).</para>
1264         </listitem>
1265       </itemizedlist>
1266
1267       <note>
1268         <para>If you are running on a Fedora or RHEL based system, the
1269         openafs-client initialization script behaves differently from that
1270         described above. It sources
1271         <emphasis role="bold">/etc/sysconfig/openafs</emphasis>, in which the
1272         AFSD_ARGS variable may be set to contain any, or all, of the afsd
1273         options detailed above. Note that this script does not support setting
1274         an <computeroutput>OPTIONS</computeroutput> variable, or the
1275         <computeroutput>SMALL</computeroutput>,
1276         <computeroutput>MEDIUM</computeroutput> and
1277         <computeroutput>LARGE</computeroutput> methods of defining cache size.
1278         </para>
1279       </note>
1280
1281       <orderedlist>
1282         <listitem>
1283           <para>Create the local directory on which to mount the AFS filespace, by convention <emphasis role="bold">/afs</emphasis>.
1284           If the directory already exists, verify that it is empty. <programlisting>
1285    # <emphasis role="bold">mkdir /afs</emphasis>
1286 </programlisting></para>
1287         </listitem>
1288
1289         <listitem>
1290           <para>On non-package based Linux systems, copy the <emphasis role="bold">afsd</emphasis> options file from the <emphasis
1291           role="bold">/usr/vice/etc</emphasis> directory to the <emphasis role="bold">/etc/sysconfig</emphasis> directory, removing
1292           the <emphasis role="bold">.conf</emphasis> extension as you do so. <programlisting>
1293    # <emphasis role="bold">cp /usr/vice/etc/afs.conf /etc/sysconfig/afs</emphasis>
1294 </programlisting></para>
1295         </listitem>
1296
1297         <listitem>
1298           <para>Edit the machine's AFS initialization script or <emphasis role="bold">afsd</emphasis> options file to set
1299           appropriate values for <emphasis role="bold">afsd</emphasis> command parameters. The appropriate file for each system type
1300           is as follows: <itemizedlist>
1301               <listitem>
1302                 <para>On Fedora and RHEL systems, <emphasis role="bold">/etc/sysconfig/openafs</emphasis></para>
1303               </listitem>
1304
1305               <listitem>
1306                 <para>On Linux systems, <emphasis role="bold">/etc/sysconfig/afs</emphasis> (the <emphasis
1307                 role="bold">afsd</emphasis> options file)</para>
1308               </listitem>
1309
1310               <listitem>
1311                 <para>On Solaris systems, <emphasis role="bold">/etc/init.d/afs</emphasis></para>
1312               </listitem>
1313             </itemizedlist></para>
1314
1315           <para>Use one of the methods described in the introduction to this section to add the following flags to the <emphasis
1316           role="bold">afsd</emphasis> command line. Also set any performance-related arguments you wish. <itemizedlist>
1317               <listitem>
1318                 <para>Add the <emphasis role="bold">-memcache</emphasis> flag if the machine is to use a memory cache.</para>
1319               </listitem>
1320
1321               <listitem>
1322                 <para>Add the <emphasis role="bold">-verbose</emphasis> flag to display a trace of the Cache Manager's
1323                 initialization on the standard output stream.</para>
1324               </listitem>
1325             </itemizedlist></para>
1326         </listitem>
1327       </orderedlist></para>
1328
1329     <indexterm>
1330       <primary>AFS initialization script</primary>
1331
1332       <secondary>running</secondary>
1333
1334       <tertiary>client machine</tertiary>
1335     </indexterm>
1336
1337     <indexterm>
1338       <primary>client machine</primary>
1339
1340       <secondary>AFS initialization script</secondary>
1341     </indexterm>
1342
1343     <indexterm>
1344       <primary>running AFS init. script</primary>
1345
1346       <secondary>client machine</secondary>
1347     </indexterm>
1348
1349     <indexterm>
1350       <primary>installing</primary>
1351
1352       <secondary>AFS initialization script</secondary>
1353
1354       <tertiary>client machine</tertiary>
1355     </indexterm>
1356
1357     <indexterm>
1358       <primary>AFS initialization script</primary>
1359
1360       <secondary>adding to machine startup sequence</secondary>
1361
1362       <tertiary>client machine</tertiary>
1363     </indexterm>
1364   </sect1>
1365
1366   <sect1 id="HDRWQ150">
1367     <title>Starting the Cache Manager and Installing the AFS Initialization Script</title>
1368
1369     <para>In this section you run the AFS initialization script to start the Cache Manager. If the script works correctly, perform
1370     the steps that incorporate it into the machine's startup and shutdown sequence. If there are problems during the initialization,
1371     attempt to resolve them. The AFS Product Support group can provide assistance if necessary.</para>
1372
1373     <para>On machines that use a disk cache, it can take a while for the <emphasis role="bold">afsd</emphasis> program to run the
1374     first time on a machine, because it must create all of the <emphasis role="bold">V</emphasis><replaceable>n</replaceable> files
1375     in the cache directory. Subsequent Cache Manager initializations do not take nearly as long, because the <emphasis
1376     role="bold">V</emphasis><replaceable>n</replaceable> files already exist.</para>
1377
1378     <para>On system types that use a dynamic loader program, you must reboot the machine before running the initialization script,
1379     so that it can freshly load AFS modifications into the kernel.</para>
1380
1381     <para>Proceed to the instructions for your system type:</para>
1382
1383     <itemizedlist>
1384       <listitem>
1385         <para><link linkend="HDRWQ155">Running the Script on Linux Systems</link></para>
1386       </listitem>
1387
1388       <listitem>
1389         <para><link linkend="HDRWQ156">Running the Script on Solaris Systems</link></para>
1390       </listitem>
1391     </itemizedlist>
1392
1393       <indexterm>
1394         <primary>afs file</primary>
1395
1396         <secondary>AFS initialization file</secondary>
1397       </indexterm>
1398
1399       <indexterm>
1400         <primary>files</primary>
1401
1402         <secondary>afs</secondary>
1403
1404         <tertiary>AFS initialization file</tertiary>
1405       </indexterm>
1406
1407       <indexterm>
1408         <primary>etc/rc.d/init.d/afs</primary>
1409
1410         <see>afs file</see>
1411       </indexterm>
1412
1413       <indexterm>
1414         <primary>Linux</primary>
1415
1416         <secondary>AFS initialization script</secondary>
1417
1418         <tertiary>on client machine</tertiary>
1419       </indexterm>
1420
1421     <sect2>
1422       <title>Running the Script on Fedora / RHEL Systems</title>
1423
1424       <orderedlist>
1425         <listitem>
1426           <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
1427    # <emphasis role="bold">cd /</emphasis>
1428    # <emphasis role="bold">shutdown -r now</emphasis>
1429    login: <emphasis role="bold">root</emphasis>
1430    Password: <replaceable>root_password</replaceable>
1431 </programlisting></para>
1432         </listitem>
1433
1434         <listitem>
1435           <para>Run the AFS initialization script.
1436 <programlisting>
1437    # <emphasis role="bold">/etc/rc.d/init.d/openafs-client  start</emphasis>
1438 </programlisting></para>
1439         </listitem>
1440
1441         <listitem>
1442           <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis role="bold">openafs-client</emphasis>
1443           configuration variable. Based on the instruction in the AFS initialization file that begins with the string
1444           <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic links that incorporate the
1445           script into the Linux startup and shutdown sequence. <programlisting>
1446    # <emphasis role="bold">/sbin/chkconfig  --add openafs-client</emphasis>
1447 </programlisting></para>
1448         </listitem>
1449       </orderedlist>
1450     </sect2>
1451
1452     <sect2 id="HDRWQ155">
1453       <title>Running the Script on other Linux Systems</title>
1454
1455       <orderedlist>
1456         <listitem>
1457           <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
1458    # <emphasis role="bold">cd /</emphasis>
1459    # <emphasis role="bold">shutdown -r now</emphasis>
1460    login: <emphasis role="bold">root</emphasis>
1461    Password: <replaceable>root_password</replaceable>
1462 </programlisting></para>
1463         </listitem>
1464
1465         <listitem>
1466           <para>Run the AFS initialization script. <programlisting>
1467    # <emphasis role="bold">/etc/rc.d/init.d/afs  start</emphasis>
1468 </programlisting></para>
1469         </listitem>
1470
1471         <listitem>
1472           <para>Issue the <emphasis role="bold">chkconfig</emphasis> command to activate the <emphasis role="bold">afs</emphasis>
1473           configuration variable. Based on the instruction in the AFS initialization file that begins with the string
1474           <computeroutput>#chkconfig</computeroutput>, the command automatically creates the symbolic links that incorporate the
1475           script into the Linux startup and shutdown sequence. <programlisting>
1476    # <emphasis role="bold">/sbin/chkconfig  --add afs</emphasis>
1477 </programlisting></para>
1478         </listitem>
1479
1480         <listitem>
1481           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
1482           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/rc.d/init.d</emphasis> directories, and
1483           copies of the <emphasis role="bold">afsd</emphasis> options file in both the <emphasis
1484           role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/sysconfig</emphasis> directories. If you want to avoid
1485           potential confusion by guaranteeing that the two copies of each file are always the same, create a link between them. You
1486           can always retrieve the original script or options file from the AFS CD-ROM if necessary. <programlisting>
1487    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
1488    # <emphasis role="bold">rm afs.rc afs.conf</emphasis>
1489    # <emphasis role="bold">ln -s  /etc/rc.d/init.d/afs  afs.rc</emphasis>
1490    # <emphasis role="bold">ln -s  /etc/sysconfig/afs  afs.conf</emphasis>
1491 </programlisting></para>
1492         </listitem>
1493
1494         <listitem>
1495           <para>If a volume for housing AFS binaries for this machine's system type does not already exist, proceed to <link
1496           linkend="HDRWQ157">Setting Up Volumes and Loading Binaries into AFS</link>. Otherwise, the installation is
1497           complete.</para>
1498         </listitem>
1499       </orderedlist>
1500
1501       <indexterm>
1502         <primary>afs file</primary>
1503
1504         <secondary>AFS initialization file</secondary>
1505       </indexterm>
1506
1507       <indexterm>
1508         <primary>files</primary>
1509
1510         <secondary>afs</secondary>
1511
1512         <tertiary>AFS initialization file</tertiary>
1513       </indexterm>
1514
1515       <indexterm>
1516         <primary>Solaris</primary>
1517
1518         <secondary>AFS initialization script</secondary>
1519
1520         <tertiary>on client machine</tertiary>
1521       </indexterm>
1522     </sect2>
1523
1524     <sect2 id="HDRWQ156">
1525       <title>Running the Script on Solaris Systems</title>
1526
1527       <orderedlist>
1528         <listitem>
1529           <para>Reboot the machine and log in again as the local superuser <emphasis role="bold">root</emphasis>. <programlisting>
1530    # <emphasis role="bold">cd /</emphasis>
1531    # <emphasis role="bold">shutdown -i6 -g0 -y</emphasis>
1532    login: <emphasis role="bold">root</emphasis>
1533    Password: <replaceable>root_password</replaceable>
1534 </programlisting></para>
1535         </listitem>
1536
1537         <listitem>
1538           <para>Run the AFS initialization script. <programlisting>
1539    # <emphasis role="bold">/etc/init.d/afs  start</emphasis>
1540 </programlisting></para>
1541         </listitem>
1542
1543         <listitem>
1544           <para>Change to the <emphasis role="bold">/etc/init.d</emphasis> directory and issue the <emphasis role="bold">ln
1545           -s</emphasis> command to create symbolic links that incorporate the AFS initialization script into the Solaris startup and
1546           shutdown sequence. <programlisting>
1547    # <emphasis role="bold">cd /etc/init.d</emphasis>
1548    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc3.d/S99afs</emphasis>
1549    # <emphasis role="bold">ln -s ../init.d/afs /etc/rc0.d/K66afs</emphasis>
1550 </programlisting></para>
1551         </listitem>
1552
1553         <listitem>
1554           <para><emphasis role="bold">(Optional)</emphasis> There are now copies of the AFS initialization file in both the
1555           <emphasis role="bold">/usr/vice/etc</emphasis> and <emphasis role="bold">/etc/init.d</emphasis> directories. If you want
1556           to avoid potential confusion by guaranteeing that they are always the same, create a link between them. You can always
1557           retrieve the original script from the OpenAFS Binary Distribution if necessary. <programlisting>
1558    # <emphasis role="bold">cd /usr/vice/etc</emphasis>
1559    # <emphasis role="bold">rm afs.rc</emphasis>
1560    # <emphasis role="bold">ln -s  /etc/init.d/afs  afs.rc</emphasis>
1561 </programlisting></para>
1562         </listitem>
1563
1564         <listitem>
1565           <para>If a volume for housing AFS binaries for this machine's system type does not already exist, proceed to <link
1566           linkend="HDRWQ157">Setting Up Volumes and Loading Binaries into AFS</link>. Otherwise, the installation is
1567           complete.</para>
1568         </listitem>
1569       </orderedlist>
1570
1571       <indexterm>
1572         <primary>storing</primary>
1573
1574         <secondary>AFS binaries in volumes</secondary>
1575       </indexterm>
1576
1577       <indexterm>
1578         <primary>creating</primary>
1579
1580         <secondary>volume</secondary>
1581
1582         <tertiary>for AFS binaries</tertiary>
1583       </indexterm>
1584
1585       <indexterm>
1586         <primary>volume</primary>
1587
1588         <secondary>for AFS binaries</secondary>
1589       </indexterm>
1590
1591       <indexterm>
1592         <primary>binaries</primary>
1593
1594         <secondary>storing AFS in volume</secondary>
1595       </indexterm>
1596
1597       <indexterm>
1598         <primary>usr/afsws directory</primary>
1599       </indexterm>
1600
1601       <indexterm>
1602         <primary>directories</primary>
1603
1604         <secondary>/usr/afsws</secondary>
1605       </indexterm>
1606     </sect2>
1607   </sect1>
1608
1609   <sect1 id="HDRWQ157">
1610     <title>Setting Up Volumes and Loading Binaries into AFS</title>
1611
1612     <note><para>If you are using an operating system which uses packaged
1613     binaries, such as .rpms or .debs, you should allow these package management
1614     systems to maintain your AFS binaries, rather than following the
1615     instructions in this section.</para></note>
1616
1617     <para>In this section, you link <emphasis role="bold">/usr/afsws</emphasis> on the local disk to the directory in AFS that
1618     houses AFS binaries for this system type. The conventional name for the AFS directory is <emphasis
1619     role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1620     role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis>.</para>
1621
1622     <para>If this machine is an existing system type, the AFS directory presumably already exists. You can simply create a link from
1623     the local <emphasis role="bold">/usr/afsws</emphasis> directory to it. Follow the instructions in <link
1624     linkend="HDRWQ158">Linking /usr/afsws on an Existing System Type</link>.</para>
1625
1626     <para>If this machine is a new system type (there are no AFS machines of this type in your cell), you must first create and
1627     mount volumes to store its AFS binaries, and then create the link from <emphasis role="bold">/usr/afsws</emphasis> to the new
1628     directory. See <link linkend="HDRWQ159">Creating Binary Volumes for a New System Type</link>.</para>
1629
1630     <para>You can also store UNIX system binaries (the files normally stored in local disk directories such as <emphasis
1631     role="bold">/bin</emphasis>, <emphasis role="bold">/etc</emphasis>, and <emphasis role="bold">/lib</emphasis>) in volumes
1632     mounted under <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1633     role="bold">/</emphasis><replaceable>sysname</replaceable>. See <link linkend="HDRWQ88">Storing System Binaries in AFS</link>
1634     .</para>
1635
1636     <sect2 id="HDRWQ158">
1637       <title>Linking /usr/afsws on an Existing System Type</title>
1638
1639       <para>If this client machine is an existing system type, there is already a volume mounted in the AFS filespace that houses
1640       AFS client binaries for it. <orderedlist>
1641           <listitem>
1642             <para>Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the directory <emphasis
1643             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws</emphasis>. You can
1644             specify the actual system name instead of <emphasis role="bold">@sys</emphasis> if you wish, but the advantage of using
1645             <emphasis role="bold">@sys</emphasis> is that it remains valid if you upgrade this machine to a different system type.
1646             <programlisting>
1647    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws  /usr/afsws</emphasis>
1648 </programlisting></para>
1649           </listitem>
1650
1651           <listitem>
1652             <para><emphasis role="bold">(Optional)</emphasis> If you believe it is helpful to your users to access the AFS documents
1653             in a certain format via a local disk directory, create <emphasis role="bold">/usr/afsdoc</emphasis> on the local disk as
1654             a symbolic link to the documentation directory in AFS (<emphasis
1655             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1656             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable>). <programlisting>
1657    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> <emphasis
1658                   role="bold">/usr/afsdoc</emphasis>
1659 </programlisting></para>
1660
1661             <para>An alternative is to create a link in each user's home directory to the <emphasis
1662             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1663             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> directory.</para>
1664           </listitem>
1665         </orderedlist></para>
1666     </sect2>
1667
1668     <sect2 id="HDRWQ159">
1669       <title>Creating Binary Volumes for a New System Type</title>
1670
1671       <para>If this client machine is a new system type, you must create and mount volumes for its binaries before you can link the
1672       local <emphasis role="bold">/usr/afsws</emphasis> directory to an AFS directory.</para>
1673
1674       <para>To create and mount the volumes, you use the
1675       <emphasis role="bold">kinit</emphasis> command to authenticate as an
1676       administrator, followed by the <emphasis role="bold">aklog</emphasis>
1677       command to gain tokens, and then issue commands from the
1678       <emphasis role="bold">vos</emphasis> and
1679       <emphasis role="bold">fs</emphasis> command suites. However, the
1680       command binaries are not yet available on this machine (by convention,
1681       they are accessible via the <emphasis role="bold">/usr/afsws</emphasis>
1682       link that you are about to create). You have two choices:
1683       <itemizedlist>
1684           <listitem>
1685             <para>Perform all steps except the last one (Step <link linkend="LIWQ162">10</link>) on an existing AFS machine. On a
1686             file server machine, the <emphasis role="bold">aklog</emphasis>, <emphasis role="bold">fs</emphasis> and <emphasis
1687             role="bold">vos</emphasis> binaries reside in the <emphasis role="bold">/usr/afs/bin</emphasis> directory. On client
1688             machines, the <emphasis role="bold">aklog</emphasis> and <emphasis role="bold">fs</emphasis> binaries reside in the
1689             <emphasis role="bold">/usr/afsws/bin</emphasis> directory and the <emphasis role="bold">vos</emphasis> binary in the
1690             <emphasis role="bold">/usr/afsws/etc</emphasis> directory. Depending on how your PATH environment variable is set, you
1691             possibly need to precede the command names with a pathname.</para>
1692
1693             <para>If you work on another AFS machine, be sure to substitute the new system type name for the
1694             <replaceable>sysname</replaceable> argument in the following commands, not the system type of the machine on which you
1695             are issuing the commands.</para>
1696           </listitem>
1697
1698           <listitem>
1699             <para>Copy the necessary command binaries to a temporary location on the local disk, which enables you to perform the
1700             steps on the local machine. The following procedure installs them in the <emphasis role="bold">/tmp</emphasis> directory
1701             and removes them at the end. Depending on how your PATH environment variable is set, you possibly need to precede the
1702             command names with a pathname.</para>
1703           </listitem>
1704         </itemizedlist></para>
1705
1706       <para>Perform the following steps to create a volume for housing AFS binaries. <orderedlist>
1707           <listitem>
1708             <para>Working either on the local machine or another AFS machine,
1709             extract the Open AFS distribtion tarball onto a directory on that
1710             machine. The following instructions assume that you are using the
1711             <emphasis role="bold">/tmp/afsdist</emphasis> directory.</para>
1712           </listitem>
1713
1714           <listitem>
1715             <para>If working on the local machine, copy the necessary binaries to a temporary location on the local disk. Substitute
1716             a different directory name for <emphasis role="bold">/tmp</emphasis> if you wish. <programlisting>
1717    # <emphasis role="bold">cd  /tmp/afsdist/</emphasis><replaceable>new_sysname</replaceable><emphasis role="bold">/root.server/usr/afs/bin</emphasis>
1718    # <emphasis role="bold">cp -p  aklog  /tmp</emphasis>
1719    # <emphasis role="bold">cp -p  fs  /tmp</emphasis>
1720    # <emphasis role="bold">cp -p  vos  /tmp</emphasis>
1721 </programlisting></para>
1722           </listitem>
1723
1724           <listitem>
1725             <para>Authenticate as the user <emphasis role="bold">admin</emphasis>.
1726 <programlisting>
1727    # <emphasis role="bold">kinit admin</emphasis>
1728    Password: <replaceable>admin_password</replaceable>
1729    # <emphasis role="bold">aklog</emphasis>
1730 </programlisting></para>
1731           </listitem>
1732
1733           <listitem id="LIWQ160">
1734             <para>Issue the <emphasis role="bold">vos create</emphasis> command to create volumes for storing
1735             the AFS client binaries for this system type. The following example instruction creates volumes called
1736             <replaceable>sysname</replaceable>, <replaceable>sysname</replaceable>.<emphasis role="bold">usr</emphasis>, and
1737             <replaceable>sysname</replaceable>.<emphasis role="bold">usr.afsws</emphasis>. Refer to the <emphasis>OpenAFS Release
1738             Notes</emphasis> to learn the proper value of <replaceable>sysname</replaceable> for this system type. <programlisting>
1739    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable>
1740    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable><emphasis
1741                   role="bold">.usr</emphasis>
1742    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable><emphasis
1743                   role="bold">.usr.afsws</emphasis>
1744 </programlisting></para>
1745           </listitem>
1746
1747           <listitem>
1748             <para>Issue the <emphasis role="bold">fs mkmount</emphasis> command to mount the newly created volumes. Because the
1749             <emphasis role="bold">root.cell</emphasis> volume is replicated, you must precede the <emphasis>cellname</emphasis> part
1750             of the pathname with a period to specify the read/write mount point, as shown. Then issue the <emphasis role="bold">vos
1751             release</emphasis> command to release a new replica of the <emphasis role="bold">root.cell</emphasis> volume, and the
1752             <emphasis role="bold">fs checkvolumes</emphasis> command to force the local Cache Manager to access them.
1753             <programlisting>
1754    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable> <emphasis
1755                   role="bold">-vol</emphasis> <replaceable>sysname</replaceable>
1756    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1757                   role="bold">/usr</emphasis>  <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis
1758                   role="bold">.usr</emphasis>
1759    # <emphasis role="bold">fs mkmount -dir /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1760                   role="bold">/usr/afsws</emphasis> <emphasis role="bold">-vol</emphasis> <replaceable>sysname</replaceable><emphasis
1761                   role="bold">.usr.afsws</emphasis>
1762    # <emphasis role="bold">vos release root.cell</emphasis>
1763    # <emphasis role="bold">fs checkvolumes</emphasis>
1764 </programlisting></para>
1765           </listitem>
1766
1767           <listitem>
1768             <para>Issue the <emphasis role="bold">fs setacl</emphasis> command to grant the <emphasis role="bold">l</emphasis>
1769             (<emphasis role="bold">lookup</emphasis>) and <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>)
1770             permissions to the <emphasis role="bold">system:anyuser</emphasis> group on each new directory's ACL. <programlisting>
1771    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable>
1772    # <emphasis role="bold">fs setacl  -dir  .  usr  usr/afsws  -acl  system:anyuser rl</emphasis>
1773 </programlisting></para>
1774           </listitem>
1775
1776           <listitem>
1777             <para>Issue the <emphasis role="bold">fs setquota</emphasis> command to set an unlimited quota on the volume mounted at
1778             the <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1779             role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory. This
1780             enables you to copy all of the appropriate files from the CD-ROM into the volume without exceeding the volume's
1781             quota.</para>
1782
1783             <para>If you wish, you can set the volume's quota to a finite value after you complete the copying operation. At that
1784             point, use the <emphasis role="bold">vos examine</emphasis> command to determine how much space the volume is occupying.
1785             Then issue the <emphasis role="bold">fs setquota</emphasis> command to set a quota that is slightly larger.</para>
1786
1787             <programlisting>
1788    # <emphasis role="bold">fs setquota /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1789                 role="bold">/usr/afsws  0</emphasis>
1790 </programlisting>
1791           </listitem>
1792
1793           <listitem id="LIWQ161">
1794             <para>Copy the contents of the indicated
1795             directories from the OpenAFS binary distribution into the
1796             <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1797             role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/usr/afsws</emphasis> directory.
1798             <programlisting>
1799    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1800                   role="bold">/usr/afsws</emphasis>
1801    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/bin  .</emphasis>
1802    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/etc  .</emphasis>
1803    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/include  .</emphasis>
1804    # <emphasis role="bold">cp -rp /cdrom/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/lib  .</emphasis>
1805 </programlisting></para>
1806           </listitem>
1807
1808           <listitem>
1809             <para>Issue the <emphasis role="bold">fs setacl</emphasis> command
1810             to set the ACL on each directory appropriately. If you wish to
1811             enable access to the software for locally authenticated users only,
1812             set the ACL on the <emphasis role="bold">etc</emphasis>,
1813             <emphasis role="bold">include</emphasis>, and
1814             <emphasis role="bold">lib</emphasis> subdirectories to grant the
1815             <emphasis role="bold">l</emphasis> and
1816             <emphasis role="bold">r</emphasis> permissions to the
1817             <emphasis role="bold">system:authuser</emphasis> group rather than
1818             the <emphasis role="bold">system:anyuser</emphasis> group. The
1819             <emphasis role="bold">system:anyuser</emphasis> group must retain
1820             the <emphasis role="bold">l</emphasis> and
1821             <emphasis role="bold">r</emphasis> permissions on the
1822             <emphasis role="bold">bin</emphasis> subdirectory to enable
1823             unauthenticated users to access the
1824             <emphasis role="bold">aklog</emphasis> binary.
1825 <programlisting>
1826    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable><emphasis
1827                   role="bold">/usr/afsws</emphasis>
1828    # <emphasis role="bold">fs setacl  -dir etc include lib  -acl  system:authuser rl</emphasis>  \
1829               <emphasis role="bold">system:anyuser none</emphasis>
1830 </programlisting></para>
1831           </listitem>
1832
1833           <listitem id="LIWQ162">
1834             <para>Perform this step on the new client machine even if you have performed the previous steps
1835             on another machine. Create <emphasis role="bold">/usr/afsws</emphasis> on the local disk as a symbolic link to the
1836             directory <emphasis role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1837             role="bold">/@sys/usr/afsws</emphasis>. You can specify the actual system name instead of <emphasis
1838             role="bold">@sys</emphasis> if you wish, but the advantage of using <emphasis role="bold">@sys</emphasis> is that it
1839             remains valid if you upgrade this machine to a different system type. <programlisting>
1840    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/@sys/usr/afsws  /usr/afsws</emphasis>
1841 </programlisting></para>
1842           </listitem>
1843
1844           <listitem>
1845             <para><emphasis role="bold">(Optional)</emphasis> To enable users to issue commands from the AFS suites (such as
1846             <emphasis role="bold">fs</emphasis>) without having to specify a pathname to their binaries, include the <emphasis
1847             role="bold">/usr/afsws/bin</emphasis> and <emphasis role="bold">/usr/afsws/etc</emphasis> directories in the PATH
1848             environment variable you define in each user's shell initialization file (such as <emphasis
1849             role="bold">.cshrc</emphasis>).</para>
1850           </listitem>
1851
1852           <listitem>
1853             <para><emphasis role="bold">(Optional)</emphasis> If you believe it is helpful to your users to access the AFS documents
1854             in a certain format via a local disk directory, create <emphasis role="bold">/usr/afsdoc</emphasis> on the local disk as
1855             a symbolic link to the documentation directory in AFS (<emphasis
1856             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1857             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable>). <programlisting>
1858    # <emphasis role="bold">ln -s /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> <emphasis
1859                   role="bold">/usr/afsdoc</emphasis>
1860 </programlisting></para>
1861
1862             <para>An alternative is to create a link in each user's home directory to the <emphasis
1863             role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis
1864             role="bold">/afsdoc/</emphasis><replaceable>format_name</replaceable> directory.</para>
1865           </listitem>
1866
1867           <listitem>
1868             <para><emphasis role="bold">(Optional)</emphasis> If working on the local machine, remove the AFS binaries from the
1869             temporary location. They are now accessible in the <emphasis role="bold">/usr/afsws</emphasis> directory.
1870             <programlisting>
1871    # <emphasis role="bold">cd  /tmp</emphasis>
1872    # <emphasis role="bold">rm  klog  fs  vos</emphasis>
1873 </programlisting></para>
1874           </listitem>
1875         </orderedlist></para>
1876     </sect2>
1877   </sect1>
1878 </chapter>