# Administration Reference

## package Configuration File

Purpose

Provides instructions for the package command

Description

The package configuration file defines the file system elements that the package command creates or alters on the local disk of an AFS client machine it is configuring. Use the -config or -fullconfig argument to the package command to identify the configuration file to use.

Summary of Configuration File Instructions

The configuration file can include one or more instances of each of the following instructions, each on its own line. A more detailed description of each instruction's syntax follows this list.

B
  Defines a block special device, such as a disk, which deals with input in units of multi-byte command blocks

C
  Defines a character special device, such as a terminal or tty, which deals with input in single character units

D
  Creates a directory

F
  Creates or alters a file to match the contents of a specified source file

L
  Creates a symbolic link

S
  Defines a socket, which is a communications device for UDP and TCP/IP connections

%define
  Defines a variable or declares a string as defined

%ifdef
  Specifies an action to perform if a certain string is declared or defined

%ifndef
  Specifies an action to perform if a certain string is not declared or defined

%include
  Includes a library file

%undef
  Declares a string not to be defined, or a variable no longer to have a value

The B and C Instructions for Defining Block and Character Special Devices

The B instruction in a package configuration file defines a block special device, such as a disk, that deals with input in units of multi-byte command blocks. The C instruction defines a character special device, such as a terminal or tty, that deals with input in single character units. They share a common syntax:

       {B | C}   device_name  major_device  minor_device  owner  group  mode_bits

where

B
  Indicates the definition of a block special device. It must be a capital letter.

C
  Indicates the definition of character special device. It must be a capital letter.

device_name
  Names the special device to define. To learn the name format appropriate to the machine's system type, consult the hardware or operating system documentation.

major_device
  Specifies the device's major device number in decimal format. To learn the correct value for the machine's system type, consult the hardware or operating system documentation.

minor_device
  Specifies the device's minor device number in one of hexadecimal, octal, or decimal format. Precede a hexadecimal number with the string 0x (zero and the letter x) or an octal number with a 0 (zero). A number without either prefix is interpreted as a decimal. To learn the correct value for the machine's system type, consult the hardware or operating system documentation.

owner
  Specifies the username or UNIX user ID (UID) of the user to be designated the device's owner in the output from the UNIX ls -l command.

group
  Specifies the group name or UNIX group ID (GID) of the group to be designated the device's group in the output from the UNIX ls -lg command.

mode_bits
  Defines the device's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to combinations of permissions. Examples: 755 corresponds to rwxr-xr-x, and 644 to rw-r--r--.

The D Instruction for Creating a Directory

The D instruction in a package configuration file creates a directory on the local disk. If a symbolic link, file, or other element on the local disk has the same name, it is replaced with a directory. If the directory already exists, its owner, group, and mode bits are changed if necessary to conform with the instruction. The instruction has the following syntax:

       D[update_code]  directory  owner  group  mode_bits

where

D
  Indicates the creation of a directory. It must be a capital letter.

update_code
  Modulates the directory creation instruction. It is optional and follows the letter D directly, without an intervening space. Choose one of the two acceptable values:

  X
    Indicates that the directory is a lost+found directory (used by the fsck program).

  R
    Removes any subdirectory (along its contents) or file that exists in the existing directory on the local disk but for which an instruction does not appear in the configuration file.

directory
  Specifies the full pathname of the directory to create.

owner
  Specifies the username or UNIX user ID (UID) of the user to be designated the directory's owner in the output from the UNIX ls -ld command.

group
  Specifies the name or UNIX group ID (GID) of the group to be designated the directory's group in the output from the UNIX ls -lgd command.

mode_bits
  Defines the directory's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to combinations of permissions. Examples: 755 corresponds to drwxr-xr-x, and 644 to drw-r--r--.

The F Instruction for Creating or Updating a File

The F instruction in a package configuration file creates or updates a file on the local disk by copying in the contents of the indicated source file, which can reside in AFS or on the local disk. If the package command interpreter cannot access the source file, it exits without executing any instruction in the configuration file.

If a file with the same name already exists on disk, the package command overwrites it with the contents of the source file, unless the I update code is used to prevent that. To add a .old extension to the current version of the file, include the O update code. To have the machine reboot automatically after the package program completes, include the Q update code.

