doc/html/AdminGuide/auagd016.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Guide</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3570/auagd000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 2 Oct 2000 at 11:42:14                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Mon, 02 Oct 2000 11:42:13">
   8 <META HTTP-EQUIV="review" CONTENT="Tue, 02 Oct 2001 11:42:13">
   9 <META HTTP-EQUIV="expires" CONTENT="Wed, 02 Oct 2002 11:42:13">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Guide</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd015.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auagd017.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <HR><H1><A NAME="HDRWQ419" HREF="auagd002.htm#ToC_491">Configuring Client Machines with the package Program</A></H1>
  18 <P>The <B>package</B> program automates many aspects of the
  19 client configuration process. With the <B>package</B> program, you
  20 can easily configure the local disk of numerous clients by defining global
  21 configuration files.
  22 <A NAME="IDX7519"></A>
  23 <A NAME="IDX7520"></A>
  24 <A NAME="IDX7521"></A>
  25 <A NAME="IDX7522"></A>
  26 <HR><H2><A NAME="HDRWQ420" HREF="auagd002.htm#ToC_492">Summary of Instructions</A></H2>
  27 <P>This chapter explains how to perform the following tasks by
  28 using the indicated commands or instructions in a prototype file:
  29 <BR>
  30 <TABLE WIDTH="100%">
  31 <TR>
  32 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="37%">Configure a client machine's local disk
  33 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="63%"><B>package</B>
  34 </TD></TR><TR>
  35 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="37%">Define directory
  36 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="63%"><B>D</B> [<VAR>update_code</VAR>] <VAR>directory</VAR> <VAR>owner</VAR>
  37 <VAR>group</VAR> <VAR>mode_bits</VAR>
  38 </TD></TR><TR>
  39 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="37%">Define file
  40 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="63%"><B>F</B> [<VAR>update_code</VAR>] <VAR>file</VAR> <VAR>source_file</VAR>
  41 [<VAR>owner</VAR> <VAR>group</VAR> <VAR>mode_bits</VAR>]
  42 </TD></TR><TR>
  43 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="37%">Define symbolic link
  44 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="63%"><B>L</B> [<VAR>update_code</VAR>] <VAR>link</VAR> <VAR>actual_file</VAR>
  45 [<VAR>owner</VAR> <VAR>group</VAR> <VAR>mode_bits</VAR>]
  46 </TD></TR><TR>
  47 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="37%">Define block special device
  48 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="63%"><B>B</B> <VAR>device_name</VAR> <VAR>major_device_number</VAR>
  49 <VAR>minor_device_number</VAR> <VAR>owner</VAR> <VAR>group</VAR> <VAR>mode_bits</VAR>
  50 </TD></TR><TR>
  51 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="37%">Define character special device
  52 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="63%"><B>C</B> <VAR>device_name</VAR> <VAR>major_device_number</VAR>
  53 <VAR>minor_device_number</VAR> <VAR>owner</VAR> <VAR>group</VAR> <VAR>mode_bits</VAR>
  54 </TD></TR><TR>
  55 <TD ALIGN="LEFT" VALIGN="TOP" WIDTH="37%">Define socket
  56 </TD><TD ALIGN="LEFT" VALIGN="TOP" WIDTH="63%"><B>S</B> <VAR>socket_name</VAR> [<VAR>owner</VAR> <VAR>group</VAR>
  57 <VAR>mode_bits</VAR>]
  58 </TD></TR></TABLE>
  59 <HR><H2><A NAME="HDRWQ422" HREF="auagd002.htm#ToC_493">Using the package Program</A></H2>
  60 <A NAME="IDX7523"></A>
  61 <A NAME="IDX7524"></A>
  62 <P>The <B>package</B> program uses system-independent <I>prototype
  63 files</I> to define a standard disk configuration; a prototype file
  64 indicates which files reside on the local client disk, which files are links
  65 into AFS, etc. The prototype files are then compiled into
  66 <I>configuration files</I> for each different system type.
  67 <P>Not all client machines have the same configuration. If desired, you
  68 can create different prototype files for different client functions (print
  69 server, regular client, etc.).
  70 <P>The <B>package</B> program compares the contents of a local client disk
  71 with the configuration file. If there are any differences, the
  72 <B>package</B> program makes the necessary updates to the local disk by
  73 copying the files from AFS onto the disk. The <B>package</B>
  74 program can also be configured to delete files that are not part of the system
  75 configuration or automatically reboot the client when certain files (such as
  76 the <B>dkload</B> file) have been updated.
  77 <P>The <B>package</B> program does require that you take some time to
  78 prepare the prototype files, but it provides the following benefits:
  79 <UL>
  80 <P><LI>You no longer need to configure each machine individually; the
  81 prototype configuration file applies to all machines.
  82 <P><LI>You can change the configuration of machines simply by changing the
  83 prototype file and rebooting the clients.
  84 <P><LI>Disk organization is uniform across a set of machines.
  85 <P><LI>The configuration files serve as a record of files on the disk and
  86 symbolic links into AFS.
  87 </UL>
  88 <P><H3><A NAME="Header_494" HREF="auagd002.htm#ToC_494">Using Package on File Server Machines</A></H3>
  89 <P>While the <B>package</B> program was designed for use on client
  90 machines, it can also be used to configure a file server machine's
  91 disk. However, if any of the files referred to in a configuration file
  92 reside in volumes on the file server, the <B>package</B> program cannot
  93 access the volumes during reboot (and until the File Server process and Volume
  94 Server process start up again).
  95 <P>Since the <B>package</B> program aborts when it cannot access a file,
  96 you need to eliminate references to files in AFS that reside in volumes on the
  97 file server machine. Because of these constraints, the remainder of
  98 this chapter assumes the <B>package</B> program is being used for client
  99 configurations.
 100 <HR><H2><A NAME="HDRWQ423" HREF="auagd002.htm#ToC_495">Package Overview</A></H2>
 101 <P>There are three main steps to follow before running the
 102 <B>package</B> program:
 103 <OL TYPE=1>
 104 <P><LI>Preparing function-specific <I>prototype files</I> (and any included
 105 <I>library files</I>).
 106 <P><LI>Modifying the <B>package</B> <B>Makefile</B> and compiling
 107 prototype files into system-specific <I>configuration files</I>.
 108 <P><LI>Modifying client machines to run the appropriate <B>package</B>
 109 configuration file automatically.
 110 </OL>
 111 <P>The following sections summarize these steps.
 112 <P><H3><A NAME="Header_496" HREF="auagd002.htm#ToC_496">Preparing Prototype Files</A></H3>
 113 <A NAME="IDX7525"></A>
 114 <A NAME="IDX7526"></A>
 115 <P>Begin by listing the different functions or roles client machines perform
 116 and the local disk configurations that support those functions. Example
 117 roles include a standard client that provides AFS access, a print server that
 118 drives a printer, and a backup machine on which you issue commands from the
 119 <B>backup</B> suite. Create a different <I>prototype file</I>
 120 for each role.
 121 <P>A prototype file defines the disk configuration that supports a specific
 122 role. Usually, prototype files are function-specific, but system
 123 independent; system-specific values can be defined using variables and
 124 library files. Then, when you modify a variable or library file, the
 125 change gets propagated to all appropriate clients when the <B>package</B>
 126 program is invoked.
 127 <P>Methods for building flexible prototype files that are easy to maintain are
 128 presented in <A HREF="#HDRWQ427">Example Prototype and Library Files</A>.
 129 <P><H3><A NAME="HDRWQ424" HREF="auagd002.htm#ToC_497">Compiling Prototype Files</A></H3>
 130 <A NAME="IDX7527"></A>
 131 <A NAME="IDX7528"></A>
 132 <A NAME="IDX7529"></A>
 133 <P>Prototype files are usually system-independent, but can include
 134 <TT>ifdef</TT> statements to satisfy the needs of different system
 135 types. The prototype files are compiled to generate operating-system
 136 specific versions. During compilation, the <B>package</B> program
 137 selects the definitions suitable for each system type and replaces any
 138 variables with actual values. These compiled, machine-specific files
 139 are called <I>configuration files</I>.
 140 <P>Prototype files are compiled using a standard-type <B>Makefile</B>
 141 file, as described in <A HREF="#HDRWQ438">The Package Makefile File</A>.
 142 <P><H3><A NAME="Header_498" HREF="auagd002.htm#ToC_498">Preparing Clients</A></H3>
 143 <P>Once system-specific configuration files exist, the <B>package</B>
 144 program is ready to run on the clients. You must first make the
 145 <B>package</B> binary available and specify the correct configuration
 146 file.
 147 <P>Modify the clients as described below:
 148 <OL TYPE=1>
 149 <P><LI>Create a <B>.package</B> file in the root ( <B>/</B> )
 150 directory of each client's local disk that defines the default
 151 configuration file.
 152 <P><LI>Make the <B>package</B> binary (<B>/etc/package</B>) available on
 153 the local disk.
 154 <P><LI>Modify the machine's initialization file (<B>/etc/rc</B> or
 155 equivalent) to include a call to the <B>package</B> program.
 156 </OL>
 157 <P>These steps are discussed more completely in <A HREF="#HDRWQ447">Modifying Client Machines</A>.
 158 <HR><H2><A NAME="HDRWQ425" HREF="auagd002.htm#ToC_499">The package Directory Structure</A></H2>
 159 <A NAME="IDX7530"></A>
 160 <P>This section assumes that the <B>package</B>-related files have been
 161 installed in three subdirectories of the
 162 <B>/afs/</B><VAR>cellname</VAR>/<B>wsadmin</B> directory:
 163 <B>src</B>, <B>lib</B> and <B>etc</B>, as recommended in the
 164 <I>IBM AFS Quick Beginnings</I>.
 165 <P>These directories contain several sample prototype, library, and
 166 configuration files, which can help to clarify how the <B>package</B>
 167 program works. However, they are not necessarily suitable for use in
 168 your cell; you must modify them for your needs.
 169 <P><H3><A NAME="HDRWQ426" HREF="auagd002.htm#ToC_500">The src directory</A></H3>
 170 <P>The <B>src</B> directory contains some sample prototype
 171 files (used to build the configuration files), the <B>Makefile</B> file
 172 used to build them, and the resulting compiled configuration files.
 173 <P>Prototype files have names of the form
 174 <VAR>function</VAR>.<B>proto</B>. For example, a
 175 <B>minimal.proto</B> file defines the minimum set of library files
 176 need to run AFS and a<B>staff.dkload.proto</B> file defines
 177 a client configuration that uses the a dynamic kernel loading program.
 178 Prototype files can also contain definitions for system administrative files,
 179 such as a <B>hosts.equiv</B> file.
 180 <P>The <B>Makefile</B> file is used to compile the system-independent
 181 prototype files into system-specific configuration files. To learn how
 182 to modify this file for use in your cell, see <A HREF="#HDRWQ438">The Package Makefile File</A>.
 183 <P>Configuration files are the compiled version of the prototype files and are
 184 named <VAR>function</VAR><B>.</B><VAR>sysname</VAR>.
 185 Configuration files also appear in the <B>etc</B> subdirectory, which the
 186 <B>package</B> program accesses when configuring disks.
 187 <P><H3><A NAME="Header_501" HREF="auagd002.htm#ToC_501">The lib directory</A></H3>
 188 <P>The <B>lib</B> directory contains many of the example library files
 189 referred to in prototype files. For example, the
 190 <B>base.generic</B> file is a system-independent file which
 191 includes a definition of the cell name, system options, and variables;
 192 these are used to set the <VAR>owner</VAR>, <VAR>group</VAR>, and
 193 <VAR>mode_bits</VAR> fields in the file and the symbolic link
 194 definitions.
 195 <P><H3><A NAME="Header_502" HREF="auagd002.htm#ToC_502">The etc directory</A></H3>
 196 <P>The <B>etc</B> directory contains the system-specific configuration
 197 files built from the prototype files in the <B>src</B>
 198 subdirectory. The <B>package</B> program uses the configuration
 199 files in the <B>etc</B> directory to configure disks.
 200 <P>Some of the example files include <B>minimal</B> and <B>staff</B>
 201 prototype files compiled for different system types.
 202 <HR><H2><A NAME="HDRWQ427" HREF="auagd002.htm#ToC_503">Example Prototype and Library Files</A></H2>
 203 <A NAME="IDX7531"></A>
 204 <A NAME="IDX7532"></A>
 205 <P>A prototype file is a template that defines the configuration of a
 206 client's local disk. Prototype files are usually function-specific
 207 (for example, a backup machine, print server, etc.) but
 208 system-independent. Prototype files support the use of <TT>ifdef</TT>
 209 statements and variables, so you can include system-specific
 210 definitions. The actual system-specific configuration file is generated
 211 when the prototype file is compiled.
 212 <P>The components defined in a prototype file can include the directories,
 213 files, symbolic links, block special devices, character special devices and
 214 sockets that need to reside on a client's local disk in order for it to
 215 perform a specific role, such as a print server or backup machine.
 216 Thus, we recommend that you construct a unique prototype file for each
 217 different client function.
 218 <P>To make the <B>package</B> program more effective and easy to maintain,
 219 create prototype files that are modular and generic, instead of specific, by
 220 using library files and variables:
 221 <A NAME="IDX7533"></A>
 222 <A NAME="IDX7534"></A>
 223 <UL>
 224 <P><LI>By creating general-purpose library files, you can include the same
 225 library file in many prototype files. Thus, you can make global
 226 configuration changes by modifying a single library file; you do not need
 227 to modify each prototype file.
 228 <P><LI>Variables enable you to change definitions simply by changing the
 229 variable's value.
 230 </UL>
 231 <P><H3><A NAME="HDRWQ428" HREF="auagd002.htm#ToC_504">An Example Prototype File</A></H3>
 232 <A NAME="IDX7535"></A>
 233 <P>The following is part of an example prototype file that contains the
 234 minimum definitions necessary to run AFS. A similar file called
 235 <B>minimal.proto</B> can reside in your <B>src</B>
 236 subdirectory. As recommended, this prototype file references library
 237 files and does not include actual definitions.
 238 <PRE>            .
 239             .
 240    # Package prototype for a minimal configuration.
 241    # Base components
 242    %include ${wsadmin}/lib/base.generic
 243    # Machine-specific components
 244    %ifdef rs_aix42
 245    %include ${wsadmin}/lib/rs_aix42.readonly
 246    %include ${wsadmin}/lib/rs_aix42.AFS
 247    %endif rs_aix42
 248    %ifdef alpha_dux40
 249    %include ${wsadmin}/lib/alpha_dux40.readonly
 250    %include ${wsadmin}/lib/alpha_dux40.AFS
 251    %endif alpha_dux40
 252    %ifdef sun4x_56
 253    %include ${wsadmin}/lib/sun4x_56.readonly
 254    %include ${wsadmin}/lib/sun4x_56.AFS
 255    %endif sun4x_56
 256             .
 257             .
 258 </PRE>
 259 <P>In the previous example, the first uncommented line includes the
 260 <B>/lib/base.generic</B> library file. This library file can
 261 contain definitions appropriate for many prototype files; the
 262 <B>base.generic</B> library file can also be included in other
 263 prototype files, like a <B>staff.proto</B> or
 264 <B>backup.proto</B> file. An example library file appears in
 265 the following section.
 266 <P>Note that system-specific definitions are permitted through the use of
 267 <TT>ifdef</TT> statements and variables (for example, <TT>${wsadmin}</TT>
 268 is used to specify pathnames). Thus, the same prototype file can be
 269 used to configure a machine running AIX 4.2 or Solaris 2.6, even
 270 though they require different files, directories, symbolic links and
 271 devices.
 272 <P>In the next uncommented lines of this example, the administrator has
 273 constructed different library files for different system types. Each of
 274 these is compiled into unique configuration files. For instance, the
 275 following lines in this prototype file tell the <B>package</B> program to
 276 use the library files <B>lib/rs_aix42.readonly</B> and
 277 <B>lib/rs_aix42.AFS</B> for the configuration file when the value
 278 <TT>rs_aix42</TT> has been declared. (The system-type definition is
 279 declared in the <B>Makefile</B>; see <A HREF="#HDRWQ438">The Package Makefile File</A>.)
 280 <PRE>   %ifdef rs_aix42
 281    %include ${wsadmin}/lib/rs_aix42.readonly
 282    %include ${wsadmin}/lib/rs_aix42.AFS
 283    %endif rs_aix42
 284 </PRE>
 285 <P>Similarly, the following lines tell the <B>package</B> program to use
 286 the library files <B>lib/sun4x_56.readonly</B> and
 287 <B>lib/sun4x_56.AFS</B> when the value <TT>sun4x_56</TT> has been
 288 declared.
 289 <PRE>   %ifdef sun4x_56
 290    %include ${wsadmin}/lib/sun4x_56.readonly
 291    %include ${wsadmin}/lib/sun4x_56.AFS
 292    %endif sun4x_56
 293 </PRE>
 294 <P><H3><A NAME="Header_505" HREF="auagd002.htm#ToC_505">Example Library File</A></H3>
 295 <A NAME="IDX7536"></A>
 296 <A NAME="IDX7537"></A>
 297 <A NAME="IDX7538"></A>
 298 <A NAME="IDX7539"></A>
 299 <P>The following is part of an example library file for basic configuration
 300 definitions. A similar file, called <B>base.generic</B>, can
 301 reside in your <B>lib</B> subdirectory. Note that configurations
 302 are defined using standard <TT>ifdef</TT> statements.
 303 <PRE>            .
 304             .
 305    #
 306    # Base package definitions.
 307    #
 308    %ifndef      cell
 309    %define      cell    abc.com
 310    %endif       cell
 311    %ifndef      sys
 312    %include /etc/package.sys
 313    %endif       sys
 314    %define      ${name}         ${name}
 315    %define      ${cpu}          ${cpu}
 316    %define      ${sys}          ${sys}
 317    %define      ${dept}         ${dept}
 318    %define      ${hostname}     ${hostname}
 319    %ifdef       rs_aix42
 320    %    define  AIX
 321    %    define  rootlinks
 322    %ifndef      noafsd
 323    %    define  afsd
 324    %endif       noafsd
 325    %endif       rs_aix42
 326             .
 327             .
 328    #
 329    # Some definitions to handle common combinations of owner, group,
 330    # and protection fields.
 331    #
 332    %define      rzmode          root wheel 600
 333    %define      usermode        root wheel 666
 334    %define      systemmode      root wheel 644
 335    %define      diskmode        root wheel 644
 336    %define      ptymode         root wheel 666
 337    %define      ttymode         root wheel 666
 338             .
 339             .
 340    %define aix_rootbin     root bin
 341    %define aix_rootprintq  root printq
 342    %define aix_rootstaff   root staff
 343    %define aix_rootsys     root system
 344    %define aix_binbin      bin bin
 345    %define aix_binmail     bin mail
 346    %define aix_binsys      bin system
 347    %define aix_addsys      adduser system
 348    %define aix_romode      444
 349    %define aix_loginmode   544
 350    %define aix_usermode    666
 351    %define aix_systemmode  644
 352    %define aix_textmode    644
 353    %define aix_rwmode1     660
 354    %define aix_allrugw     664
 355 </PRE>
 356 <P>The following example library file uses <B>package</B>-specific syntax
 357 to define files, directories, sockets, etc. Each line, called a
 358 <I>configuration file instruction</I>, defines a specific component of
 359 disk configuration. The proper syntax for these instructions is briefly
 360 described in <A HREF="#HDRWQ429">Package Configuration File Instruction Syntax</A>; see the reference page for the <B>package</B>
 361 configuration file in the <I>IBM AFS Administration Reference</I> for
 362 detailed descriptions.
 363 <P>In this example, the library file contains instructions specific to the
 364 configuration of an <B>rs_aix42</B> machine. You can have similar
 365 library files in your <B>lib</B> subdirectory.
 366 <PRE>            .
 367             .
 368    #
 369    # Generic configuration for an AFS rs_aix42 machine.
 370    #
 371    D    /                                       ${treemode}
 372    D    /afs
 373    FAQ  /unix          ${machine}/unix.std      ${binmode}
 374    LA   /unix.std       /unix
 375    D    /bin                                    ${treemode}
 376    F    /bin/as         ${machine}              ${binmode}
 377    F    /bin/ld         ${machine}              ${binmode}
 378    F    /bin/nm         ${machine}              ${binmode}
 379    FO   /bin/login      ${afstest}              ${suidmode}
 380             .
 381             .
 382    FAQ  /usr/vice/etc/ThisCell  ${common}/etc/ThisCell ${textmode}
 383    FQ   /usr/vice/etc/afsd      ${afstest}/root.client ${binmode}
 384    FA   /usr/vice/etc/bos       ${afstest}/bin/bos     ${binmode}
 385    FA   /usr/vice/etc/fs        ${afstest}/bin/fs      ${binmode}
 386 </PRE>
 387 <HR><H2><A NAME="HDRWQ429" HREF="auagd002.htm#ToC_506">Package Configuration File Instruction Syntax</A></H2>
 388 <A NAME="IDX7540"></A>
 389 <A NAME="IDX7541"></A>
 390 <P>Within a library file, configuration file instructions are used to define
 391 the specific disk configuration. Each instruction can be used to define
 392 a file, directory, socket, or device on the client machine. The syntax
 393 for each valid instruction type is described briefly here; detailed
 394 descriptions of the fields appear in the <I>AFS Command Reference
 395 Manual</I>.
 396 <UL>
 397 <P><LI><B>D</B> defines a directory
 398 <P><LI><B>F</B> defines a file
 399 <P><LI><B>L</B> defines a link
 400 <P><LI><B>B</B> defines a block special device
 401 <P><LI><B>C</B> defines a character special device
 402 <P><LI><B>S</B> defines a socket
 403 </UL>
 404 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Each configuration instruction must appear on a single, unbroken line.
 405 Instructions sometimes appear here on multiple lines only for
 406 legibility.
 407 <P>The configuration file must be completely correct. If there are any
 408 syntax errors or incorrect values, the <B>package</B> command interpreter
 409 exits without executing any instruction.
 410 </TD></TR></TABLE>
 411 <P><H3><A NAME="HDRWQ430" HREF="auagd002.htm#ToC_507">Local Files versus Symbolic Links</A></H3>
 412 <P>You can take advantage of the AFS by keeping the number of
 413 files on the local client disk to a minimum; instead, create symbolic
 414 links that point into AFS. This can improve machine performance by
 415 allowing more space for caching and swapping.
 416 <P>Some files, however, must reside on the local disk, as described
 417 below. Create these files in the prototype or library files using the
 418 <B>F</B> (file) instruction, not the <B>L</B> (symbolic link)
 419 instruction.
 420 <P>The following types of files must reside on the local disk of all AFS
 421 clients:
 422 <UL>
 423 <P><LI>Boot sequence files executed before the <B>afsd</B> program
 424 runs.
 425 <P>Until <B>afsd</B> runs and initializes the Cache Manager, AFS is
 426 inaccessible from the client. Any files that are executed before the
 427 <B>afsd</B> program runs must reside on the local client disk.
 428 <P>For example, on a machine that uses a disk cache, the
 429 <B>/usr/vice/cache</B> directory must exist when you bring up the Cache
 430 Manager, so that there is a location to create cache files. The binary
 431 files <B>/etc/mount</B> and <B>/etc/umount</B> must be available on
 432 the local disk as the machine boots in order to mount the
 433 <B>/usr/vice/cache</B> directory.
 434 <P>In addition, certain UNIX files, such as initialization files
 435 (<B>/etc/rc</B> or equivalent) and file system mapping files
 436 (<B>/etc/fstab</B> or equivalent), must reside on the local disk.
 437 <P><LI>Diagnostic and recovery files
 438 <P>Certain commands can be used to diagnose and recover from problems caused
 439 by a file server outage. It is best to keep copies of the binaries for
 440 these commands on the local disk. For example, store the <B>bos</B>
 441 and <B>fs</B> binaries in the <B>/usr/vice/etc</B> directory on the
 442 local disk, as well as in the <B>/usr/afsws</B> directory (which in the
 443 conventional configuration is a symbolic link into AFS). Then, set PATH
 444 variables so that the <B>/usr/afsws</B> directory appears before the
 445 <B>/usr/vice/etc</B> directory. Thus, even if users cannot access
 446 AFS (for example, due to a file server outage) they can still access copies of
 447 the <B>bos</B> and <B>fs</B> binaries in the <B>/usr/vice/etc</B>
 448 directory on the local disk.
 449 <P><LI>Files in the <B>/usr/vice</B> directory
 450 <P>The contents of the <B>/usr/vice</B> directory, including the cache
 451 files in the <B>cache</B> subdirectory and the configuration files in the
 452 <B>etc</B> subdirectory, must reside on the local disk. For a
 453 description of the files in the directory, see <A HREF="auagd015.htm#HDRWQ391">Configuration and Cache-Related Files on the Local Disk</A>.
 454 </UL>
 455 <A NAME="IDX7542"></A>
 456 <A NAME="IDX7543"></A>
 457 <A NAME="IDX7544"></A>
 458 <A NAME="IDX7545"></A>
 459 <P><H3><A NAME="HDRWQ431" HREF="auagd002.htm#ToC_508">Defining a Directory</A></H3>
 460 <P>The <B>D</B> instruction defines a directory to be
 461 created on the local disk. If a symbolic link, file, or other element
 462 on the local disk has the same name, it is replaced with a directory.
 463 If the directory already exists, its owner, group, and mode bits are changed
 464 if necessary to conform with the instruction.
 465 <P>Use the following instruction to define a directory:
 466 <PRE>   <B>D</B>[<VAR>update_code</VAR>]   <VAR>directory</VAR>   <VAR>owner</VAR>   <VAR>group</VAR>   <VAR>mode_bits</VAR>
 467 </PRE>
 468 <P>The following example defines the <B>/usr</B> directory:
 469 <PRE>   D /usr root wheel 755
 470 </PRE>
 471 <A NAME="IDX7546"></A>
 472 <A NAME="IDX7547"></A>
 473 <A NAME="IDX7548"></A>
 474 <A NAME="IDX7549"></A>
 475 <P><H3><A NAME="HDRWQ432" HREF="auagd002.htm#ToC_509">Defining a File</A></H3>
 476 <P>The <B>F</B> instruction defines a file to be created on
 477 the local disk. The source file can reside in either AFS or the local
 478 disk.
 479 <P>If a file of this name already exists, then it is updated with (overwritten
 480 by) the source file, unless the <B>I</B> update code is specified.
 481 If a symbolic link or directory of this name exists, the <B>package</B>
 482 program replaces it with the source file.
 483 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Some files must reside on the local disk; they cannot be symbolic
 484 links. See <A HREF="#HDRWQ430">Local Files versus Symbolic Links</A>.
 485 </TD></TR></TABLE>
 486 <P>Use the following instruction to define a file:
 487 <PRE>   <B>F</B>[<VAR>update_code</VAR>]   <VAR>file</VAR>   <VAR>source_file</VAR>  [<VAR>owner</VAR>   <VAR>group</VAR>   <VAR>mode_bits</VAR>]
 488 </PRE>
 489 <P>An example which creates/updates the file <B>/bin/grep</B> on the local
 490 disk, using <B>/afs/abc.com/rs_aix42/bin/grep</B> as the
 491 source:
 492 <PRE>   F /bin/grep /afs/abc.com/rs_aix42 root wheel 755
 493 </PRE>
 494 <P>In the following example, two update codes are used, and the
 495 <I>owner</I>, <I>group</I> and <I>mode_bits</I> slots are left
 496 empty, so that the disk file adopts the source file's values for those
 497 slots.
 498 <PRE>   FAQ /usr/vice/etc/ThisCell /afs/abc.com/common/etc/ThisCell
 499 </PRE>
 500 <A NAME="IDX7550"></A>
 501 <A NAME="IDX7551"></A>
 502 <A NAME="IDX7552"></A>
 503 <A NAME="IDX7553"></A>
 504 <P><H3><A NAME="HDRWQ433" HREF="auagd002.htm#ToC_510">Defining a Symbolic Link</A></H3>
 505 <P>The <B>L</B> instruction defines a symbolic link to be
 506 created on the local disk. The symbolic link can point to the AFS file
 507 system or the local disk. If the identical symbolic link already
 508 exists, the <B>package</B> program does nothing. However, if an
 509 element of the same name exists on the disk as a file or directory, the
 510 <B>package</B> program replaces the element with a symbolic link.
 511 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Some files must reside on the local disk; they cannot be symbolic
 512 links. See <A HREF="#HDRWQ430">Local Files versus Symbolic Links</A>.
 513 </TD></TR></TABLE>
 514 <P>Use the following instruction to define a symbolic link:
 515 <PRE>   <B>L</B>[<VAR>update_code</VAR>]  <VAR>link</VAR> <VAR>actual_file</VAR>  [<VAR>owner</VAR>   <VAR>group</VAR>   <VAR>mode_bits</VAR>]
 516 </PRE>
 517 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Do not create a symbolic link to a file whose name begins with the number
 518 sign (<B>#</B>) or percent sign (<B>%</B>). The Cache Manager
 519 interprets such a link as a mount point to a regular or Read/Write volume,
 520 respectively.
 521 </TD></TR></TABLE>
 522 <P>The following example creates a symbolic link from the <B>/etc/ftpd</B>
 523 directory on the local disk to the
 524 <B>/afs/abc.com/hp_ux110/etc/ftpd</B> file in AFS. Since the
 525 <I>owner</I>, <I>group</I> and <I>mode_bits</I> fields are empty,
 526 the symbolic link adopts values for those fields from the actual file:
 527 <PRE>   L /etc/ftpd /afs/abc.com/hp_ux110
 528 </PRE>
 529 <P>This example uses the <B>A</B> update code:
 530 <PRE>   LA /etc/printcap /afs/abc.com/common/etc/printcap.remote
 531                root wheel 644
 532 </PRE>
 533 <A NAME="IDX7554"></A>
 534 <A NAME="IDX7555"></A>
 535 <A NAME="IDX7556"></A>
 536 <A NAME="IDX7557"></A>
 537 <P><H3><A NAME="HDRWQ434" HREF="auagd002.htm#ToC_511">Defining a Block Special Device</A></H3>
 538 <P>The <B>B</B> instruction defines a block special device,
 539 which is a device that handles data in units of multibyte blocks, such as a
 540 disk. If a device of the same name already exists, the
 541 <B>package</B> program replaces it with the specified block device.
 542 <P>Use the following instruction to define a block special device (it appears
 543 on two lines here only for legibility):
 544 <PRE>   <B>B</B> <VAR>device_name</VAR>   <VAR>major_device_number</VAR>   <VAR>minor_device_number</VAR>  \
 545       <VAR>owner</VAR>   <VAR>group</VAR>   <VAR>mode_bits</VAR>
 546 </PRE>
 547 <P>The following example defines a disk called <B>/dev/hd0a</B> to have
 548 major and minor device numbers <B>1</B> and <B>0</B>:
 549 <PRE>   B /dev/hd0a 1 0 root wheel 644
 550 </PRE>
 551 <A NAME="IDX7558"></A>
 552 <A NAME="IDX7559"></A>
 553 <A NAME="IDX7560"></A>
 554 <A NAME="IDX7561"></A>
 555 <P><H3><A NAME="HDRWQ435" HREF="auagd002.htm#ToC_512">Defining a Character Special Device</A></H3>
 556 <P>The <B>C</B> instruction defines a character special
 557 device, which is device that handles data in units of a single character at a
 558 time, such as a terminal or tty. If a device of the same name already
 559 exists, the <B>package</B> program replaces it with the specified
 560 character device.
 561 <P>Use the following instruction to define a character special device (it
 562 appears here on two lines only for legibility):
 563 <PRE>   <B>C </B><VAR>device_name</VAR>   <VAR>major_device_number</VAR>   <VAR>minor_device_number</VAR>  \
 564       <VAR>owner</VAR>   <VAR>group</VAR>   <VAR>mode_bits</VAR>
 565 </PRE>
 566 <P>The following example defines the tty called <B>/dev/ttyp5</B> with
 567 major and minor device numbers <B>6</B> and <B>5</B>:
 568 <PRE>   C /dev/ttyp5 6 5 root wheel 666
 569 </PRE>
 570 <A NAME="IDX7562"></A>
 571 <A NAME="IDX7563"></A>
 572 <A NAME="IDX7564"></A>
 573 <A NAME="IDX7565"></A>
 574 <P><H3><A NAME="HDRWQ436" HREF="auagd002.htm#ToC_513">Defining a Socket</A></H3>
 575 <P>The <B>S</B> instruction defines a socket, which is
 576 communications device for UDP and TCP/IP connections. If a socket of
 577 the same name already exists, the <B>package</B> program replaces
 578 it.
 579 <P>Use the following instruction to define a socket:
 580 <PRE>   <B>S</B>   <VAR>socket_name</VAR>   [<VAR>owner</VAR>   <VAR>group</VAR>   <VAR>mode_bits</VAR>]
 581 </PRE>
 582 <P>The following example defines a socket called
 583 <B>/dev/printer</B>:
 584 <PRE>   S /dev/printer root wheel 777
 585 </PRE>
 586 <HR><H2><A NAME="HDRWQ437" HREF="auagd002.htm#ToC_514">Constructing Prototype and Library Files</A></H2>
 587 <A NAME="IDX7566"></A>
 588 <A NAME="IDX7567"></A>
 589 <A NAME="IDX7568"></A>
 590 <P>This section describes the general steps required to create
 591 <B>package</B> prototype and library files. Refer to the previous
 592 sections for guidelines, and the files in your <B>wsadmin</B> directory
 593 for examples. The construction of prototype and library files is
 594 different for each cell.
 595 <P><H3><A NAME="Header_515" HREF="auagd002.htm#ToC_515">To construct a prototype file and its component library files</A></H3>
 596 <OL TYPE=1>
 597 <P><LI>Determine where the three <B>package</B>-related subdirectories
 598 (<B>src</B>, <B>lib</B> and <B>etc</B>) reside in your cell's
 599 file tree; the following instructions assume they were loaded into the
 600 <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin</B> directory, as described
 601 in the <I>IBM AFS Quick Beginnings</I>.
 602 <P><LI>Decide how many different functions you want client machines in your cell
 603 to perform. We recommend that you construct a separate prototype file
 604 for each function. Common functions include:
 605 <UL>
 606 <P><LI>Standard workstation: provides users with access to files in AFS
 607 <P><LI>Printer server: drives a printer; can be combined with "staff"
 608 functionality
 609 <P><LI>Backup machine: performs backups of AFS volumes to tape by running
 610 the AFS Backup System software
 611 </UL>
 612 <P><LI>Determine the minimum functionality needed for all clients (such as AFS
 613 setup) and place these generic definitions in one or more library
 614 files.
 615 <P><LI>For each type of client (printer server, backup machine, and so on), place
 616 all system-independent definitions in one file, and all operating-system
 617 dependent definitions in another file.
 618 </OL>
 619 <HR><H2><A NAME="HDRWQ438" HREF="auagd002.htm#ToC_516">The Package Makefile File</A></H2>
 620 <A NAME="IDX7569"></A>
 621 <A NAME="IDX7570"></A>
 622 <A NAME="IDX7571"></A>
 623 <P>Once you have created the appropriate prototype and library files, you must
 624 compile the prototype for each system type. The result is a
 625 system-specific configuration file.
 626 <P>The <B>Makefile</B> file defines the prototype and library files used
 627 and the order of compilation. We recommend that you create your
 628 <B>Makefile</B> file by modifying the example provided with the AFS
 629 distribution, as described in this section. In the conventional
 630 configuration, it is located at
 631 <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin/src/Makefile</B>.
 632 <P><H3><A NAME="Header_517" HREF="auagd002.htm#ToC_517">Overview</A></H3>
 633 <P>The following list summarizes the sections in the <B>package</B>
 634 <B>Makefile</B> file, identifying each by the header name that begins the
 635 section. More detailed descriptions follow.
 636 <DL>
 637 <P><DT><B><TT>CONFIG=</TT>
 638 </B><DD>Lists all of the configuration files to be created and defines which
 639 prototype files are compiled for which system types. See <A HREF="#HDRWQ439">The CONFIG Section</A>.
 640 <P><DT><B><TT>BASE_LIBS=</TT>
 641 </B><DD>Lists the pathnames of all operating-system- and function independent
 642 library files included in any prototype files. See <A HREF="#HDRWQ440">The BASE_LIBS Section</A>.
 643 <P><DT><B><TT>MACHINE_LIBS=</TT>
 644 </B><DD>Lists the pathnames of all operating-system-specific library files
 645 included in any prototype files. See <A HREF="#HDRWQ441">The MACHINE_LIBS Section</A>.
 646 <P><DT><B><TT>LIBS=</TT>
 647 </B><DD>A one-line instruction that defines <TT>LIBS</TT> as the combination of
 648 <TT>BASE_LIBS</TT> and <TT>MACHINE_LIBS</TT>. See <A HREF="#HDRWQ442">The LIBS Section</A>.
 649 <P><DT><B><TT>.SUFFIXES</TT>
 650 </B><DD>Defines all of the suffixes that can appear on a prototype or
 651 configuration file. See <A HREF="#HDRWQ443">The .SUFFIXES Section</A>.
 652 </DL>
 653 <P>Finally, the <B>Makefile</B> file contains a set of instructions that
 654 the <B>package</B> program follows to generate configuration files.
 655 It is not generally necessary to alter this section. See <A HREF="#HDRWQ444">The Makefile Instructions Section</A>.
 656 <P><H3><A NAME="HDRWQ439" HREF="auagd002.htm#ToC_518">The CONFIG Section</A></H3>
 657 <P>As mentioned, a configuration file is a prototype file that
 658 has been compiled for a specific operating system type. The
 659 <TT>CONFIG</TT> section of the <B>Makefile</B> file defines the
 660 prototype files to compile for each system type. The resulting compiled
 661 file is a system-specific configuration file.
 662 <P>Study the following example taken from the sample <B>Makefile</B>
 663 file. Configuration files are defined by specifying the
 664 prototype-system combination as
 665 <VAR>prototype_file</VAR><B>.</B><VAR>sysname</VAR>. Note that
 666 it is not necessary to generate a configuration file for each prototype-system
 667 type combination.
 668 <PRE>   #Makefile...
 669    #    (C) Copyright IBM Corporation 1999
 670    #    Licensed Materials - Property of IBM
 671    #    All Rights Reserved.
 672    #
 673    CONFIG = \
 674             staff.rs_aix42 \
 675             staff.alpha_dux40 \
 676             staff.xdm.alpha_dux40 \
 677             staff.sun4x_56 \
 678             staff.hp_ux110 \
 679             minimal.rs_aix42 \
 680             minimal.alpha_dux40 \
 681             minimal.hp_ux110 \
 682             minimal.sun4x_56
 683 </PRE>
 684 <P>An entry in the <TT>CONFIG</TT> section has the following format:
 685 <UL>
 686 <P><LI>The first part of the entry defines the prototype file and is the same as
 687 the prototype file name (without the <B>.proto</B>
 688 extension). The second part of the entry indicates the system type for
 689 which the prototype file is to be compiled. A complete list of these
 690 suffixes is in the <TT>.SUFFIXES</TT> section of the
 691 <B>Makefile</B> file, as described in <A HREF="#HDRWQ443">The .SUFFIXES Section</A>. This
 692 <VAR>prototype_file</VAR><B>.</B><VAR>sysname</VAR> definition becomes
 693 the name of the compiled configuration file.
 694 <P>For example, <B>staff.rs_aix42</B> indicates that the
 695 <B>staff.proto</B> file is compiled for machines running AIX
 696 4.2. The resulting compiled configuration file is called
 697 <B>staff.rs_aix42</B>.
 698 <P><LI>Each configuration file must appear on a separate line.
 699 <P><LI>A backslash must follow the <TT>CONFIG=</TT> header and every name but
 700 the last one. A backslash must also appear on blank lines.
 701 </UL>
 702 <P><H3><A NAME="HDRWQ440" HREF="auagd002.htm#ToC_519">The BASE_LIBS Section</A></H3>
 703 <P>This section defines the complete pathname of all system-
 704 and function-independent library files included in any prototype file.
 705 (System-specific library files are defined in the <TT>MACHINE_LIBS</TT>
 706 section). The pathnames can include the <TT>${wsadmin}</TT> variable,
 707 whose value is supplied on the <B>make</B> command line.
 708 <P>You must include all of the library files referred to in your prototype
 709 files; files included but not used are ignored.
 710 <P>Study the following example. Note that the all entries (except the
 711 last one) must be followed by a backslash.
 712 <PRE>   BASE_LIBS = \
 713            ${wsadmin}/src/admin \
 714            ${wsadmin}/lib/devel \
 715            ${wsadmin}/lib/base.generic
 716 </PRE>
 717 <P><H3><A NAME="HDRWQ441" HREF="auagd002.htm#ToC_520">The MACHINE_LIBS Section</A></H3>
 718 <P>This section lists the complete pathname of all
 719 operating-system-specific library files included in prototype files.
 720 (System- and function-independent library files are defined in the
 721 <TT>BASE_LIBS</TT> section.)
 722 <P>Study the following example. Note that in this example, library
 723 files were grouped by operating-system type. Again, all lines (except
 724 the last one) must be followed by a backslash, the <TT>${wsadmin}</TT>
 725 variable is allowed, and files included but not used are ignored.
 726 <PRE>   MACHINE_LIBS = \
 727            ${wsadmin}/lib/rs_aix42.generic \
 728            ${wsadmin}/lib/rs_aix42.generic.dev \
 729            ${wsadmin}/lib/rs_aix42.readonly \
 730            ${wsadmin}/lib/rs_aix42.readwrite \
 731            ${wsadmin}/lib/rt_aix42.generic.printer \
 732     \
 733     .
 734     .
 735            ${wsadmin}/lib/alpha_dux40.AFS \
 736            ${wsadmin}/lib/hp_ux110.AFS \
 737            ${wsadmin}/lib/sun4x_56.AFS \
 738            ${wsadmin}/lib/rs_aix42.AFS
 739 </PRE>
 740 <P><H3><A NAME="HDRWQ442" HREF="auagd002.htm#ToC_521">The LIBS Section</A></H3>
 741 <P>This section contains only one instruction, which indicates
 742 that <TT>LIBS</TT> is defined as the combination of <TT>MACHINE_LIBS</TT>
 743 and <TT>BASE_LIBS</TT>. Insert a blank line after the line to
 744 separate this section from the next.
 745 <PRE>   LIBS = ${MACHINE_LIBS} ${BASE_LIBS}
 746 </PRE>
 747 <P><H3><A NAME="HDRWQ443" HREF="auagd002.htm#ToC_522">The .SUFFIXES Section</A></H3>
 748 <P>This section lists the valid machine-type suffixes.
 749 This list includes system types currently supported for AFS. Unused
 750 suffixes are ignored.
 751 <PRE>   .SUFFIXES: .rs_aix42 \
 752               .alpha_dux40 \
 753               .proto \
 754               .sun4x_56 \
 755               .i386_linux22 \
 756               .hp_ux110
 757 </PRE>
 758 <P><H3><A NAME="HDRWQ444" HREF="auagd002.htm#ToC_523">The Makefile Instructions Section</A></H3>
 759 <P>The remainder of the <B>Makefile</B> file controls how
 760 the <B>package</B> program generates configuration files.
 761 <P>Study the following instructions; it is assumed that you are familiar
 762 with programming and <B>Makefile</B> concepts.
 763 <PRE>   #The following appear on a single line each in the actual file
 764    .proto.rs_aix42: ;  mpp -Dwsadmin=${wsadmin} -Dsys=rs_aix42
 765                            -Dname=$* $*.proto > $@
 766    .proto.alpha_dux40: ; mpp -Dwsadmin=${wsadmin} -Dsys=alpha_dux40
 767                            -Dname=$* $*.proto > $@
 768    .proto.sun4x_56:  ; mpp -Dwsadmin=${wsadmin} -Dsys=sun4x_56
 769                            -Dname=$* $*.proto > $@
 770    .proto.hp_ux110:  ; mpp -Dwsadmin=${wsadmin} -Dsys=hp_ux110
 771                            -Dname=$* $*.proto > $@
 772    all: ${CONFIG}
 773    ${CONFIG}: ${LIBS}
 774    system: install
 775    install: ${CONFIG}
 776            cp ${CONFIG} ${wsadmin}/etc
 777    clean:
 778            rm -f ${CONFIG} *.BAK *.CKP
 779 </PRE>
 780 <HR><H2><A NAME="HDRWQ445" HREF="auagd002.htm#ToC_524">Modifying the Makefile</A></H2>
 781 <A NAME="IDX7572"></A>
 782 <A NAME="IDX7573"></A>
 783 <A NAME="IDX7574"></A>
 784 <P>Modify the <B>package</B> <B>Makefile</B> files when you
 785 <UL>
 786 <P><LI>Add a new prototype file
 787 (<VAR>function</VAR><B>.proto</B>).
 788 <P><LI>Add a new system type.
 789 <P><LI>Add new library files.
 790 </UL>
 791 <P>The following sections provide brief examples of how to modify the
 792 <B>Makefile</B> file for these reasons.
 793 <P><H3><A NAME="Header_525" HREF="auagd002.htm#ToC_525">Adding a New Prototype File</A></H3>
 794 <P>When you create a new prototype file, add the file name and each system
 795 type for which it is to be built into the <TT>CONFIG</TT> section of the
 796 <B>Makefile</B> file.
 797 <P>For example, to add a <VAR>function</VAR><B>.proto</B> file for
 798 <B>alpha_dux40</B> and <B>hp_ux110</B>, add the following entries to
 799 the <TT>CONFIG</TT> section:
 800 <PRE>   CONFIG = \
 801    ...
 802            <VAR>function</VAR>.alpha_dux40 \
 803            <VAR>function</VAR>.hp_ux110 \
 804    ...
 805 </PRE>
 806 <P>If you have added new library files for this prototype function, add those
 807 to the <TT>MACHINE_LIBS</TT> section.
 808 <P><H3><A NAME="Header_526" HREF="auagd002.htm#ToC_526">Adding a New System Type</A></H3>
 809 <P>For each prototype file that you want to build for the new system type,
 810 add an entry to the <TT>CONFIG</TT> section. Also add any new
 811 libraries to the <TT>MACHINE_LIBS</TT> section, and the new system type to
 812 the <TT>.SUFFIXES</TT> section.
 813 <P>The following example shows the modifications appropriate when building the
 814 <B>staff</B> and <B>minimal</B> prototype files for this new system
 815 type.
 816 <PRE>   CONFIG = \
 817    ...
 818            staff.<VAR>sysname</VAR> \
 819            minimal.<VAR>sysname</VAR> \
 820    ...
 821 </PRE>
 822 <P>If you have created corresponding library files for this new machine type,
 823 add them to the <TT>MACHINE_LIBS</TT> section.
 824 <PRE>   MACHINE_LIBS = \
 825    ...
 826            ${wsadmin}/lib/<VAR>sysname</VAR>.generic \
 827            ${wsadmin}/lib/<VAR>sysname</VAR>.generic.dev \
 828            ${wsadmin}/lib/<VAR>sysname</VAR>.readonly \
 829            ${wsadmin}/lib/<VAR>sysname</VAR>.readwrite \
 830    ...
 831 </PRE>
 832 <P>Add the new system type to the <TT>SUFFIXES</TT> section.
 833 <PRE>   .SUFFIXES: ...\
 834             .<VAR>sysname</VAR> \
 835    ...
 836 </PRE>
 837 <P>Add a line to build the configuration files for this system in the section
 838 with the rest of the commands to build configuration files:
 839 <PRE>   .proto.<VAR>sysname</VAR>: ; mpp -Dwsadmin=${wsadmin} \
 840    -Dsys=<VAR>sysname</VAR>  -Dname=$* $*.proto > $
 841 </PRE>
 842 <P><H3><A NAME="Header_527" HREF="auagd002.htm#ToC_527">Adding New Library Files</A></H3>
 843 <P>If you added a new library file for each system type,
 844 <VAR>sysname</VAR><B>.</B><VAR>library_file</VAR>, add these files to
 845 the MACHINE_LIBS section of the<B> Makefile</B>.
 846 <PRE>   MACHINE_LIBS = \
 847    ...
 848            ${wsadmin}/lib/rs_aix42.<VAR>library_file</VAR> \
 849    ...
 850            ${wsadmin}/lib/alpha_dux40.<VAR>library_file</VAR> \
 851    ...
 852            ${wsadmin}/lib/sun4x_56.<VAR>library_file</VAR> \
 853    ...
 854 </PRE>
 855 <P>If you added a new library file that is common to all system types,
 856 <I>library_file</I>, add this only to the <TT>BASE_LIBS</TT>
 857 section:
 858 <PRE>   BASE_LIBS = \
 859    ...
 860            ${wsadmin}/lib/<VAR>library_file</VAR> \
 861    ...
 862 </PRE>
 863 <HR><H2><A NAME="HDRWQ446" HREF="auagd002.htm#ToC_528">Compiling Prototype Files</A></H2>
 864 <A NAME="IDX7575"></A>
 865 <A NAME="IDX7576"></A>
 866 <P>The <B>package</B> program generates configuration files and installs
 867 them in the <B>etc</B> and <B>src</B> subdirectories of the directory
 868 designated as <B>wsadmin=</B> on the <B>make</B> command line.
 869 Recompile whenever you modify a prototype or library file.
 870 <P><H3><A NAME="Header_529" HREF="auagd002.htm#ToC_529">To compile prototype files</A></H3>
 871 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">These instructions assume that you store your <B>package</B>-related
 872 files in the <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin</B>
 873 directory. If you use a different directory, substitute its name for
 874 <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin</B>.
 875 </TD></TR></TABLE>
 876 <OL TYPE=1>
 877 <P><LI>Verify that you have all privileges in the
 878 <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin</B> directory and in its
 879 <B>src</B>, <B>lib</B> and <B>etc</B> subdirectories. If
 880 necessary, issue the <B>fs</B> <B>listacl</B> command.
 881 <PRE>   % <B>fs listacl</B> [<VAR>dir/file&nbsp;path</VAR>]
 882 </PRE>
 883 <P><LI>Change to the <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin/src</B>
 884 subdirectory.
 885 <PRE>   % <B>cd /afs/</B><VAR>cellname</VAR><B>/wsadmin/src</B>
 886 </PRE>
 887 <P><LI>Create a backup copy of the <B>Makefile</B> file included in the AFS
 888 distribution.
 889 <PRE>   % <B>cp  Makefile Makefile.example</B>
 890 </PRE>
 891 <P><LI>Modify the <TT>CONFIG</TT>, <TT>BASE_LIBS</TT> and
 892 <TT>MACHINE_LIBS</TT> sections of the <B>Makefile</B> file, as described
 893 in <A HREF="#HDRWQ439">The CONFIG Section</A>, <A HREF="#HDRWQ440">The BASE_LIBS Section</A>, and <A HREF="#HDRWQ441">The MACHINE_LIBS Section</A>.
 894 <P><LI>Compile the prototype files using the <B>make</B> command.
 895 <P>Use the <B>wsadmin=</B> argument to specify the <B>package</B>
 896 directory. This becomes the value of the <TT>${wsadmin}</TT> variable
 897 in the prototype and the library files.
 898 <P>The <B>package</B> program generates configuration files and installs
 899 them in the <B>etc</B> and <B>src</B> subdirectories of the directory
 900 designated as <B>wsadmin=</B>.
 901 <PRE>   % <B>make system wsadmin=/afs/</B><VAR>cellname</VAR><B>/wsadmin</B>
 902 </PRE>
 903 </OL>
 904 <HR><H2><A NAME="HDRWQ447" HREF="auagd002.htm#ToC_530">Modifying Client Machines</A></H2>
 905 <A NAME="IDX7577"></A>
 906 <A NAME="IDX7578"></A>
 907 <A NAME="IDX7579"></A>
 908 <A NAME="IDX7580"></A>
 909 <P>To prepare a client to run the <B>package</B> program automatically,
 910 perform the following steps. The instructions are generic because they
 911 do not refer to system-specific configuration files. If desired, you
 912 can invoke the <B>package</B> program with specific arguments, as
 913 described in the <I>IBM AFS Administration Reference</I>.
 914 <OL TYPE=1>
 915 <P><LI>Specify the configuration file to use.
 916 <P>The <B>.package</B> file in the client machine's root (
 917 <B>/</B>) directory is redirected as an argument to the <B>package</B>
 918 command; the <B>.package</B> file specifies which
 919 configuration file the <B>package</B> program uses.
 920 <P><LI>Make the <B>package</B> binary available to the client, either by
 921 copying it to the local disk, or by creating a symbolic link to AFS.
 922 <UL>
 923 <P><LI>A symbolic link saves local disk space. However, when the file
 924 server machine that houses it is down, the <B>package</B> binary is
 925 inaccessible.
 926 <P><LI>Keeping the <B>package</B> binary on the local disk enables you to run
 927 the <B>package</B> program even if file server is down. However, a
 928 file server machine outage usually makes it difficult to run the
 929 <B>package</B> program because most configuration file instructions refer
 930 to files in AFS. A local copy of the <B>package</B> binary can be
 931 useful if the files referred to in instructions are in replicated
 932 volumes.
 933 </UL>
 934 <P><LI>Modify the client machine's initialization file to invoke the
 935 <B>package</B> program at reboot. The client machine reboots a
 936 second time if the <B>package</B> program updates any files marked with
 937 the <B>Q</B> update code.
 938 </OL>
 939 <P><H3><A NAME="Header_531" HREF="auagd002.htm#ToC_531">To prepare a client machine to run the package program</A></H3>
 940 <P>Repeat these instructions on every client that runs the
 941 <B>package</B> program.
 942 <P>These instructions assume that the <B>package</B> configuration files
 943 (created when the prototype files were compiled) reside in the
 944 <B>/afs/</B><VAR>cellname</VAR><B>/wsadmin/etc</B> directory .
 945 <OL TYPE=1>
 946 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
 947 already, by issuing the <B>su</B> command.
 948 <PRE>   % <B>su root</B>
 949    Password: <VAR>root_password</VAR>
 950 </PRE>
 951 <P><LI>Create the <B>.package</B> file in the root ( <B>/</B>)
 952 directory and specify the name of the prototype file to use. Do not
 953 include the system-type suffix (such as <B>.rs_aix42</B>); the
 954 <B>package</B> program automatically determines the correct machine
 955 type.
 956 <PRE>   # <B>echo "/afs/</B><VAR>cellname</VAR><B>/wsadmin/etc/</B><VAR>config_file</VAR><B>" >> /.package</B>
 957 </PRE>
 958 <P>For example, to configure a machine for a member of staff machine (assuming
 959 the proper prototype file had been defined and compiled for the system type),
 960 the appropriate command is:
 961 <PRE>   # <B>echo "/afs/</B><VAR>cellname</VAR><B>/wsadmin/etc/staff" >> /.package</B>
 962 </PRE>
 963 <P><LI>Make the <B>package</B> binary available on the local disk as
 964 <B>/etc/package</B>. Issue one of the following commands, depending
 965 on whether you want to create a file or create a symbolic link.
 966 <P>To store the <B>package</B> binary locally, enter the following
 967 command:
 968 <PRE>   # <B>cp /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/etc/package   /etc/package</B>
 969 </PRE>
 970 <P>To create a symbolic link, enter the following command:
 971 <PRE>   # <B>ln -s /afs/</B><VAR>cellname</VAR><B>/</B><VAR>sysname</VAR><B>/usr/afsws/etc/package   /etc/package</B>
 972 </PRE>
 973 <P><LI>Add the following lines to the appropriate initialization file, after the
 974 <B>afsd</B> command is invoked. If this is a file server machine,
 975 the <B>bosserver</B> command must follow the <B>package</B>
 976 command.
 977 <P>Using the <B>-v</B> and <B>-c</B> options is recommended.
 978 The <B>-v</B> flag produces a detailed trace, and the <B>-c</B> option
 979 appends the system type to the base name of the configuration file. See
 980 the <I>IBM AFS Administration Reference</I> for a description of other
 981 options.
 982 <TABLE><TR><TD ALIGN="LEFT" VALIGN="TOP"><B>Note:</B></TD><TD ALIGN="LEFT" VALIGN="TOP">Replace the <B>shutdown</B> command with a similar command if it is not
 983 appropriate for rebooting your machine.
 984 </TD></TR></TABLE>
 985 <PRE>   if [ -f /etc/package ]; then
 986            if [ -f /.package ]: then
 987                    /etc/package -v -c `cat /.package` >/dev/console
 988            else
 989                    /etc/package -v >/dev/console
 990    fi
 991    case $? in
 992    0)
 993            echo "Package completed successfully" >/dev/console 2>&amp;1
 994            date >/dev/console 2>&amp;1
 995            ;;
 996    4)
 997            echo "Rebooting to restart system" >/dev/console 2>&amp;1
 998            echo >/fastboot
 999            shutdown
