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