If a symbolic link, directory, or other element on the local disk has the same name, it is replaced with the file (a directory's contents are first removed as necessary).

The instruction has the following syntax:

       F[update_code]  file  source_file  [owner  group  mode_bits]

where

F
  Indicates the creation or update of a file. It must be a capital letter.

update_code
  Modulates the file creation instruction. It is optional and follows the letter F directly, without an intervening space. Choose one or more of the four acceptable values, and list them in any order:

  A
    Indicates that the pathname in the source_file field is the complete pathname of the source file, including the filename. If this argument is omitted, the package command appends the pathname in the file field to the pathname in the source_file field to derive the source file's full name. This code allows the source and target filenames to differ.

  I
    Preserves the existing file called file, rather than overwriting it.

  O
    Saves the existing version of the file by appending a .old extension to it.

  Q
    Causes the package command to exit with status code 4 if it overwrites the file. If the standard package-related changes have been made to the machine's AFS initialization file, then status code 4 causes the machine to reboot automatically. Use this code when the machine must reboot if updates to the file are to have any effect (for example, if the operating system file--/vmunix or equivalent--has changed).

file
  Specifies the complete pathname on the local disk of the file to create or update, including the filename as the final element.

source_file
  Specifies the pathname (local or AFS) of the file to copy to the local disk.

  If the A update code is included, specify the source file's complete pathname. Otherwise, the package command derives the source file's full name by appending the file pathname to this pathname. For example, if the A update code is not included and the file /afs/abc.com/rs_aix42/bin/grep is the source file for the /bin/grep binary, the proper value in this field is /afs/abc.com/rs_aix42.

owner
  Specifies the username or UNIX user ID (UID) of the user to be designated the file's owner in the output from the UNIX ls -l command.

  To copy the source file's owner to the target file, leave this field empty. In this case, the group and mode_bits fields must also be empty.

group
  Specifies the name or UNIX group ID (GID) of the group to be designated the file's group in the output from the UNIX ls -lg command.

  To copy the source file's group to the target file, leave this field empty. In this case, the owner and mode_bits fields must also be empty.

mode_bits
  Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to combinations of permissions. Examples: 755 corresponds to rwxr-xr-x, and 644 to rw-r--r--.

  To copy the source file's mode bits to the target file, leave this field empty. In this case, the owner and group fields must also be empty.

The L Instruction for Creating a Symbolic Link

The L instruction in a package configuration file creates a symbolic link on the local disk to a directory or file that exists either in AFS or elsewhere on the local disk. As with the standard UNIX ln -s command, the link is created even if the actual file or directory does not exist.

If a file or directory on the local disk already has the same name, the package command replaces it with a symbolic link.

The instruction has the following syntax:

       L[update_code]  link  actual_path  [owner  group  mode_bits]

where

L
  Indicates the creation of a symbolic link. It must be a capital letter.

update_code
  Modulates the link creation instruction. It is optional and follows the letter L directly, without an intervening space. Choose one or both of the acceptable values, and list them in any order:

  A
    Indicates that the pathname in the actual_path field is the complete pathname of the actual directory or file (including the filename for a file). If this argument is omitted, the package command appends the value in the link field to the pathname in the actual_path field to derive the actual directory or file's full name. This code allows the name of the symbolic link and actual directory or file to differ.

  I
    Preserves the existing symbolic link called link, rather than overwriting it.

link
  Specifies the complete local disk pathname of the symbolic link to create.

actual_path
  Specifies the pathname (local or AFS) of the directory or file to which the link refers. If the A update code is included, specify the directory or file's complete pathname. Otherwise, the package command derives the actual directory or file's full name by appending the value in the link field to this pathname. For example, if the A update code is not included and /etc/ftpd is a symbolic link to the file /afs/abc.com/sun4x_56/etc/ftpd, the proper value in this field is /afs/abc.com/sun4x_56.

  The package command interpreter correctly handles pathnames that begin with the ./ (period, slash) or ../ (two periods, slash) notation, interpreting them relative to the current working directory from which the package command is invoked.

owner
  Specifies the username or UNIX user ID (UID) of the user to be designated the symbolic link's owner in the output from the UNIX ls -l command.

  To designate the issuer of the package command (usually, the local superuser root) as the symbolic link's owner, leave this field empty. In this case, the group and mode_bits fields must also be empty.

group
  Specifies the name or UNIX group ID (GID) of the group to be designated the link's group in the output from the UNIX ls -lg command.

  To have the symbolic link's group match the default group associated with the package command's issuer, leave this field empty. The issuer is usually the local superuser root and the default group is designated in the issuer's entry in the local /etc/passwd file or equivalent. If this field is left empty, the owner and mode_bits fields must also be empty.

mode_bits
  Defines the symbolic link's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to combinations of permissions. Examples: 755 corresponds to rwxr-xr-x, and 644 to rw-r--r--.

  Leaving this field empty sets the symbolic link's mode bits to 777 (rwxrwxrwx). In this case, the owner and group fields must also be empty.

The S Instruction for Creating a Socket

The S instruction in a package configuration file creates a socket (a communications device for UDP or TCP/IP connections) on the local disk. The instruction has the following syntax:

       S  socket [owner  group  mode_bits]

where

S
  Indicates the creation of a socket. It must be a capital letter.

socket
  Names the socket. The proper format depends on the local machine's operating system.

owner
  Specifies the username or UNIX user ID (UID) of the user to be designated the socket's owner in the output from the UNIX ls -l command.

  To designate the issuer of the package command (usually, the local superuser root) as the socket's owner, leave this field empty. In this case, the group and mode_bits fields must also be empty.

group
  Specifies the name or UNIX group ID (GID) of the group to be designated the socket's group in the output from the UNIX ls -lg command.

  To have the symbolic link's group match the default group associated with the package command's issuer, leave this field empty. The issuer is usually the local superuser root and the default group is designated in the issuer's entry in the local /etc/passwd file or equivalent. If this field is left empty, the owner and mode_bits fields must also be empty.

mode_bits
  Defines the socket's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding to combinations of permissions. Examples: 755 corresponds to rwxr-xr-x, and 644 to rw-r--r--.

  Leaving this field empty sets the symbolic link's mode bits to 777 (rwxrwxrwx), modulated by the cell's umask. In this case, the owner and group fields must also be empty.

The %define or %undef Instructions Declaring or Undeclaring a Definition

The %define instruction in a package configuration file declares or defines a variable, depending on its number of arguments:

- If followed by a single argument, it declares that argument to be defined. The argument is then available as a controller when mentioned in %ifdef and %ifndef statements, which evaluate to true and false respectively.

- If followed by two arguments, it defines the second argument as the value of the first. When the first argument appears later in this prototype or other prototype or library files as a variable--surrounded by curly braces and preceded by a dollar sign, as in the example `${variable}`--the package command interpreter substitutes the second argument for it.

The %undef statement negates the effect of a previous %define statement, declaring its argument to be defined no longer, or to have a value no longer if it is a variable.

The syntax for the two types of instruction are as follows:

       %define  declaration
       %define  variable  value
       %undef  declaration
       %undef  variable

where

%define
  Indicates a definition statement.

%undef
  Indicates a statement that negates a definition.

declaration
  Names the string being declared by a %define statement, or negated by an %undef statement.

variable
  Specifies the name of the variable that a %define statement is defining, or an %undef statement is negating.

value
  Specifies the value to substitute for the string in the variable field when it appears in the appropriate format (surrounded by curly braces and preceded by a dollar sign, as in the example `${variable}`), in this or other prototype and library files. It can include one or more words.

The %ifdef and %ifndef Instructions for Specifying a Conditional Action to Perform

The %ifdef instruction in a package configuration file specifies one or more actions to perform if the indicated string has been declared by a single-argument %define statement, or is a variable for which a value has been defined by a two-argument %define statement.

Similarly, the %ifndef instruction specifies one or more actions to perform if the indicated string has not been declared or is a variable without a value, either because no %define statement has defined it or an %undef statement has undefined it.

In both cases, the optional %else statement specifies one or more alternate actions to perform if the first statement evaluates to false. (For an %ifdef statement, the %else statement is executed if the indicated string has never been declared or is a variable without a value, or if an %undef statement has undefined either one; for an %ifndef statement, it is executed if the string has been declared or is a variable with a value.)

It is possible to nest any number of %ifdef and %ifndef statements.

The two types of statement share a common syntax:

       %ifdef | ifndef   declaration
                                      action+
       [%else [declaration]
                      alternate_action+]
       %endif declaration

where

ifdef
  Indicates that the statement evaluates as true if the string in the declaration field is declared or is a variable with a defined value.

ifndef
  Indicates that the statement evaluates as true if the string in the declaration field is not declared or is a variable without a defined value.

declaration
  Specifies the string that must be declared or the variable name that must have a defined value for an %ifdef statement to evaluate as true, which results in the specified action being performed. For an %ifndef statement, the string must not be declared or the variable must have no defined value for the statement to evaluate as true. The first and third occurrences of declaration (the latter following the string %endif) are required. The second occurrence (following the string %else) is optional, serving only to clarify to which %ifdef or %ifndef statement the %else statement belongs.

action
  Specifies each action to perform if the %ifdef or %ifndef statement evaluates as true. Each action must appear on a separate line. Acceptable types of actions are other statements beginning with a percent sign and definition instructions.

alternate_action
  Specifies each action to perform if the %ifdef or %ifndef statement evaluates to false. Each action must appear on a separate line. Acceptable types of actions are other statements beginning with a percent sign and definition instructions.

The %include Instruction for Including a Library File

The %include instruction in a package configuration file includes the contents of the indicated library file in a configuration file that results from the compilation of the prototype file in which the %include instruction appears. It has the following syntax:

       %include  pathname

where

%include
  Indicates a library file include statement.

pathname
  Specifies the complete pathname of the library file to include. It can be in AFS or on the local disk, and can include one or more variables.

Cautions

The configuration file must be completely correct. If there are any syntax errors or incorrect values, the package command interpreter exits without executing any instruction.

Examples

The following example B and C instructions define a disk /dev/hd0a with major and minor device numbers 1 and 0 and mode bits of -rw-r--r--, and a tty /dev/ttyp5 with major and minor device numbers 6 and 5 and mode bits of -rw-rw-rw. In both cases, the owner is root and the owning group wheel.

       B /dev/hd0a 1 0 root wheel 644
       C /dev/ttyp5 6 5 root wheel 666

The following example D instruction creates the local /usr directory with owner root and group wheel and mode bits of drwxr-xr-x. The R update code removes any files and subdirectories that reside in the /usr directory (if it already exists) but do not appear in the configuration file.

       DR /usr root wheel 755

The following example F instruction, appropriate for a machine running AIX 4.2 in the ABC Corporation cell, creates or updates the local disk file /bin/grep, using /afs/abc.com/rs_aix42/bin/grep as the source.

       F /bin/grep /afs/abc.com/rs_aix42 root wheel 755

The next example F instruction creates the /usr/vice/etc/ThisCell file and specifies an absolute pathname for the source file, as indicated by the A update code. The Q code makes the package command return status code 4 as it exits, prompting a reboot of the machine if the standard package-related changes have been made to the machine's AFS initialization file. No values are provided for the owner, group and mode bits, so the file inherits them from the source file.

       FAQ /usr/vice/etc/ThisCell /afs/abc.com/common/etc/ThisCell

The following example L instruction, appropriate for a machine running AIX 4.2 in the ABC Corporation cell, creates a symbolic link from /etc/ftpd on the local disk to the file /afs/abc.com/rs_aix42/etc/ftpd.

       L /etc/ftpd /afs/abc.com/rs_aix42 root wheel 644

The following example S instruction defines the socket /dev/printer.

       S /dev/printer root wheel 777

The following example %define instruction defines the value for the variable `${diskmode}`. This variable is used elsewhere in the template to fill the owner_name, group_name, and mode_bits fields in a D, F, or L instruction.

       %define diskmode root wheel 644

The following example %undef instruction declares the string afsd not to be defined.

       %undef afsd

The following example %ifdef instruction specifies that if the string `rs_aix42` is currently declared, then when the prototype file containing the instruction is compiled the three indicated library files are included. There is no alternate action defined. There must be %define statements earlier in the prototype file to declare rs_aix42 and to assign a value to the `${wsadmin}` variable.

       %ifdef rs_aix42
       %include ${wsadmin}/lib/rs_aix42.readonly
       %include ${wsadmin}/lib/rs_aix42.generic
       %include ${wsadmin}/lib/rs_aix42.generic.dev
       %endif rs_aix42

The following example %ifndef instruction, appropriate for the State University cell, defines `stateu.edu` as the value of the `${cell}` variable if it does not already have a value.

       %ifndef cell
       %define cell stateu.edu
       %endif cell

The following example %include instruction includes the library file base.generic from the lib subdirectory of the directory in which package-related files reside. The `${wsadmin}` variable resolves to an actual pathname (such as /afs/abc.com/wsadmin) during compilation.

       %include ${wsadmin}/lib/base.generic

Related Information

package

© IBM Corporation 2000. All Rights Reserved