1000            ;;
1001    *)
1002            echo "Update failed, continuing anyway" >/dev/console 2>&amp;1
1003            ;;
1004    esac
1005    fi
1006 </PRE>
1007 </OL>
1008 <HR><H2><A NAME="HDRWQ448" HREF="auagd002.htm#ToC_532">Running the package program</A></H2>
1009 <P>After you have created and compiled prototype files and
1010 modified client machines, you are ready to run the <B>package</B>
1011 program. It is probably most convenient to run the <B>package</B>
1012 program automatically at reboot by invoking it in the machine's AFS
1013 initialization file, but you can also issue the command at the command shell
1014 prompt.
1015 <P>The configuration file must be completely correct. If there are any
1016 syntax errors or incorrect values, the program exits without executing any
1017 instruction. To check the configuration file, issue the
1018 <B>package</B> command with the <B>-noaction</B> and <B>-debug</B>
1019 flags at the command shell prompt. They display a list of potential
1020 problems without actually executing instructions.
1021 <P>The <B>package</B> program follows these general rules. Complete
1022 explanations are in <A HREF="#HDRWQ429">Package Configuration File Instruction Syntax</A>.
1023 <UL>
1024 <P><LI>The <B>package</B> program does not delete any files from the disk
1025 unless the <B>R</B> update code was specified in the prototype
1026 file. If the <B>R</B> update code is associated with the parent
1027 directory, the <B>package</B> program removes anything from the local disk
1028 directory that is not specified in the configuration file.
1029 <P><LI>Local files are updated only if they are out of date. For each
1030 <B>F</B> instruction in the configuration file, the <B>package</B>
1031 program compares the time of the local file with the indicated source
1032 file. If the source file is newer than the local, the file is
1033 updated.
1034 <P><LI>When the initialization file is modified as recommended in <A HREF="#HDRWQ447">Modifying Client Machines</A>, the <B>package</B> program reboots the workstation
1035 automatically if any files marked with the <B>Q</B> update code are
1036 updated, and if the <B>package</B> program has been invoked from the
1037 initialization file. When a file marked with the <B>Q</B> update
1038 code is changed, the <B>package</B> program exits with status code 4,
1039 causing a reboot (as directed in the initialization file). Files that
1040 require a reboot before changes are recognized (such as the operating system
1041 kernel and <B>/usr/vice/etc/CellServDB</B> files) must be marked with a
1042 <B>Q</B> update code in the configuration file.
1043 <P><LI>The <B>package</B> program copies the configuration file it has just
1044 used to <B>/etc/package.</B><VAR>sysname</VAR>, where
1045 <VAR>sysname</VAR> reflects this machine's system type. The
1046 <B>package</B> command interpreter consults this file if you do not
1047 provide a configuration file name. To be sure that it configures the
1048 local disk as you wish, review its contents.
1049 </UL>
1050 <P><H3><A NAME="Header_533" HREF="auagd002.htm#ToC_533">To invoke the package program by rebooting</A></H3>
1051 <OL TYPE=1>
1052 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1053 already, by issuing the <B>su</B> command.
1054 <PRE>   % <B>su root</B>
1055    Password: <VAR>root_password</VAR>
1056 </PRE>
1057 <P><LI><B>(Recommended)</B> Verify the following:
1058 <UL>
1059 <P><LI>The <B>/.package</B> file identifies the desired configuration
1060 file
1061 <P><LI>The <B>package</B> binary is available as <B>/etc/package</B>
1062 <P><LI>The initialization file is properly modified to invoke the
1063 <B>package</B> program automatically
1064 </UL>
1065 <P><LI>Reboot the machine, using the appropriate command.
1066 <PRE>   # <B>shutdown</B>
1067 </PRE>
1068 </OL>
1069 <A NAME="IDX7581"></A>
1070 <A NAME="IDX7582"></A>
1071 <P><H3><A NAME="Header_534" HREF="auagd002.htm#ToC_534">To invoke the package program directly (without rebooting)</A></H3>
1072 <OL TYPE=1>
1073 <P><LI>Become the local superuser <B>root</B> on the machine, if you are not
1074 already, by issuing the <B>su</B> command.
1075 <PRE>   % <B>su root</B>
1076    Password: <VAR>root_password</VAR>
1077 </PRE>
1078 <P><LI>Verify the following:
1079 <UL>
1080 <P><LI>The <B>/.package</B> file identifies the desired configuration
1081 file
1082 <P><LI>The <B>package</B> binary is available as <B>/etc/package</B>
1083 <P><LI>The initialization file is properly modified to invoke the
1084 <B>package</B> program automatically
1085 </UL>
1086 <P><LI>Issue the <B>package</B> command.
1087 <PRE>   # <B>package</B>  [<B>initcmd</B>]  [<B>-config</B> &lt;<VAR>base&nbsp;name&nbsp;of&nbsp;configuration&nbsp;file</VAR>>]  \
1088     [<B>-fullconfig</B> &lt;<VAR>full&nbsp;name&nbsp;of&nbsp;configuration&nbsp;file,&nbsp;or&nbsp;stdin&nbsp;for&nbsp;standard&nbsp;input</VAR>>]  \
1089     [<B>-overwrite</B>]  [<B>-noaction</B>]  [<B>-verbose</B>]  [<B>-silent</B>] [<B>-rebootfiles</B>]
1090 </PRE>
1091 <P>where
1092 <DL>
1093 <P><DT><B>-config
1094 </B><DD>Specifies the full pathname of the configuration file to use, ending in
1095 the file's base name, which omits the suffix that indicates the machine
1096 type. The <B>package</B> program knows how to determine a
1097 machine's type, and automatically selects the appropriate version of the
1098 base file name. An example of the proper value for this argument is
1099 <B>staff</B> rather than <B>staff.rs_aix42</B>. You can
1100 also have the <B>package</B> program refer to <B>/.package</B>
1101 to learn the configuration file name by providing the following value:
1102 <P><B>`cat /.package`</B>
1103 <P>Use either this argument or the <B>-fullconfig</B> argument.
1104 <P><DT><B>-fullconfig
1105 </B><DD>Specifies the full name of the configuration file to use, complete with
1106 the machine-type extension. Examples are
1107 <B>staff.rs_aix42</B> and <B>minimal.hp_ux110</B>
1108 files.
1109 <P>Another possibility is the string <B>stdin</B>, which indicates that
1110 the issuer is providing configuration information via the standard input
1111 stream, either as a piped file or by typing the configuration file at the
1112 keyboard. Press &lt;<B>Ctrl-d</B>> to conclude the input.
1113 <P>Use either this argument or the <B>-config</B> argument.
1114 <P><DT><B>-overwrite
1115 </B><DD>Overwrite elements on the local disk with the source version indicated in
1116 the configuration file, even if the first (owner) <B>w</B>
1117 (<B>write</B>) mode bit is turned off on the local disk copy of the
1118 file. Files protected by the <B>I</B> update code are not
1119 overwritten; see the definition for the <B>F</B> instruction.
1120 <P><DT><B>-noaction
1121 </B><DD>Displays on the standard output stream a trace of potential problems in
1122 running the command, rather than actually running it. If the
1123 <B>-verbose</B> flag is added, the trace also notes the actions the
1124 <B>package</B> program attempts.
1125 <P><DT><B>-silent
1126 </B><DD>Explicitly invokes the default level of tracing, which includes only a
1127 list of problems encountered while executing the command.
1128 <P><DT><B>-verbose
1129 </B><DD>Produces a detailed trace of the program's actions on the standard
1130 output stream. The trace records on the transfer and ownership/mode bit
1131 setting of each element in the configuration file.
1132 <P><DT><B>-rebootfiles
1133 </B><DD>Prevents the overwrite of any element marked with the <B>Q</B>
1134 update-mode code in the configuration file. This effectively prevents
1135 the machine from rebooting automatically again when the <B>package</B>
1136 program is invoked from an initialization file.
1137 </DL>
1138 <P><LI>If you think files marked with the <B>Q</B> update code were updated,
1139 reboot the machine. This reboot does not occur automatically.
1140 </OL>
1141 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auagd002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auagd015.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auagd017.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auagd026.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
1142 <!-- Begin Footer Records  ========================================== -->
1143 <P><HR><B>
1144 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
1145 </B>
1146 <!-- End Footer Records  ============================================ -->
1147 <A NAME="Bot_Of_Page"></A>
1148 </BODY></HTML>