doc/xml/AdminGuide/auagd016.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter id="HDRWQ419">
   3   <title>Configuring Client Machines with the package Program</title>
   4
   5   <para>The <emphasis role="bold">package</emphasis> program automates many aspects of the client configuration process. With the
   6   <emphasis role="bold">package</emphasis> program, you can easily configure the local disk of numerous clients by defining global
   7   configuration files. <indexterm>
   8       <primary>configuring</primary>
   9
  10       <secondary>local disk of client with package</secondary>
  11     </indexterm> <indexterm>
  12       <primary>client</primary>
  13
  14       <secondary>configuring local disk with package</secondary>
  15     </indexterm> <indexterm>
  16       <primary>disk</primary>
  17
  18       <secondary>local</secondary>
  19
  20       <see>local disk</see>
  21     </indexterm> <indexterm>
  22       <primary>local disk</primary>
  23
  24       <secondary>configuring on client, using package</secondary>
  25     </indexterm></para>
  26
  27   <sect1 id="HDRWQ420">
  28     <title>Summary of Instructions</title>
  29
  30     <para>This chapter explains how to perform the following tasks by using the indicated commands or instructions in a prototype
  31     file:</para>
  32
  33     <informaltable frame="none">
  34       <tgroup cols="2">
  35         <colspec colwidth="37*" />
  36
  37         <colspec colwidth="63*" />
  38
  39         <tbody>
  40           <row>
  41             <entry>Configure a client machine's local disk</entry>
  42
  43             <entry><emphasis role="bold">package</emphasis></entry>
  44           </row>
  45
  46           <row>
  47             <entry>Define directory</entry>
  48
  49             <entry><emphasis role="bold">D</emphasis> [update_code] directory owner group mode_bits</entry>
  50           </row>
  51
  52           <row>
  53             <entry>Define file</entry>
  54
  55             <entry><emphasis role="bold">F</emphasis> [update_code] file source_file [owner group mode_bits]</entry>
  56           </row>
  57
  58           <row>
  59             <entry>Define symbolic link</entry>
  60
  61             <entry><emphasis role="bold">L</emphasis> [update_code] link actual_file [owner group mode_bits]</entry>
  62           </row>
  63
  64           <row>
  65             <entry>Define block special device</entry>
  66
  67             <entry><emphasis role="bold">B</emphasis> device_name major_device_number minor_device_number owner group
  68             mode_bits</entry>
  69           </row>
  70
  71           <row>
  72             <entry>Define character special device</entry>
  73
  74             <entry><emphasis role="bold">C</emphasis> device_name major_device_number minor_device_number owner group
  75             mode_bits</entry>
  76           </row>
  77
  78           <row>
  79             <entry>Define socket</entry>
  80
  81             <entry><emphasis role="bold">S</emphasis> socket_name [owner group mode_bits]</entry>
  82           </row>
  83         </tbody>
  84       </tgroup>
  85     </informaltable>
  86   </sect1>
  87
  88   <sect1 id="HDRWQ422">
  89     <title>Using the package Program</title>
  90
  91     <indexterm>
  92       <primary>package</primary>
  93
  94       <secondary>prototype file</secondary>
  95     </indexterm>
  96
  97     <indexterm>
  98       <primary>prototype files in package</primary>
  99
 100       <secondary>about</secondary>
 101     </indexterm>
 102
 103     <para>The <emphasis role="bold">package</emphasis> program uses system-independent <emphasis>prototype files</emphasis> to
 104     define a standard disk configuration; a prototype file indicates which files reside on the local client disk, which files are
 105     links into AFS, etc. The prototype files are then compiled into <emphasis>configuration files</emphasis> for each different
 106     system type.</para>
 107
 108     <para>Not all client machines have the same configuration. If desired, you can create different prototype files for different
 109     client functions (print server, regular client, etc.).</para>
 110
 111     <para>The <emphasis role="bold">package</emphasis> program compares the contents of a local client disk with the configuration
 112     file. If there are any differences, the <emphasis role="bold">package</emphasis> program makes the necessary updates to the
 113     local disk by copying the files from AFS onto the disk. The <emphasis role="bold">package</emphasis> program can also be
 114     configured to delete files that are not part of the system configuration or automatically reboot the client when certain files
 115     (such as the <emphasis role="bold">dkload</emphasis> file) have been updated.</para>
 116
 117     <para>The <emphasis role="bold">package</emphasis> program does require that you take some time to prepare the prototype files,
 118     but it provides the following benefits: <itemizedlist>
 119         <listitem>
 120           <para>You no longer need to configure each machine individually; the prototype configuration file applies to all
 121           machines.</para>
 122         </listitem>
 123
 124         <listitem>
 125           <para>You can change the configuration of machines simply by changing the prototype file and rebooting the clients.</para>
 126         </listitem>
 127
 128         <listitem>
 129           <para>Disk organization is uniform across a set of machines.</para>
 130         </listitem>
 131
 132         <listitem>
 133           <para>The configuration files serve as a record of files on the disk and symbolic links into AFS.</para>
 134         </listitem>
 135       </itemizedlist></para>
 136
 137     <sect2 id="Header_494">
 138       <title>Using Package on File Server Machines</title>
 139
 140       <para>While the <emphasis role="bold">package</emphasis> program was designed for use on client machines, it can also be used
 141       to configure a file server machine's disk. However, if any of the files referred to in a configuration file reside in volumes
 142       on the file server, the <emphasis role="bold">package</emphasis> program cannot access the volumes during reboot (and until
 143       the File Server process and Volume Server process start up again).</para>
 144
 145       <para>Since the <emphasis role="bold">package</emphasis> program aborts when it cannot access a file, you need to eliminate
 146       references to files in AFS that reside in volumes on the file server machine. Because of these constraints, the remainder of
 147       this chapter assumes the <emphasis role="bold">package</emphasis> program is being used for client configurations.</para>
 148     </sect2>
 149   </sect1>
 150
 151   <sect1 id="HDRWQ423">
 152     <title>Package Overview</title>
 153
 154     <para>There are three main steps to follow before running the <emphasis role="bold">package</emphasis> program: <orderedlist>
 155         <listitem>
 156           <para>Preparing function-specific <emphasis>prototype files</emphasis> (and any included <emphasis>library
 157           files</emphasis>).</para>
 158         </listitem>
 159
 160         <listitem>
 161           <para>Modifying the <emphasis role="bold">package</emphasis> <emphasis role="bold">Makefile</emphasis> and compiling
 162           prototype files into system-specific <emphasis>configuration files</emphasis>.</para>
 163         </listitem>
 164
 165         <listitem>
 166           <para>Modifying client machines to run the appropriate <emphasis role="bold">package</emphasis> configuration file
 167           automatically.</para>
 168         </listitem>
 169       </orderedlist></para>
 170
 171     <para>The following sections summarize these steps.</para>
 172
 173     <sect2 id="Header_496">
 174       <title>Preparing Prototype Files</title>
 175
 176       <indexterm>
 177         <primary>package</primary>
 178
 179         <secondary>preparing prototype files</secondary>
 180       </indexterm>
 181
 182       <indexterm>
 183         <primary>prototype files in package</primary>
 184
 185         <secondary>preparing</secondary>
 186       </indexterm>
 187
 188       <para>Begin by listing the different functions or roles client machines perform and the local disk configurations that support
 189       those functions. Example roles include a standard client that provides AFS access, a print server that drives a printer, and a
 190       backup machine on which you issue commands from the <emphasis role="bold">backup</emphasis> suite. Create a different
 191       <emphasis>prototype file</emphasis> for each role.</para>
 192
 193       <para>A prototype file defines the disk configuration that supports a specific role. Usually, prototype files are
 194       function-specific, but system independent; system-specific values can be defined using variables and library files. Then, when
 195       you modify a variable or library file, the change gets propagated to all appropriate clients when the <emphasis
 196       role="bold">package</emphasis> program is invoked.</para>
 197
 198       <para>Methods for building flexible prototype files that are easy to maintain are presented in <link
 199       linkend="HDRWQ427">Example Prototype and Library Files</link>.</para>
 200     </sect2>
 201
 202     <sect2 id="HDRWQ424">
 203       <title>Compiling Prototype Files</title>
 204
 205       <indexterm>
 206         <primary>package</primary>
 207
 208         <secondary>compiling prototype files</secondary>
 209       </indexterm>
 210
 211       <indexterm>
 212         <primary>package</primary>
 213
 214         <secondary>configuration files</secondary>
 215       </indexterm>
 216
 217       <indexterm>
 218         <primary>configuration files</primary>
 219
 220         <secondary>package program</secondary>
 221       </indexterm>
 222
 223       <para>Prototype files are usually system-independent, but can include <computeroutput>ifdef</computeroutput> statements to
 224       satisfy the needs of different system types. The prototype files are compiled to generate operating-system specific versions.
 225       During compilation, the <emphasis role="bold">package</emphasis> program selects the definitions suitable for each system type
 226       and replaces any variables with actual values. These compiled, machine-specific files are called <emphasis>configuration
 227       files</emphasis>.</para>
 228
 229       <para>Prototype files are compiled using a standard-type <emphasis role="bold">Makefile</emphasis> file, as described in <link
 230       linkend="HDRWQ438">The Package Makefile File</link>.</para>
 231     </sect2>
 232
 233     <sect2 id="Header_498">
 234       <title>Preparing Clients</title>
 235
 236       <para>Once system-specific configuration files exist, the <emphasis role="bold">package</emphasis> program is ready to run on
 237       the clients. You must first make the <emphasis role="bold">package</emphasis> binary available and specify the correct
 238       configuration file.</para>
 239
 240       <para>Modify the clients as described below: <orderedlist>
 241           <listitem>
 242             <para>Create a <emphasis role="bold">.package</emphasis> file in the root ( <emphasis role="bold">/</emphasis> )
 243             directory of each client's local disk that defines the default configuration file.</para>
 244           </listitem>
 245
 246           <listitem>
 247             <para>Make the <emphasis role="bold">package</emphasis> binary (<emphasis role="bold">/etc/package</emphasis>) available
 248             on the local disk.</para>
 249           </listitem>
 250
 251           <listitem>
 252             <para>Modify the machine's initialization file (<emphasis role="bold">/etc/rc</emphasis> or equivalent) to include a
 253             call to the <emphasis role="bold">package</emphasis> program.</para>
 254           </listitem>
 255         </orderedlist></para>
 256
 257       <para>These steps are discussed more completely in <link linkend="HDRWQ447">Modifying Client Machines</link>.</para>
 258     </sect2>
 259   </sect1>
 260
 261   <sect1 id="HDRWQ425">
 262     <title>The package Directory Structure</title>
 263
 264     <indexterm>
 265       <primary>package</primary>
 266
 267       <secondary>directory structure</secondary>
 268     </indexterm>
 269
 270     <para>This section assumes that the <emphasis role="bold">package</emphasis>-related files have been installed in three
 271     subdirectories of the <emphasis role="bold">/afs/</emphasis>cellname/<emphasis role="bold">wsadmin</emphasis> directory:
 272     <emphasis role="bold">src</emphasis>, <emphasis role="bold">lib</emphasis> and <emphasis role="bold">etc</emphasis>, as
 273     recommended in the <emphasis>OpenAFS Quick Beginnings</emphasis>.</para>
 274
 275     <para>These directories contain several sample prototype, library, and configuration files, which can help to clarify how the
 276     <emphasis role="bold">package</emphasis> program works. However, they are not necessarily suitable for use in your cell; you
 277     must modify them for your needs.</para>
 278
 279     <sect2 id="HDRWQ426">
 280       <title>The src directory</title>
 281
 282       <para>The <emphasis role="bold">src</emphasis> directory contains some sample prototype files (used to build the configuration
 283       files), the <emphasis role="bold">Makefile</emphasis> file used to build them, and the resulting compiled configuration
 284       files.</para>
 285
 286       <para>Prototype files have names of the form function.<emphasis role="bold">proto</emphasis>. For example, a <emphasis
 287       role="bold">minimal.proto</emphasis> file defines the minimum set of library files need to run AFS and a<emphasis
 288       role="bold">staff.dkload.proto</emphasis> file defines a client configuration that uses the a dynamic kernel loading program.
 289       Prototype files can also contain definitions for system administrative files, such as a <emphasis
 290       role="bold">hosts.equiv</emphasis> file.</para>
 291
 292       <para>The <emphasis role="bold">Makefile</emphasis> file is used to compile the system-independent prototype files into
 293       system-specific configuration files. To learn how to modify this file for use in your cell, see <link linkend="HDRWQ438">The
 294       Package Makefile File</link>.</para>
 295
 296       <para>Configuration files are the compiled version of the prototype files and are named function<emphasis
 297       role="bold">.</emphasis>sysname. Configuration files also appear in the <emphasis role="bold">etc</emphasis> subdirectory,
 298       which the <emphasis role="bold">package</emphasis> program accesses when configuring disks.</para>
 299     </sect2>
 300
 301     <sect2 id="Header_501">
 302       <title>The lib directory</title>
 303
 304       <para>The <emphasis role="bold">lib</emphasis> directory contains many of the example library files referred to in prototype
 305       files. For example, the <emphasis role="bold">base.generic</emphasis> file is a system-independent file which includes a
 306       definition of the cell name, system options, and variables; these are used to set the owner, group, and mode_bits fields in
 307       the file and the symbolic link definitions.</para>
 308     </sect2>
 309
 310     <sect2 id="Header_502">
 311       <title>The etc directory</title>
 312
 313       <para>The <emphasis role="bold">etc</emphasis> directory contains the system-specific configuration files built from the
 314       prototype files in the <emphasis role="bold">src</emphasis> subdirectory. The <emphasis role="bold">package</emphasis> program
 315       uses the configuration files in the <emphasis role="bold">etc</emphasis> directory to configure disks.</para>
 316
 317       <para>Some of the example files include <emphasis role="bold">minimal</emphasis> and <emphasis role="bold">staff</emphasis>
 318       prototype files compiled for different system types.</para>
 319     </sect2>
 320   </sect1>
 321
 322   <sect1 id="HDRWQ427">
 323     <title>Example Prototype and Library Files</title>
 324
 325     <indexterm>
 326       <primary>package</primary>
 327
 328       <secondary>example prototype files</secondary>
 329     </indexterm>
 330
 331     <indexterm>
 332       <primary>prototype files in package</primary>
 333
 334       <secondary>examples</secondary>
 335     </indexterm>
 336
 337     <para>A prototype file is a template that defines the configuration of a client's local disk. Prototype files are usually
 338     function-specific (for example, a backup machine, print server, etc.) but system-independent. Prototype files support the use of
 339     <computeroutput>ifdef</computeroutput> statements and variables, so you can include system-specific definitions. The actual
 340     system-specific configuration file is generated when the prototype file is compiled.</para>
 341
 342     <para>The components defined in a prototype file can include the directories, files, symbolic links, block special devices,
 343     character special devices and sockets that need to reside on a client's local disk in order for it to perform a specific role,
 344     such as a print server or backup machine. Thus, we recommend that you construct a unique prototype file for each different
 345     client function.</para>
 346
 347     <para>To make the <emphasis role="bold">package</emphasis> program more effective and easy to maintain, create prototype files
 348     that are modular and generic, instead of specific, by using library files and variables: <indexterm>
 349         <primary>library files in package</primary>
 350       </indexterm> <indexterm>
 351         <primary>package</primary>
 352
 353         <secondary>library files</secondary>
 354       </indexterm> <itemizedlist>
 355         <listitem>
 356           <para>By creating general-purpose library files, you can include the same library file in many prototype files. Thus, you
 357           can make global configuration changes by modifying a single library file; you do not need to modify each prototype
 358           file.</para>
 359         </listitem>
 360
 361         <listitem>
 362           <para>Variables enable you to change definitions simply by changing the variable's value.</para>
 363         </listitem>
 364       </itemizedlist></para>
 365
 366     <sect2 id="HDRWQ428">
 367       <title>An Example Prototype File</title>
 368
 369       <indexterm>
 370         <primary>examples</primary>
 371
 372         <secondary>prototype files for package</secondary>
 373       </indexterm>
 374
 375       <para>The following is part of an example prototype file that contains the minimum definitions necessary to run AFS. A similar
 376       file called <emphasis role="bold">minimal.proto</emphasis> can reside in your <emphasis role="bold">src</emphasis>
 377       subdirectory. As recommended, this prototype file references library files and does not include actual definitions.</para>
 378
 379       <programlisting>
 380             .
 381             .
 382    # Package prototype for a minimal configuration.
 383    # Base components
 384    %include ${wsadmin}/lib/base.generic
 385    # Machine-specific components
 386    %ifdef rs_aix42
 387    %include ${wsadmin}/lib/rs_aix42.readonly
 388    %include ${wsadmin}/lib/rs_aix42.AFS
 389    %endif rs_aix42
 390    %ifdef alpha_dux40
 391    %include ${wsadmin}/lib/alpha_dux40.readonly
 392    %include ${wsadmin}/lib/alpha_dux40.AFS
 393    %endif alpha_dux40
 394    %ifdef sun4x_56
 395    %include ${wsadmin}/lib/sun4x_56.readonly
 396    %include ${wsadmin}/lib/sun4x_56.AFS
 397    %endif sun4x_56
 398             .
 399             .
 400 </programlisting>
 401
 402       <para>In the previous example, the first uncommented line includes the <emphasis role="bold">/lib/base.generic</emphasis>
 403       library file. This library file can contain definitions appropriate for many prototype files; the <emphasis
 404       role="bold">base.generic</emphasis> library file can also be included in other prototype files, like a <emphasis
 405       role="bold">staff.proto</emphasis> or <emphasis role="bold">backup.proto</emphasis> file. An example library file appears in
 406       the following section.</para>
 407
 408       <para>Note that system-specific definitions are permitted through the use of <computeroutput>ifdef</computeroutput> statements
 409       and variables (for example, <computeroutput>${wsadmin}</computeroutput> is used to specify pathnames). Thus, the same
 410       prototype file can be used to configure a machine running AIX 4.2 or Solaris 2.6, even though they require different files,
 411       directories, symbolic links and devices.</para>
 412
 413       <para>In the next uncommented lines of this example, the administrator has constructed different library files for different
 414       system types. Each of these is compiled into unique configuration files. For instance, the following lines in this prototype
 415       file tell the <emphasis role="bold">package</emphasis> program to use the library files <emphasis
 416       role="bold">lib/rs_aix42.readonly</emphasis> and <emphasis role="bold">lib/rs_aix42.AFS</emphasis> for the configuration file
 417       when the value rs_aix42 has been declared. (The system-type definition is declared in the <emphasis
 418       role="bold">Makefile</emphasis>; see <link linkend="HDRWQ438">The Package Makefile File</link>.)</para>
 419
 420       <programlisting>
 421    %ifdef rs_aix42
 422    %include ${wsadmin}/lib/rs_aix42.readonly
 423    %include ${wsadmin}/lib/rs_aix42.AFS
 424    %endif rs_aix42
 425 </programlisting>
 426
 427       <para>Similarly, the following lines tell the <emphasis role="bold">package</emphasis> program to use the library files
 428       <emphasis role="bold">lib/sun4x_56.readonly</emphasis> and <emphasis role="bold">lib/sun4x_56.AFS</emphasis> when the value
 429       sun4x_56 has been declared.</para>
 430
 431       <programlisting>
 432    %ifdef sun4x_56
 433    %include ${wsadmin}/lib/sun4x_56.readonly
 434    %include ${wsadmin}/lib/sun4x_56.AFS
 435    %endif sun4x_56
 436 </programlisting>
 437     </sect2>
 438
 439     <sect2 id="Header_505">
 440       <title>Example Library File</title>
 441
 442       <indexterm>
 443         <primary>package</primary>
 444
 445         <secondary>example library files</secondary>
 446       </indexterm>
 447
 448       <indexterm>
 449         <primary>library files in package</primary>
 450
 451         <secondary>examples</secondary>
 452       </indexterm>
 453
 454       <indexterm>
 455         <primary>package</primary>
 456
 457         <secondary>preparing prototype files</secondary>
 458       </indexterm>
 459
 460       <indexterm>
 461         <primary>examples</primary>
 462
 463         <secondary>library files for package</secondary>
 464       </indexterm>
 465
 466       <para>The following is part of an example library file for basic configuration definitions. A similar file, called <emphasis
 467       role="bold">base.generic</emphasis>, can reside in your <emphasis role="bold">lib</emphasis> subdirectory. Note that
 468       configurations are defined using standard <computeroutput>ifdef</computeroutput> statements.</para>
 469
 470       <programlisting>
 471             .
 472             .
 473    #
 474    # Base package definitions.
 475    #
 476    %ifndef      cell
 477    %define      cell    example.com
 478    %endif       cell
 479    %ifndef      sys
 480    %include /etc/package.sys
 481    %endif       sys
 482    %define      ${name}         ${name}
 483    %define      ${cpu}          ${cpu}
 484    %define      ${sys}          ${sys}
 485    %define      ${dept}         ${dept}
 486    %define      ${hostname}     ${hostname}
 487    %ifdef       rs_aix42
 488    %    define  AIX
 489    %    define  rootlinks
 490    %ifndef      noafsd
 491    %    define  afsd
 492    %endif       noafsd
 493    %endif       rs_aix42
 494             .
 495             .
 496    #
 497    # Some definitions to handle common combinations of owner, group,
 498    # and protection fields.
 499    #
 500    %define      rzmode          root wheel 600
 501    %define      usermode        root wheel 666
 502    %define      systemmode      root wheel 644
 503    %define      diskmode        root wheel 644
 504    %define      ptymode         root wheel 666
 505    %define      ttymode         root wheel 666
 506             .
 507             .
 508    %define aix_rootbin     root bin
 509    %define aix_rootprintq  root printq
 510    %define aix_rootstaff   root staff
 511    %define aix_rootsys     root system
 512    %define aix_binbin      bin bin
 513    %define aix_binmail     bin mail
 514    %define aix_binsys      bin system
 515    %define aix_addsys      adduser system
 516    %define aix_romode      444
 517    %define aix_loginmode   544
 518    %define aix_usermode    666
 519    %define aix_systemmode  644
 520    %define aix_textmode    644
 521    %define aix_rwmode1     660
 522    %define aix_allrugw     664
 523 </programlisting>
 524
 525       <para>The following example library file uses <emphasis role="bold">package</emphasis>-specific syntax to define files,
 526       directories, sockets, etc. Each line, called a <emphasis>configuration file instruction</emphasis>, defines a specific
 527       component of disk configuration. The proper syntax for these instructions is briefly described in <link
 528       linkend="HDRWQ429">Package Configuration File Instruction Syntax</link>; see the reference page for the <emphasis
 529       role="bold">package</emphasis> configuration file in the <emphasis>OpenAFS Administration Reference</emphasis> for detailed
 530       descriptions.</para>
 531
 532       <para>In this example, the library file contains instructions specific to the configuration of an <emphasis
 533       role="bold">rs_aix42</emphasis> machine. You can have similar library files in your <emphasis role="bold">lib</emphasis>
 534       subdirectory.</para>
 535
 536       <programlisting>
 537             .
 538             .
 539    #
 540    # Generic configuration for an AFS rs_aix42 machine.
 541    #
 542    D    /                                       ${treemode}
 543    D    /afs
 544    FAQ  /unix          ${machine}/unix.std      ${binmode}
 545    LA   /unix.std       /unix
 546    D    /bin                                    ${treemode}
 547    F    /bin/as         ${machine}              ${binmode}
 548    F    /bin/ld         ${machine}              ${binmode}
 549    F    /bin/nm         ${machine}              ${binmode}
 550    FO   /bin/login      ${afstest}              ${suidmode}
 551             .
 552             .
 553    FAQ  /usr/vice/etc/ThisCell  ${common}/etc/ThisCell ${textmode}
 554    FQ   /usr/vice/etc/afsd      ${afstest}/root.client ${binmode}
 555    FA   /usr/vice/etc/bos       ${afstest}/bin/bos     ${binmode}
 556    FA   /usr/vice/etc/fs        ${afstest}/bin/fs      ${binmode}
 557 </programlisting>
 558     </sect2>
 559   </sect1>
 560
 561   <sect1 id="HDRWQ429">
 562     <title>Package Configuration File Instruction Syntax</title>
 563
 564     <indexterm>
 565       <primary>package</primary>
 566
 567       <secondary>configuration file instructions</secondary>
 568     </indexterm>
 569
 570     <indexterm>
 571       <primary>configuration file</primary>
 572
 573       <secondary>instructions for package program</secondary>
 574     </indexterm>
 575
 576     <para>Within a library file, configuration file instructions are used to define the specific disk configuration. Each
 577     instruction can be used to define a file, directory, socket, or device on the client machine. The syntax for each valid
 578     instruction type is described briefly here; detailed descriptions of the fields appear in the <emphasis>OpenAFS Command
 579     Reference Manual</emphasis>. <itemizedlist>
 580         <listitem>
 581           <para><emphasis role="bold">D</emphasis> defines a directory</para>
 582         </listitem>
 583
 584         <listitem>
 585           <para><emphasis role="bold">F</emphasis> defines a file</para>
 586         </listitem>
 587
 588         <listitem>
 589           <para><emphasis role="bold">L</emphasis> defines a link</para>
 590         </listitem>
 591
 592         <listitem>
 593           <para><emphasis role="bold">B</emphasis> defines a block special device</para>
 594         </listitem>
 595
 596         <listitem>
 597           <para><emphasis role="bold">C</emphasis> defines a character special device</para>
 598         </listitem>
 599
 600         <listitem>
 601           <para><emphasis role="bold">S</emphasis> defines a socket</para>
 602         </listitem>
 603       </itemizedlist></para>
 604
 605     <note>
 606       <para>Each configuration instruction must appear on a single, unbroken line. Instructions sometimes appear here on multiple
 607       lines only for legibility.</para>
 608
 609       <para>The configuration file must be completely correct. If there are any syntax errors or incorrect values, the <emphasis
 610       role="bold">package</emphasis> command interpreter exits without executing any instruction.</para>
 611     </note>
 612
 613     <sect2 id="HDRWQ430">
 614       <title>Local Files versus Symbolic Links</title>
 615
 616       <para>You can take advantage of the AFS by keeping the number of files on the local client disk to a minimum; instead, create
 617       symbolic links that point into AFS. This can improve machine performance by allowing more space for caching and
 618       swapping.</para>
 619
 620       <para>Some files, however, must reside on the local disk, as described below. Create these files in the prototype or library
 621       files using the <emphasis role="bold">F</emphasis> (file) instruction, not the <emphasis role="bold">L</emphasis> (symbolic
 622       link) instruction.</para>
 623
 624       <para>The following types of files must reside on the local disk of all AFS clients: <itemizedlist>
 625           <listitem>
 626             <para>Boot sequence files executed before the <emphasis role="bold">afsd</emphasis> program runs.</para>
 627
 628             <para>Until <emphasis role="bold">afsd</emphasis> runs and initializes the Cache Manager, AFS is inaccessible from the
 629             client. Any files that are executed before the <emphasis role="bold">afsd</emphasis> program runs must reside on the
 630             local client disk.</para>
 631
 632             <para>For example, on a machine that uses a disk cache, the <emphasis role="bold">/usr/vice/cache</emphasis> directory
 633             must exist when you bring up the Cache Manager, so that there is a location to create cache files. The binary files
 634             <emphasis role="bold">/etc/mount</emphasis> and <emphasis role="bold">/etc/umount</emphasis> must be available on the
 635             local disk as the machine boots in order to mount the <emphasis role="bold">/usr/vice/cache</emphasis> directory.</para>
 636
 637             <para>In addition, certain UNIX files, such as initialization files (<emphasis role="bold">/etc/rc</emphasis> or
 638             equivalent) and file system mapping files (<emphasis role="bold">/etc/fstab</emphasis> or equivalent), must reside on
 639             the local disk.</para>
 640           </listitem>
 641
 642           <listitem>
 643             <para>Diagnostic and recovery files</para>
 644
 645             <para>Certain commands can be used to diagnose and recover from problems caused by a file server outage. It is best to
 646             keep copies of the binaries for these commands on the local disk. For example, store the <emphasis
 647             role="bold">bos</emphasis> and <emphasis role="bold">fs</emphasis> binaries in the <emphasis
 648             role="bold">/usr/vice/etc</emphasis> directory on the local disk, as well as in the <emphasis
 649             role="bold">/usr/afsws</emphasis> directory (which in the conventional configuration is a symbolic link into AFS). Then,
 650             set PATH variables so that the <emphasis role="bold">/usr/afsws</emphasis> directory appears before the <emphasis
 651             role="bold">/usr/vice/etc</emphasis> directory. Thus, even if users cannot access AFS (for example, due to a file server
 652             outage) they can still access copies of the <emphasis role="bold">bos</emphasis> and <emphasis role="bold">fs</emphasis>
 653             binaries in the <emphasis role="bold">/usr/vice/etc</emphasis> directory on the local disk.</para>
 654           </listitem>
 655
 656           <listitem>
 657             <para>Files in the <emphasis role="bold">/usr/vice</emphasis> directory</para>
 658
 659             <para>The contents of the <emphasis role="bold">/usr/vice</emphasis> directory, including the cache files in the
 660             <emphasis role="bold">cache</emphasis> subdirectory and the configuration files in the <emphasis
 661             role="bold">etc</emphasis> subdirectory, must reside on the local disk. For a description of the files in the directory,
 662             see <link linkend="HDRWQ391">Configuration and Cache-Related Files on the Local Disk</link>.</para>
 663           </listitem>
 664         </itemizedlist></para>
 665
 666       <indexterm>
 667         <primary>D instruction</primary>
 668
 669         <secondary>package configuration file</secondary>
 670       </indexterm>
 671
 672       <indexterm>
 673         <primary>package</primary>
 674
 675         <secondary>D instruction in configuration file</secondary>
 676       </indexterm>
 677
 678       <indexterm>
 679         <primary>package</primary>
 680
 681         <secondary>defining directory in configuration file</secondary>
 682       </indexterm>
 683
 684       <indexterm>
 685         <primary>directory</primary>
 686
 687         <secondary>creating with package</secondary>
 688       </indexterm>
 689     </sect2>
 690
 691     <sect2 id="HDRWQ431">
 692       <title>Defining a Directory</title>
 693
 694       <para>The <emphasis role="bold">D</emphasis> instruction defines a directory to be created on the local disk. If a symbolic
 695       link, file, or other element on the local disk has the same name, it is replaced with a directory. If the directory already
 696       exists, its owner, group, and mode bits are changed if necessary to conform with the instruction.</para>
 697
 698       <para>Use the following instruction to define a directory:</para>
 699
 700       <programlisting><emphasis role="bold">D</emphasis>[update_code]   directory   owner   group   mode_bits
 701 </programlisting>
 702
 703       <para>The following example defines the <emphasis role="bold">/usr</emphasis> directory:</para>
 704
 705       <programlisting>
 706    D /usr root wheel 755
 707 </programlisting>
 708
 709       <indexterm>
 710         <primary>F instruction</primary>
 711
 712         <secondary>package configuration file</secondary>
 713       </indexterm>
 714
 715       <indexterm>
 716         <primary>package</primary>
 717
 718         <secondary>F instruction in configuration file</secondary>
 719       </indexterm>
 720
 721       <indexterm>
 722         <primary>package</primary>
 723
 724         <secondary>defining file in configuration file</secondary>
 725       </indexterm>
 726
 727       <indexterm>
 728         <primary>file</primary>
 729
 730         <secondary>creating with package</secondary>
 731       </indexterm>
 732     </sect2>
 733
 734     <sect2 id="HDRWQ432">
 735       <title>Defining a File</title>
 736
 737       <para>The <emphasis role="bold">F</emphasis> instruction defines a file to be created on the local disk. The source file can
 738       reside in either AFS or the local disk.</para>
 739
 740       <para>If a file of this name already exists, then it is updated with (overwritten by) the source file, unless the <emphasis
 741       role="bold">I</emphasis> update code is specified. If a symbolic link or directory of this name exists, the <emphasis
 742       role="bold">package</emphasis> program replaces it with the source file.</para>
 743
 744       <note>
 745         <para>Some files must reside on the local disk; they cannot be symbolic links. See <link linkend="HDRWQ430">Local Files
 746         versus Symbolic Links</link>.</para>
 747       </note>
 748
 749       <para>Use the following instruction to define a file:</para>
 750
 751       <programlisting><emphasis role="bold">F</emphasis>[update_code]   file   source_file  [owner   group   mode_bits]
 752 </programlisting>
 753
 754       <para>An example which creates/updates the file <emphasis role="bold">/bin/grep</emphasis> on the local disk, using <emphasis
 755       role="bold">/afs/example.com/rs_aix42/bin/grep</emphasis> as the source:</para>
 756
 757       <programlisting>
 758    F /bin/grep /afs/example.com/rs_aix42 root wheel 755
 759 </programlisting>
 760
 761       <para>In the following example, two update codes are used, and the <emphasis>owner</emphasis>, <emphasis>group</emphasis> and
 762       <emphasis>mode_bits</emphasis> slots are left empty, so that the disk file adopts the source file's values for those
 763       slots.</para>
 764
 765       <programlisting>
 766    FAQ /usr/vice/etc/ThisCell /afs/example.com/common/etc/ThisCell
 767 </programlisting>
 768
 769       <indexterm>
 770         <primary>L instruction</primary>
 771
 772         <secondary>package configuration file</secondary>
 773       </indexterm>
 774
 775       <indexterm>
 776         <primary>package</primary>
 777
 778         <secondary>L instruction in configuration file</secondary>
 779       </indexterm>
 780
 781       <indexterm>
 782         <primary>package</primary>
 783
 784         <secondary>defining symbolic link in configuration file</secondary>
 785       </indexterm>
 786
 787       <indexterm>
 788         <primary>symbolic link</primary>
 789
 790         <secondary>creating with package</secondary>
 791       </indexterm>
 792     </sect2>
 793
 794     <sect2 id="HDRWQ433">
 795       <title>Defining a Symbolic Link</title>
 796
 797       <para>The <emphasis role="bold">L</emphasis> instruction defines a symbolic link to be created on the local disk. The symbolic
 798       link can point to the AFS file system or the local disk. If the identical symbolic link already exists, the <emphasis
 799       role="bold">package</emphasis> program does nothing. However, if an element of the same name exists on the disk as a file or
 800       directory, the <emphasis role="bold">package</emphasis> program replaces the element with a symbolic link.</para>
 801
 802       <note>
 803         <para>Some files must reside on the local disk; they cannot be symbolic links. See <link linkend="HDRWQ430">Local Files
 804         versus Symbolic Links</link>.</para>
 805       </note>
 806
 807       <para>Use the following instruction to define a symbolic link:</para>
 808
 809       <programlisting><emphasis role="bold">L</emphasis>[update_code]  link actual_file  [owner   group   mode_bits]
 810 </programlisting>
 811
 812       <note>
 813         <para>Do not create a symbolic link to a file whose name begins with the number sign (<emphasis role="bold">#</emphasis>) or
 814         percent sign (<emphasis role="bold">%</emphasis>). The Cache Manager interprets such a link as a mount point to a regular or
 815         Read/Write volume, respectively.</para>
 816       </note>
 817
 818       <para>The following example creates a symbolic link from the <emphasis role="bold">/etc/ftpd</emphasis> directory on the local
 819       disk to the <emphasis role="bold">/afs/example.com/hp_ux110/etc/ftpd</emphasis> file in AFS. Since the <emphasis>owner</emphasis>,
 820       <emphasis>group</emphasis> and <emphasis>mode_bits</emphasis> fields are empty, the symbolic link adopts values for those
 821       fields from the actual file:</para>
 822
 823       <programlisting>
 824    L /etc/ftpd /afs/example.com/hp_ux110
 825 </programlisting>
 826
 827       <para>This example uses the <emphasis role="bold">A</emphasis> update code:</para>
 828
 829       <programlisting>
 830    LA /etc/printcap /afs/example.com/common/etc/printcap.remote
 831                root wheel 644
 832 </programlisting>
 833
 834       <indexterm>
 835         <primary>B instruction</primary>
 836
 837         <secondary>package configuration file</secondary>
 838       </indexterm>
 839
 840       <indexterm>
 841         <primary>package</primary>
 842
 843         <secondary>B instruction in configuration file</secondary>
 844       </indexterm>
 845
 846       <indexterm>
 847         <primary>package</primary>
 848
 849         <secondary>defining block special device in configuration file</secondary>
 850       </indexterm>
 851
 852       <indexterm>
 853         <primary>block special device</primary>
 854
 855         <secondary>creating with package</secondary>
 856       </indexterm>
 857     </sect2>
 858
 859     <sect2 id="HDRWQ434">
 860       <title>Defining a Block Special Device</title>
 861
 862       <para>The <emphasis role="bold">B</emphasis> instruction defines a block special device, which is a device that handles data
 863       in units of multibyte blocks, such as a disk. If a device of the same name already exists, the <emphasis
 864       role="bold">package</emphasis> program replaces it with the specified block device.</para>
 865
 866       <para>Use the following instruction to define a block special device (it appears on two lines here only for
 867       legibility):</para>
 868
 869       <programlisting><emphasis role="bold">B</emphasis> device_name   major_device_number   minor_device_number  \
 870       owner   group   mode_bits
 871 </programlisting>
 872
 873       <para>The following example defines a disk called <emphasis role="bold">/dev/hd0a</emphasis> to have major and minor device
 874       numbers <emphasis role="bold">1</emphasis> and <emphasis role="bold">0</emphasis>:</para>
 875
 876       <programlisting>
 877    B /dev/hd0a 1 0 root wheel 644
 878 </programlisting>
 879
 880       <indexterm>
 881         <primary>C instruction</primary>
 882
 883         <secondary>package configuration file</secondary>
 884       </indexterm>
 885
 886       <indexterm>
 887         <primary>package</primary>
 888
 889         <secondary>C instruction in configuration file</secondary>
 890       </indexterm>
 891
 892       <indexterm>
 893         <primary>package</primary>
 894
 895         <secondary>defining character special device in configuration file</secondary>
 896       </indexterm>
 897
 898       <indexterm>
 899         <primary>character special device</primary>
 900
 901         <secondary>creating with package</secondary>
 902       </indexterm>
 903     </sect2>
 904
 905     <sect2 id="HDRWQ435">
 906       <title>Defining a Character Special Device</title>
 907
 908       <para>The <emphasis role="bold">C</emphasis> instruction defines a character special device, which is device that handles data
 909       in units of a single character at a time, such as a terminal or tty. If a device of the same name already exists, the
 910       <emphasis role="bold">package</emphasis> program replaces it with the specified character device.</para>
 911
 912       <para>Use the following instruction to define a character special device (it appears here on two lines only for
 913       legibility):</para>
 914
 915       <programlisting><emphasis role="bold">C</emphasis> device_name   major_device_number   minor_device_number  \
 916       owner   group   mode_bits
 917 </programlisting>
 918
 919       <para>The following example defines the tty called <emphasis role="bold">/dev/ttyp5</emphasis> with major and minor device
 920       numbers <emphasis role="bold">6</emphasis> and <emphasis role="bold">5</emphasis>:</para>
 921
 922       <programlisting>
 923    C /dev/ttyp5 6 5 root wheel 666
 924 </programlisting>
 925
 926       <indexterm>
 927         <primary>S instruction</primary>
 928
 929         <secondary>package configuration file</secondary>
 930       </indexterm>
 931
 932       <indexterm>
 933         <primary>package</primary>
 934
 935         <secondary>S instruction in configuration file</secondary>
 936       </indexterm>
 937
 938       <indexterm>
 939         <primary>package</primary>
 940
 941         <secondary>defining socket in configuration file</secondary>
 942       </indexterm>
 943
 944       <indexterm>
 945         <primary>socket</primary>
 946
 947         <secondary>creating with package</secondary>
 948       </indexterm>
 949     </sect2>
 950
 951     <sect2 id="HDRWQ436">
 952       <title>Defining a Socket</title>
 953
 954       <para>The <emphasis role="bold">S</emphasis> instruction defines a socket, which is communications device for UDP and TCP/IP
 955       connections. If a socket of the same name already exists, the <emphasis role="bold">package</emphasis> program replaces
 956       it.</para>
 957
 958       <para>Use the following instruction to define a socket:</para>
 959
 960       <programlisting><emphasis role="bold">S</emphasis>   socket_name   [owner   group   mode_bits]
 961 </programlisting>
 962
 963       <para>The following example defines a socket called <emphasis role="bold">/dev/printer</emphasis>:</para>
 964
 965       <programlisting>
 966    S /dev/printer root wheel 777
 967 </programlisting>
 968     </sect2>
 969   </sect1>
 970
 971   <sect1 id="HDRWQ437">
 972     <title>Constructing Prototype and Library Files</title>
 973
 974     <indexterm>
 975       <primary>package</primary>
 976
 977       <secondary>constructing prototype and library files</secondary>
 978     </indexterm>
 979
 980     <indexterm>
 981       <primary>prototype files in package</primary>
 982
 983       <secondary>constructing</secondary>
 984     </indexterm>
 985
 986     <indexterm>
 987       <primary>library files in package</primary>
 988
 989       <secondary>constructing</secondary>
 990     </indexterm>
 991
 992     <para>This section describes the general steps required to create <emphasis role="bold">package</emphasis> prototype and library
 993     files. Refer to the previous sections for guidelines, and the files in your <emphasis role="bold">wsadmin</emphasis> directory
 994     for examples. The construction of prototype and library files is different for each cell.</para>
 995
 996     <sect2 id="Header_515">
 997       <title>To construct a prototype file and its component library files</title>
 998
 999       <orderedlist>
1000         <listitem>
1001           <para>Determine where the three <emphasis role="bold">package</emphasis>-related subdirectories (<emphasis
1002           role="bold">src</emphasis>, <emphasis role="bold">lib</emphasis> and <emphasis role="bold">etc</emphasis>) reside in your
1003           cell's file tree; the following instructions assume they were loaded into the <emphasis
1004           role="bold">/afs/</emphasis>cellname<emphasis role="bold">/wsadmin</emphasis> directory, as described in the OpenAFS Quick
1005           Beginnings.</para>
1006         </listitem>
1007
1008         <listitem>
1009           <para>Decide how many different functions you want client machines in your cell to perform. We recommend that you
1010           construct a separate prototype file for each function. Common functions include: <itemizedlist>
1011               <listitem>
1012                 <para>Standard workstation: provides users with access to files in AFS</para>
1013               </listitem>
1014
1015               <listitem>
1016                 <para>Printer server: drives a printer; can be combined with "staff" functionality</para>
1017               </listitem>
1018
1019               <listitem>
1020                 <para>Backup machine: performs backups of AFS volumes to tape by running the AFS Backup System software</para>
1021               </listitem>
1022             </itemizedlist></para>
1023         </listitem>
1024
1025         <listitem>
1026           <para>Determine the minimum functionality needed for all clients (such as AFS setup) and place these generic definitions
1027           in one or more library files.</para>
1028         </listitem>
1029
1030         <listitem>
1031           <para>For each type of client (printer server, backup machine, and so on), place all system-independent definitions in one
1032           file, and all operating-system dependent definitions in another file.</para>
1033         </listitem>
1034       </orderedlist>
1035     </sect2>
1036   </sect1>
1037
1038   <sect1 id="HDRWQ438">
1039     <title>The Package Makefile File</title>
1040
1041     <indexterm>
1042       <primary>package</primary>
1043
1044       <secondary>Makefile</secondary>
1045     </indexterm>
1046
1047     <indexterm>
1048       <primary>Makefile for package</primary>
1049     </indexterm>
1050
1051     <indexterm>
1052       <primary>files</primary>
1053
1054       <secondary>package Makefile</secondary>
1055     </indexterm>
1056
1057     <para>Once you have created the appropriate prototype and library files, you must compile the prototype for each system type.
1058     The result is a system-specific configuration file.</para>
1059
1060     <para>The <emphasis role="bold">Makefile</emphasis> file defines the prototype and library files used and the order of
1061     compilation. We recommend that you create your <emphasis role="bold">Makefile</emphasis> file by modifying the example provided
1062     with the AFS distribution, as described in this section. In the conventional configuration, it is located at <emphasis
1063     role="bold">/afs/</emphasis>cellname<emphasis role="bold">/wsadmin/src/Makefile</emphasis>.</para>
1064
1065     <sect2 id="Header_517">
1066       <title>Overview</title>
1067
1068       <para>The following list summarizes the sections in the <emphasis role="bold">package</emphasis> <emphasis
1069       role="bold">Makefile</emphasis> file, identifying each by the header name that begins the section. More detailed descriptions
1070       follow. <variablelist>
1071           <varlistentry>
1072             <term><emphasis role="bold">CONFIG=</emphasis></term>
1073
1074             <listitem>
1075               <para>Lists all of the configuration files to be created and defines which prototype files are compiled for which
1076               system types. See <link linkend="HDRWQ439">The CONFIG Section</link>.</para>
1077             </listitem>
1078           </varlistentry>
1079
1080           <varlistentry>
1081             <term><emphasis role="bold">BASE_LIBS=</emphasis></term>
1082
1083             <listitem>
1084               <para>Lists the pathnames of all operating-system- and function independent library files included in any prototype
1085               files. See <link linkend="HDRWQ440">The BASE_LIBS Section</link>.</para>
1086             </listitem>
1087           </varlistentry>
1088
1089           <varlistentry>
1090             <term><emphasis role="bold">MACHINE_LIBS=</emphasis></term>
1091
1092             <listitem>
1093               <para>Lists the pathnames of all operating-system-specific library files included in any prototype files. See <link
1094               linkend="HDRWQ441">The MACHINE_LIBS Section</link>.</para>
1095             </listitem>
1096           </varlistentry>
1097
1098           <varlistentry>
1099             <term><emphasis role="bold">LIBS=</emphasis></term>
1100
1101             <listitem>
1102               <para>A one-line instruction that defines LIBS as the combination of BASE_LIBS and MACHINE_LIBS. See <link
1103               linkend="HDRWQ442">The LIBS Section</link>.</para>
1104             </listitem>
1105           </varlistentry>
1106
1107           <varlistentry>
1108             <term><emphasis role="bold">.SUFFIXES</emphasis></term>
1109
1110             <listitem>
1111               <para>Defines all of the suffixes that can appear on a prototype or configuration file. See <link
1112               linkend="HDRWQ443">The .SUFFIXES Section</link>.</para>
1113             </listitem>
1114           </varlistentry>
1115         </variablelist></para>
1116
1117       <para>Finally, the <emphasis role="bold">Makefile</emphasis> file contains a set of instructions that the <emphasis
1118       role="bold">package</emphasis> program follows to generate configuration files. It is not generally necessary to alter this
1119       section. See <link linkend="HDRWQ444">The Makefile Instructions Section</link>.</para>
1120     </sect2>
1121
1122     <sect2 id="HDRWQ439">
1123       <title>The CONFIG Section</title>
1124
1125       <para>As mentioned, a configuration file is a prototype file that has been compiled for a specific operating system type. The
1126       CONFIG section of the <emphasis role="bold">Makefile</emphasis> file defines the prototype files to compile for each system
1127       type. The resulting compiled file is a system-specific configuration file.</para>
1128
1129       <para>Study the following example taken from the sample <emphasis role="bold">Makefile</emphasis> file. Configuration files
1130       are defined by specifying the prototype-system combination as prototype_file<emphasis role="bold">.</emphasis>sysname. Note
1131       that it is not necessary to generate a configuration file for each prototype-system type combination.</para>
1132
1133       <programlisting>
1134    #Makefile...
1135    #    (C) Copyright IBM Corporation 1999
1136    #    Licensed Materials - Property of IBM
1137    #    All Rights Reserved.
1138    #
1139    CONFIG = \
1140             staff.rs_aix42 \
1141             staff.alpha_dux40 \
1142             staff.xdm.alpha_dux40 \
1143             staff.sun4x_56 \
1144             staff.hp_ux110 \
1145             minimal.rs_aix42 \
1146             minimal.alpha_dux40 \
1147             minimal.hp_ux110 \
1148             minimal.sun4x_56
1149 </programlisting>
1150
1151       <para>An entry in the CONFIG section has the following format: <itemizedlist>
1152           <listitem>
1153             <para>The first part of the entry defines the prototype file and is the same as the prototype file name (without the
1154             <emphasis role="bold">.proto</emphasis> extension). The second part of the entry indicates the system type for which the
1155             prototype file is to be compiled. A complete list of these suffixes is in the .SUFFIXES section of the <emphasis
1156             role="bold">Makefile</emphasis> file, as described in <link linkend="HDRWQ443">The .SUFFIXES Section</link>. This
1157             prototype_file<emphasis role="bold">.</emphasis>sysname definition becomes the name of the compiled configuration
1158             file.</para>
1159
1160             <para>For example, <emphasis role="bold">staff.rs_aix42</emphasis> indicates that the <emphasis
1161             role="bold">staff.proto</emphasis> file is compiled for machines running AIX 4.2. The resulting compiled configuration
1162             file is called <emphasis role="bold">staff.rs_aix42</emphasis>.</para>
1163           </listitem>
1164
1165           <listitem>
1166             <para>Each configuration file must appear on a separate line.</para>
1167           </listitem>
1168
1169           <listitem>
1170             <para>A backslash must follow the CONFIG= header and every name but the last one. A backslash must also appear on blank
1171             lines.</para>
1172           </listitem>
1173         </itemizedlist></para>
1174     </sect2>
1175
1176     <sect2 id="HDRWQ440">
1177       <title>The BASE_LIBS Section</title>
1178
1179       <para>This section defines the complete pathname of all system- and function-independent library files included in any
1180       prototype file. (System-specific library files are defined in the MACHINE_LIBS section). The pathnames can include the
1181       ${wsadmin} variable, whose value is supplied on the <emphasis role="bold">make</emphasis> command line.</para>
1182
1183       <para>You must include all of the library files referred to in your prototype files; files included but not used are
1184       ignored.</para>
1185
1186       <para>Study the following example. Note that the all entries (except the last one) must be followed by a backslash.</para>
1187
1188       <programlisting>
1189    BASE_LIBS = \
1190            ${wsadmin}/src/admin \
1191            ${wsadmin}/lib/devel \
1192            ${wsadmin}/lib/base.generic
1193 </programlisting>
1194     </sect2>
1195
1196     <sect2 id="HDRWQ441">
1197       <title>The MACHINE_LIBS Section</title>
1198
1199       <para>This section lists the complete pathname of all operating-system-specific library files included in prototype files.
1200       (System- and function-independent library files are defined in the BASE_LIBS section.)</para>
1201
1202       <para>Study the following example. Note that in this example, library files were grouped by operating-system type. Again, all
1203       lines (except the last one) must be followed by a backslash, the ${wsadmin} variable is allowed, and files included but not
1204       used are ignored.</para>
1205
1206       <programlisting>
1207    MACHINE_LIBS = \
1208            ${wsadmin}/lib/rs_aix42.generic \
1209            ${wsadmin}/lib/rs_aix42.generic.dev \
1210            ${wsadmin}/lib/rs_aix42.readonly \
1211            ${wsadmin}/lib/rs_aix42.readwrite \
1212            ${wsadmin}/lib/rt_aix42.generic.printer \
1213     \
1214     .
1215     .
1216            ${wsadmin}/lib/alpha_dux40.AFS \
1217            ${wsadmin}/lib/hp_ux110.AFS \
1218            ${wsadmin}/lib/sun4x_56.AFS \
1219            ${wsadmin}/lib/rs_aix42.AFS
1220 </programlisting>
1221     </sect2>
1222
1223     <sect2 id="HDRWQ442">
1224       <title>The LIBS Section</title>
1225
1226       <para>This section contains only one instruction, which indicates that LIBS is defined as the combination of MACHINE_LIBS and
1227       BASE_LIBS. Insert a blank line after the line to separate this section from the next.</para>
1228
1229       <programlisting>
1230    LIBS = ${MACHINE_LIBS} ${BASE_LIBS}
1231 </programlisting>
1232     </sect2>
1233
1234     <sect2 id="HDRWQ443">
1235       <title>The .SUFFIXES Section</title>
1236
1237       <para>This section lists the valid machine-type suffixes. This list includes system types currently supported for AFS. Unused
1238       suffixes are ignored.</para>
1239
1240       <programlisting>
1241    .SUFFIXES: .rs_aix42 \
1242               .alpha_dux40 \
1243               .proto \
1244               .sun4x_56 \
1245               .i386_linux22 \
1246               .hp_ux110
1247 </programlisting>
1248     </sect2>
1249
1250     <sect2 id="HDRWQ444">
1251       <title>The Makefile Instructions Section</title>
1252
1253       <para>The remainder of the <emphasis role="bold">Makefile</emphasis> file controls how the <emphasis
1254       role="bold">package</emphasis> program generates configuration files.</para>
1255
1256       <para>Study the following instructions; it is assumed that you are familiar with programming and <emphasis
1257       role="bold">Makefile</emphasis> concepts.</para>
1258
1259       <programlisting>
1260    #The following appear on a single line each in the actual file
1261    .proto.rs_aix42: ;  mpp -Dwsadmin=${wsadmin} -Dsys=rs_aix42
1262                            -Dname=$* $*.proto &gt; $@
1263    .proto.alpha_dux40: ; mpp -Dwsadmin=${wsadmin} -Dsys=alpha_dux40
1264                            -Dname=$* $*.proto &gt; $@
1265    .proto.sun4x_56:  ; mpp -Dwsadmin=${wsadmin} -Dsys=sun4x_56
1266                            -Dname=$* $*.proto &gt; $@
1267    .proto.hp_ux110:  ; mpp -Dwsadmin=${wsadmin} -Dsys=hp_ux110
1268                            -Dname=$* $*.proto &gt; $@
1269    all: ${CONFIG}
1270    ${CONFIG}: ${LIBS}
1271    system: install
1272    install: ${CONFIG}
1273            cp ${CONFIG} ${wsadmin}/etc
1274    clean:
1275            rm -f ${CONFIG} *.BAK *.CKP
1276 </programlisting>
1277     </sect2>
1278   </sect1>
1279
1280   <sect1 id="HDRWQ445">
1281     <title>Modifying the Makefile</title>
1282
1283     <indexterm>
1284       <primary>package</primary>
1285
1286       <secondary>modifying the Makefile</secondary>
1287     </indexterm>
1288
1289     <indexterm>
1290       <primary>Makefile for package</primary>
1291
1292       <secondary>modifying</secondary>
1293     </indexterm>
1294
1295     <indexterm>
1296       <primary>modifying</primary>
1297
1298       <secondary>package Makefile</secondary>
1299     </indexterm>
1300
1301     <para>Modify the <emphasis role="bold">package</emphasis> <emphasis role="bold">Makefile</emphasis> files when you <itemizedlist>
1302         <listitem>
1303           <para>Add a new prototype file (function<emphasis role="bold">.proto</emphasis>).</para>
1304         </listitem>
1305
1306         <listitem>
1307           <para>Add a new system type.</para>
1308         </listitem>
1309
1310         <listitem>
1311           <para>Add new library files.</para>
1312         </listitem>
1313       </itemizedlist></para>
1314
1315     <para>The following sections provide brief examples of how to modify the <emphasis role="bold">Makefile</emphasis> file for
1316     these reasons.</para>
1317
1318     <sect2 id="Header_525">
1319       <title>Adding a New Prototype File</title>
1320
1321       <para>When you create a new prototype file, add the file name and each system type for which it is to be built into the CONFIG
1322       section of the <emphasis role="bold">Makefile</emphasis> file.</para>
1323
1324       <para>For example, to add a function<emphasis role="bold">.proto</emphasis> file for <emphasis
1325       role="bold">alpha_dux40</emphasis> and <emphasis role="bold">hp_ux110</emphasis>, add the following entries to the CONFIG
1326       section:</para>
1327
1328       <programlisting>
1329    CONFIG = \
1330    ...
1331            function.alpha_dux40 \
1332            function.hp_ux110 \
1333    ...
1334 </programlisting>
1335
1336       <para>If you have added new library files for this prototype function, add those to the MACHINE_LIBS section.</para>
1337     </sect2>
1338
1339     <sect2 id="Header_526">
1340       <title>Adding a New System Type</title>
1341
1342       <para>For each prototype file that you want to build for the new system type, add an entry to the CONFIG section. Also add any
1343       new libraries to the MACHINE_LIBS section, and the new system type to the .SUFFIXES section.</para>
1344
1345       <para>The following example shows the modifications appropriate when building the <emphasis role="bold">staff</emphasis> and
1346       <emphasis role="bold">minimal</emphasis> prototype files for this new system type.</para>
1347
1348       <programlisting>
1349    CONFIG = \
1350    ...
1351            staff.sysname \
1352            minimal.sysname \
1353    ...
1354 </programlisting>
1355
1356       <para>If you have created corresponding library files for this new machine type, add them to the MACHINE_LIBS section.</para>
1357
1358       <programlisting>
1359    MACHINE_LIBS = \
1360    ...
1361            ${wsadmin}/lib/sysname.generic \
1362            ${wsadmin}/lib/sysname.generic.dev \
1363            ${wsadmin}/lib/sysname.readonly \
1364            ${wsadmin}/lib/sysname.readwrite \
1365    ...
1366 </programlisting>
1367
1368       <para>Add the new system type to the SUFFIXES section.</para>
1369
1370       <programlisting>
1371    .SUFFIXES: ...\
1372             .sysname \
1373    ...
1374 </programlisting>
1375
1376       <para>Add a line to build the configuration files for this system in the section with the rest of the commands to build
1377       configuration files:</para>
1378
1379       <programlisting>
1380    .proto.sysname: ; mpp -Dwsadmin=${wsadmin} \
1381    -Dsys=sysname  -Dname=$* $*.proto &gt; $
1382 </programlisting>
1383     </sect2>
1384
1385     <sect2 id="Header_527">
1386       <title>Adding New Library Files</title>
1387
1388       <para>If you added a new library file for each system type, sysname<emphasis
1389       role="bold">.</emphasis><emphasis>library_file</emphasis>, add these files to the MACHINE_LIBS section of the <emphasis
1390       role="bold">Makefile</emphasis>.</para>
1391
1392       <programlisting>
1393    MACHINE_LIBS = \
1394    ...
1395            ${wsadmin}/lib/rs_aix42.library_file \
1396    ...
1397            ${wsadmin}/lib/alpha_dux40.library_file \
1398    ...
1399            ${wsadmin}/lib/sun4x_56.library_file \
1400    ...
1401 </programlisting>
1402
1403       <para>If you added a new library file that is common to all system types, library_file, add this only to the BASE_LIBS
1404       section:</para>
1405
1406       <programlisting>
1407    BASE_LIBS = \
1408    ...
1409            ${wsadmin}/lib/library_file \
1410    ...
1411 </programlisting>
1412     </sect2>
1413   </sect1>
1414
1415   <sect1 id="HDRWQ446">
1416     <title>Compiling Prototype Files</title>
1417
1418     <indexterm>
1419       <primary>compiling</primary>
1420
1421       <secondary>package prototype file</secondary>
1422     </indexterm>
1423
1424     <indexterm>
1425       <primary>package</primary>
1426
1427       <secondary>compiling prototype files</secondary>
1428     </indexterm>
1429
1430     <para>The <emphasis role="bold">package</emphasis> program generates configuration files and installs them in the <emphasis
1431     role="bold">etc</emphasis> and <emphasis role="bold">src</emphasis> subdirectories of the directory designated as <emphasis
1432     role="bold">wsadmin=</emphasis> on the <emphasis role="bold">make</emphasis> command line. Recompile whenever you modify a
1433     prototype or library file.</para>
1434
1435     <sect2 id="Header_529">
1436       <title>To compile prototype files</title>
1437
1438       <note>
1439         <para>These instructions assume that you store your <emphasis role="bold">package</emphasis>-related files in the <emphasis
1440         role="bold">/afs/</emphasis>cellname<emphasis role="bold">/wsadmin</emphasis> directory. If you use a different directory,
1441         substitute its name for <emphasis role="bold">/afs/</emphasis>cellname<emphasis role="bold">/wsadmin</emphasis>.</para>
1442       </note>
1443
1444       <orderedlist>
1445         <listitem>
1446           <para>Verify that you have all privileges in the <emphasis role="bold">/afs/</emphasis>cellname<emphasis
1447           role="bold">/wsadmin</emphasis> directory and in its <emphasis role="bold">src</emphasis>, <emphasis
1448           role="bold">lib</emphasis> and <emphasis role="bold">etc</emphasis> subdirectories. If necessary, issue the <emphasis
1449           role="bold">fs</emphasis> <emphasis role="bold">listacl</emphasis> command. <programlisting>
1450    % <emphasis role="bold">fs listacl</emphasis> [dir/file path]
1451 </programlisting></para>
1452         </listitem>
1453
1454         <listitem>
1455           <para>Change to the <emphasis role="bold">/afs/</emphasis>cellname<emphasis role="bold">/wsadmin/src</emphasis>
1456           subdirectory. <programlisting>
1457    % <emphasis role="bold">cd /afs/</emphasis>cellname<emphasis role="bold">/wsadmin/src</emphasis>
1458 </programlisting></para>
1459         </listitem>
1460
1461         <listitem>
1462           <para>Create a backup copy of the <emphasis role="bold">Makefile</emphasis> file included in the AFS distribution.
1463           <programlisting>
1464    % <emphasis role="bold">cp  Makefile Makefile.example</emphasis>
1465 </programlisting></para>
1466         </listitem>
1467
1468         <listitem>
1469           <para>Modify the CONFIG, BASE_LIBS and MACHINE_LIBS sections of the <emphasis role="bold">Makefile</emphasis> file, as
1470           described in <link linkend="HDRWQ439">The CONFIG Section</link>, <link linkend="HDRWQ440">The BASE_LIBS Section</link>,
1471           and <link linkend="HDRWQ441">The MACHINE_LIBS Section</link>.</para>
1472         </listitem>
1473
1474         <listitem>
1475           <para>Compile the prototype files using the <emphasis role="bold">make</emphasis> command.</para>
1476
1477           <para>Use the <emphasis role="bold">wsadmin=</emphasis> argument to specify the <emphasis role="bold">package</emphasis>
1478           directory. This becomes the value of the ${wsadmin} variable in the prototype and the library files.</para>
1479
1480           <para>The <emphasis role="bold">package</emphasis> program generates configuration files and installs them in the
1481           <emphasis role="bold">etc</emphasis> and <emphasis role="bold">src</emphasis> subdirectories of the directory designated
1482           as <emphasis role="bold">wsadmin=</emphasis>.</para>
1483
1484           <programlisting>
1485    % <emphasis role="bold">make system wsadmin=/afs/</emphasis>cellname<emphasis role="bold">/wsadmin</emphasis>
1486 </programlisting>
1487         </listitem>
1488       </orderedlist>
1489     </sect2>
1490   </sect1>
1491
1492   <sect1 id="HDRWQ447">
1493     <title>Modifying Client Machines</title>
1494
1495     <indexterm>
1496       <primary>package directory</primary>
1497     </indexterm>
1498
1499     <indexterm>
1500       <primary>client</primary>
1501
1502       <secondary>modifying to run package</secondary>
1503     </indexterm>
1504
1505     <indexterm>
1506       <primary>package</primary>
1507
1508       <secondary>modifying clients to run</secondary>
1509     </indexterm>
1510
1511     <indexterm>
1512       <primary>modifying</primary>
1513
1514       <secondary>clients to run package</secondary>
1515     </indexterm>
1516
1517     <para>To prepare a client to run the <emphasis role="bold">package</emphasis> program automatically, perform the following
1518     steps. The instructions are generic because they do not refer to system-specific configuration files. If desired, you can invoke
1519     the <emphasis role="bold">package</emphasis> program with specific arguments, as described in the <emphasis>OpenAFS
1520     Administration Reference</emphasis>. <orderedlist>
1521         <listitem>
1522           <para>Specify the configuration file to use.</para>
1523
1524           <para>The <emphasis role="bold">.package</emphasis> file in the client machine's root ( <emphasis
1525           role="bold">/</emphasis>) directory is redirected as an argument to the <emphasis role="bold">package</emphasis> command;
1526           the <emphasis role="bold">.package</emphasis> file specifies which configuration file the <emphasis
1527           role="bold">package</emphasis> program uses.</para>
1528         </listitem>
1529
1530         <listitem>
1531           <para>Make the <emphasis role="bold">package</emphasis> binary available to the client, either by copying it to the local
1532           disk, or by creating a symbolic link to AFS. <itemizedlist>
1533               <listitem>
1534                 <para>A symbolic link saves local disk space. However, when the file server machine that houses it is down, the
1535                 <emphasis role="bold">package</emphasis> binary is inaccessible.</para>
1536               </listitem>
1537
1538               <listitem>
1539                 <para>Keeping the <emphasis role="bold">package</emphasis> binary on the local disk enables you to run the <emphasis
1540                 role="bold">package</emphasis> program even if file server is down. However, a file server machine outage usually
1541                 makes it difficult to run the <emphasis role="bold">package</emphasis> program because most configuration file
1542                 instructions refer to files in AFS. A local copy of the <emphasis role="bold">package</emphasis> binary can be
1543                 useful if the files referred to in instructions are in replicated volumes.</para>
1544               </listitem>
1545             </itemizedlist></para>
1546         </listitem>
1547
1548         <listitem>
1549           <para>Modify the client machine's initialization file to invoke the <emphasis role="bold">package</emphasis> program at
1550           reboot. The client machine reboots a second time if the <emphasis role="bold">package</emphasis> program updates any files
1551           marked with the <emphasis role="bold">Q</emphasis> update code.</para>
1552         </listitem>
1553       </orderedlist></para>
1554
1555     <sect2 id="Header_531">
1556       <title>To prepare a client machine to run the package program</title>
1557
1558       <para>Repeat these instructions on every client that runs the <emphasis role="bold">package</emphasis> program.</para>
1559
1560       <para>These instructions assume that the <emphasis role="bold">package</emphasis> configuration files (created when the
1561       prototype files were compiled) reside in the <emphasis role="bold">/afs/</emphasis>cellname<emphasis
1562       role="bold">/wsadmin/etc</emphasis> directory. <orderedlist>
1563           <listitem>
1564             <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by
1565             issuing the <emphasis role="bold">su</emphasis> command. <programlisting>
1566    % <emphasis role="bold">su root</emphasis>
1567    Password: &lt;<replaceable>root_password</replaceable>&gt;
1568 </programlisting></para>
1569           </listitem>
1570
1571           <listitem>
1572             <para>Create the <emphasis role="bold">.package</emphasis> file in the root ( <emphasis role="bold">/</emphasis>)
1573             directory and specify the name of the prototype file to use. Do not include the system-type suffix (such as <emphasis
1574             role="bold">.rs_aix42</emphasis>); the <emphasis role="bold">package</emphasis> program automatically determines the
1575             correct machine type. <programlisting>
1576    # <emphasis role="bold">echo "/afs/</emphasis>cellname<emphasis role="bold">/wsadmin/etc/</emphasis>config_file<emphasis
1577                   role="bold">" &gt;&gt; /.package</emphasis>
1578 </programlisting></para>
1579
1580             <para>For example, to configure a machine for a member of staff machine (assuming the proper prototype file had been
1581             defined and compiled for the system type), the appropriate command is:</para>
1582
1583             <programlisting>
1584    # <emphasis role="bold">echo "/afs/</emphasis>cellname<emphasis role="bold">/wsadmin/etc/staff" &gt;&gt; /.package</emphasis>
1585 </programlisting>
1586           </listitem>
1587
1588           <listitem>
1589             <para>Make the <emphasis role="bold">package</emphasis> binary available on the local disk as <emphasis
1590             role="bold">/etc/package</emphasis>. Issue one of the following commands, depending on whether you want to create a file
1591             or create a symbolic link.</para>
1592
1593             <para>To store the <emphasis role="bold">package</emphasis> binary locally, enter the following command:</para>
1594
1595             <programlisting>
1596    # <emphasis role="bold">cp /afs/</emphasis>cellname<emphasis role="bold">/</emphasis>sysname<emphasis role="bold">/usr/afsws/etc/package   /etc/package</emphasis>
1597 </programlisting>
1598
1599             <para>To create a symbolic link, enter the following command:</para>
1600
1601             <programlisting>
1602    # <emphasis role="bold">ln -s /afs/</emphasis>cellname<emphasis role="bold">/</emphasis>sysname<emphasis role="bold">/usr/afsws/etc/package   /etc/package</emphasis>
1603 </programlisting>
1604           </listitem>
1605
1606           <listitem>
1607             <para>Add the following lines to the appropriate initialization file, after the <emphasis role="bold">afsd</emphasis>
1608             command is invoked. If this is a file server machine, the <emphasis role="bold">bosserver</emphasis> command must follow
1609             the <emphasis role="bold">package</emphasis> command.</para>
1610
1611             <para>Using the <emphasis role="bold">-v</emphasis> and <emphasis role="bold">-c</emphasis> options is recommended. The
1612             <emphasis role="bold">-v</emphasis> flag produces a detailed trace, and the <emphasis role="bold">-c</emphasis> option
1613             appends the system type to the base name of the configuration file. See the <emphasis>OpenAFS Administration
1614             Reference</emphasis> for a description of other options.</para>
1615
1616             <note>
1617               <para>Replace the <emphasis role="bold">shutdown</emphasis> command with a similar command if it is not appropriate
1618               for rebooting your machine.</para>
1619             </note>
1620
1621             <programlisting>
1622    if [ -f /etc/package ]; then
1623            if [ -f /.package ]: then
1624                    /etc/package -v -c `cat /.package` &gt;/dev/console
1625            else
1626                    /etc/package -v &gt;/dev/console
1627    fi
1628    case $? in
1629    0)
1630            echo "Package completed successfully" &gt;/dev/console 2&gt;&amp;1
1631            date &gt;/dev/console 2&gt;&amp;1
1632            ;;
1633    4)
1634            echo "Rebooting to restart system" &gt;/dev/console 2&gt;&amp;1
1635            echo &gt;/fastboot
1636            shutdown
1637            ;;
1638    *)
1639            echo "Update failed, continuing anyway" &gt;/dev/console 2&gt;&amp;1
1640            ;;
1641    esac
1642    fi
1643 </programlisting>
1644           </listitem>
1645         </orderedlist></para>
1646     </sect2>
1647   </sect1>
1648
1649   <sect1 id="HDRWQ448">
1650     <title>Running the package program</title>
1651
1652     <para>After you have created and compiled prototype files and modified client machines, you are ready to run the <emphasis
1653     role="bold">package</emphasis> program. It is probably most convenient to run the <emphasis role="bold">package</emphasis>
1654     program automatically at reboot by invoking it in the machine's AFS initialization file, but you can also issue the command at
1655     the command shell prompt.</para>
1656
1657     <para>The configuration file must be completely correct. If there are any syntax errors or incorrect values, the program exits
1658     without executing any instruction. To check the configuration file, issue the <emphasis role="bold">package</emphasis> command
1659     with the <emphasis role="bold">-noaction</emphasis> and <emphasis role="bold">-debug</emphasis> flags at the command shell
1660     prompt. They display a list of potential problems without actually executing instructions.</para>
1661
1662     <para>The <emphasis role="bold">package</emphasis> program follows these general rules. Complete explanations are in <link
1663     linkend="HDRWQ429">Package Configuration File Instruction Syntax</link>. <itemizedlist>
1664         <listitem>
1665           <para>The <emphasis role="bold">package</emphasis> program does not delete any files from the disk unless the <emphasis
1666           role="bold">R</emphasis> update code was specified in the prototype file. If the <emphasis role="bold">R</emphasis> update
1667           code is associated with the parent directory, the <emphasis role="bold">package</emphasis> program removes anything from
1668           the local disk directory that is not specified in the configuration file.</para>
1669         </listitem>
1670
1671         <listitem>
1672           <para>Local files are updated only if they are out of date. For each <emphasis role="bold">F</emphasis> instruction in the
1673           configuration file, the <emphasis role="bold">package</emphasis> program compares the time of the local file with the
1674           indicated source file. If the source file is newer than the local, the file is updated.</para>
1675         </listitem>
1676
1677         <listitem>
1678           <para>When the initialization file is modified as recommended in <link linkend="HDRWQ447">Modifying Client
1679           Machines</link>, the <emphasis role="bold">package</emphasis> program reboots the workstation automatically if any files
1680           marked with the <emphasis role="bold">Q</emphasis> update code are updated, and if the <emphasis
1681           role="bold">package</emphasis> program has been invoked from the initialization file. When a file marked with the
1682           <emphasis role="bold">Q</emphasis> update code is changed, the <emphasis role="bold">package</emphasis> program exits with
1683           status code 4, causing a reboot (as directed in the initialization file). Files that require a reboot before changes are
1684           recognized (such as the operating system kernel and <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> files) must
1685           be marked with a <emphasis role="bold">Q</emphasis> update code in the configuration file.</para>
1686         </listitem>
1687
1688         <listitem>
1689           <para>The <emphasis role="bold">package</emphasis> program copies the configuration file it has just used to <emphasis
1690           role="bold">/etc/package.</emphasis>sysname, where sysname reflects this machine's system type. The <emphasis
1691           role="bold">package</emphasis> command interpreter consults this file if you do not provide a configuration file name. To
1692           be sure that it configures the local disk as you wish, review its contents.</para>
1693         </listitem>
1694       </itemizedlist></para>
1695
1696     <sect2 id="Header_533">
1697       <title>To invoke the package program by rebooting</title>
1698
1699       <orderedlist>
1700         <listitem>
1701           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
1702           the <emphasis role="bold">su</emphasis> command. <programlisting>
1703    % <emphasis role="bold">su root</emphasis>
1704    Password: &lt;<replaceable>root_password</replaceable>&gt;
1705 </programlisting></para>
1706         </listitem>
1707
1708         <listitem>
1709           <para><emphasis role="bold">(Recommended)</emphasis> Verify the following: <itemizedlist>
1710               <listitem>
1711                 <para>The <emphasis role="bold">/.package</emphasis> file identifies the desired configuration file</para>
1712               </listitem>
1713
1714               <listitem>
1715                 <para>The <emphasis role="bold">package</emphasis> binary is available as <emphasis
1716                 role="bold">/etc/package</emphasis></para>
1717               </listitem>
1718
1719               <listitem>
1720                 <para>The initialization file is properly modified to invoke the <emphasis role="bold">package</emphasis> program
1721                 automatically</para>
1722               </listitem>
1723             </itemizedlist></para>
1724         </listitem>
1725
1726         <listitem>
1727           <para>Reboot the machine, using the appropriate command. <programlisting>
1728    # <emphasis role="bold">shutdown</emphasis>
1729 </programlisting></para>
1730         </listitem>
1731       </orderedlist>
1732
1733       <indexterm>
1734         <primary>commands</primary>
1735
1736         <secondary>package</secondary>
1737       </indexterm>
1738
1739       <indexterm>
1740         <primary>package command</primary>
1741       </indexterm>
1742     </sect2>
1743
1744     <sect2 id="Header_534">
1745       <title>To invoke the package program directly (without rebooting)</title>
1746
1747       <orderedlist>
1748         <listitem>
1749           <para>Become the local superuser <emphasis role="bold">root</emphasis> on the machine, if you are not already, by issuing
1750           the <emphasis role="bold">su</emphasis> command. <programlisting>
1751    % <emphasis role="bold">su root</emphasis>
1752    Password: &lt;<replaceable>root_password</replaceable>&gt;
1753 </programlisting></para>
1754         </listitem>
1755
1756         <listitem>
1757           <para>Verify the following: <itemizedlist>
1758               <listitem>
1759                 <para>The <emphasis role="bold">/.package</emphasis> file identifies the desired configuration file</para>
1760               </listitem>
1761
1762               <listitem>
1763                 <para>The <emphasis role="bold">package</emphasis> binary is available as <emphasis
1764                 role="bold">/etc/package</emphasis></para>
1765               </listitem>
1766
1767               <listitem>
1768                 <para>The initialization file is properly modified to invoke the <emphasis role="bold">package</emphasis> program
1769                 automatically</para>
1770               </listitem>
1771             </itemizedlist></para>
1772         </listitem>
1773
1774         <listitem>
1775           <para>Issue the <emphasis role="bold">package</emphasis> command. <programlisting>
1776    # <emphasis role="bold">package</emphasis>  [<emphasis role="bold">initcmd</emphasis>]  [<emphasis role="bold">-config</emphasis> &lt;<replaceable>base name of configuration file</replaceable>&gt;]  \
1777     [<emphasis role="bold">-fullconfig</emphasis> &lt;<replaceable>full name of configuration file, or stdin for standard input</replaceable>&gt;]  \
1778     [<emphasis role="bold">-overwrite</emphasis>]  [<emphasis role="bold">-noaction</emphasis>]  [<emphasis role="bold">-verbose</emphasis>]  [<emphasis
1779                 role="bold">-silent</emphasis>] [<emphasis role="bold">-rebootfiles</emphasis>]
1780 </programlisting></para>
1781
1782           <para>where <variablelist>
1783               <varlistentry>
1784                 <term><emphasis role="bold">-config</emphasis></term>
1785
1786                 <listitem>
1787                   <para>Specifies the full pathname of the configuration file to use, ending in the file's base name, which omits
1788                   the suffix that indicates the machine type. The <emphasis role="bold">package</emphasis> program knows how to
1789                   determine a machine's type, and automatically selects the appropriate version of the base file name. An example of
1790                   the proper value for this argument is <emphasis role="bold">staff</emphasis> rather than <emphasis
1791                   role="bold">staff.rs_aix42</emphasis>. You can also have the <emphasis role="bold">package</emphasis> program
1792                   refer to <emphasis role="bold">/.package</emphasis> to learn the configuration file name by providing the
1793                   following value:</para>
1794
1795                   <para><emphasis role="bold">`cat /.package`</emphasis></para>
1796
1797                   <para>Use either this argument or the <emphasis role="bold">-fullconfig</emphasis> argument.</para>
1798                 </listitem>
1799               </varlistentry>
1800
1801               <varlistentry>
1802                 <term><emphasis role="bold">-fullconfig</emphasis></term>
1803
1804                 <listitem>
1805                   <para>Specifies the full name of the configuration file to use, complete with the machine-type extension. Examples
1806                   are <emphasis role="bold">staff.rs_aix42</emphasis> and <emphasis role="bold">minimal.hp_ux110</emphasis>
1807                   files.</para>
1808
1809                   <para>Another possibility is the string <emphasis role="bold">stdin</emphasis>, which indicates that the issuer is
1810                   providing configuration information via the standard input stream, either as a piped file or by typing the
1811                   configuration file at the keyboard. Press &lt;<emphasis role="bold">Ctrl-d</emphasis>&gt; to conclude the
1812                   input.</para>
1813
1814                   <para>Use either this argument or the <emphasis role="bold">-config</emphasis> argument.</para>
1815                 </listitem>
1816               </varlistentry>
1817
1818               <varlistentry>
1819                 <term><emphasis role="bold">-overwrite</emphasis></term>
1820
1821                 <listitem>
1822                   <para>Overwrite elements on the local disk with the source version indicated in the configuration file, even if
1823                   the first (owner) <emphasis role="bold">w</emphasis> (<emphasis role="bold">write</emphasis>) mode bit is turned
1824                   off on the local disk copy of the file. Files protected by the <emphasis role="bold">I</emphasis> update code are
1825                   not overwritten; see the definition for the <emphasis role="bold">F</emphasis> instruction.</para>
1826                 </listitem>
1827               </varlistentry>
1828
1829               <varlistentry>
1830                 <term><emphasis role="bold">-noaction</emphasis></term>
1831
1832                 <listitem>
1833                   <para>Displays on the standard output stream a trace of potential problems in running the command, rather than
1834                   actually running it. If the <emphasis role="bold">-verbose</emphasis> flag is added, the trace also notes the
1835                   actions the <emphasis role="bold">package</emphasis> program attempts.</para>
1836                 </listitem>
1837               </varlistentry>
1838
1839               <varlistentry>
1840                 <term><emphasis role="bold">-silent</emphasis></term>
1841
1842                 <listitem>
1843                   <para>Explicitly invokes the default level of tracing, which includes only a list of problems encountered while
1844                   executing the command.</para>
1845                 </listitem>
1846               </varlistentry>
1847
1848               <varlistentry>
1849                 <term><emphasis role="bold">-verbose</emphasis></term>
1850
1851                 <listitem>
1852                   <para>Produces a detailed trace of the program's actions on the standard output stream. The trace records on the
1853                   transfer and ownership/mode bit setting of each element in the configuration file.</para>
1854                 </listitem>
1855               </varlistentry>
1856
1857               <varlistentry>
1858                 <term><emphasis role="bold">-rebootfiles</emphasis></term>
1859
1860                 <listitem>
1861                   <para>Prevents the overwrite of any element marked with the <emphasis role="bold">Q</emphasis> update-mode code in
1862                   the configuration file. This effectively prevents the machine from rebooting automatically again when the
1863                   <emphasis role="bold">package</emphasis> program is invoked from an initialization file.</para>
1864                 </listitem>
1865               </varlistentry>
1866             </variablelist></para>
1867         </listitem>
1868
1869         <listitem>
1870           <para>If you think files marked with the <emphasis role="bold">Q</emphasis> update code were updated, reboot the machine.
1871           This reboot does not occur automatically.</para>
1872         </listitem>
1873       </orderedlist>
1874     </sect2>
1875   </sect1>
1876 </chapter>