Package Configuration File Instruction Syntax

Within a library file, configuration file instructions are used to define the specific disk configuration. Each instruction can be used to define a file, directory, socket, or device on the client machine. The syntax for each valid instruction type is described briefly here; detailed descriptions of the fields appear in the OpenAFS Command Reference Manual.

Note

Each configuration instruction must appear on a single, unbroken line. Instructions sometimes appear here on multiple lines only for legibility.

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.

Local Files versus Symbolic Links

You can take advantage of the AFS by keeping the number of files on the local client disk to a minimum; instead, create symbolic links that point into AFS. This can improve machine performance by allowing more space for caching and swapping.

Some files, however, must reside on the local disk, as described below. Create these files in the prototype or library files using the F (file) instruction, not the L (symbolic link) instruction.

The following types of files must reside on the local disk of all AFS clients:

  • Boot sequence files executed before the afsd program runs.

    Until afsd runs and initializes the Cache Manager, AFS is inaccessible from the client. Any files that are executed before the afsd program runs must reside on the local client disk.

    For example, on a machine that uses a disk cache, the /usr/vice/cache directory must exist when you bring up the Cache Manager, so that there is a location to create cache files. The binary files /etc/mount and /etc/umount must be available on the local disk as the machine boots in order to mount the /usr/vice/cache directory.

    In addition, certain UNIX files, such as initialization files (/etc/rc or equivalent) and file system mapping files (/etc/fstab or equivalent), must reside on the local disk.

  • Diagnostic and recovery files

    Certain commands can be used to diagnose and recover from problems caused by a file server outage. It is best to keep copies of the binaries for these commands on the local disk. For example, store the bos and fs binaries in the /usr/vice/etc directory on the local disk, as well as in the /usr/afsws directory (which in the conventional configuration is a symbolic link into AFS). Then, set PATH variables so that the /usr/afsws directory appears before the /usr/vice/etc directory. Thus, even if users cannot access AFS (for example, due to a file server outage) they can still access copies of the bos and fs binaries in the /usr/vice/etc directory on the local disk.

  • Files in the /usr/vice directory

    The contents of the /usr/vice directory, including the cache files in the cache subdirectory and the configuration files in the etc subdirectory, must reside on the local disk. For a description of the files in the directory, see Configuration and Cache-Related Files on the Local Disk.

Defining a Directory

The D instruction defines a directory to be created 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.

Use the following instruction to define a directory:

D[update_code]   directory   owner   group   mode_bits

The following example defines the /usr directory:

   D /usr root wheel 755

Defining a File

The F instruction defines a file to be created on the local disk. The source file can reside in either AFS or the local disk.

If a file of this name already exists, then it is updated with (overwritten by) the source file, unless the I update code is specified. If a symbolic link or directory of this name exists, the package program replaces it with the source file.

Note

Some files must reside on the local disk; they cannot be symbolic links. See Local Files versus Symbolic Links.

Use the following instruction to define a file:

F[update_code]   file   source_file  [owner   group   mode_bits]

An example which creates/updates the file /bin/grep on the local disk, using /afs/abc.com/rs_aix42/bin/grep as the source:

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

In the following example, two update codes are used, and the owner, group and mode_bits slots are left empty, so that the disk file adopts the source file's values for those slots.

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

Defining a Symbolic Link

The L instruction defines a symbolic link to be created on the local disk. The symbolic link can point to the AFS file system or the local disk. If the identical symbolic link already exists, the package program does nothing. However, if an element of the same name exists on the disk as a file or directory, the package program replaces the element with a symbolic link.

Note

Some files must reside on the local disk; they cannot be symbolic links. See Local Files versus Symbolic Links.

Use the following instruction to define a symbolic link:

L[update_code]  link actual_file  [owner   group   mode_bits]

Note

Do not create a symbolic link to a file whose name begins with the number sign (#) or percent sign (%). The Cache Manager interprets such a link as a mount point to a regular or Read/Write volume, respectively.

The following example creates a symbolic link from the /etc/ftpd directory on the local disk to the /afs/abc.com/hp_ux110/etc/ftpd file in AFS. Since the owner, group and mode_bits fields are empty, the symbolic link adopts values for those fields from the actual file:

   L /etc/ftpd /afs/abc.com/hp_ux110 

This example uses the A update code:

   LA /etc/printcap /afs/abc.com/common/etc/printcap.remote 
               root wheel 644

Defining a Block Special Device

The B instruction defines a block special device, which is a device that handles data in units of multibyte blocks, such as a disk. If a device of the same name already exists, the package program replaces it with the specified block device.

Use the following instruction to define a block special device (it appears on two lines here only for legibility):

B device_name   major_device_number   minor_device_number  \
      owner   group   mode_bits

The following example defines a disk called /dev/hd0a to have major and minor device numbers 1 and 0:

   B /dev/hd0a 1 0 root wheel 644

Defining a Character Special Device

The C instruction defines a character special device, which is device that handles data 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 package program replaces it with the specified character device.

Use the following instruction to define a character special device (it appears here on two lines only for legibility):

C device_name   major_device_number   minor_device_number  \
      owner   group   mode_bits

The following example defines the tty called /dev/ttyp5 with major and minor device numbers 6 and 5:

   C /dev/ttyp5 6 5 root wheel 666

Defining a Socket

The S instruction defines a socket, which is communications device for UDP and TCP/IP connections. If a socket of the same name already exists, the package program replaces it.

Use the following instruction to define a socket:

S   socket_name   [owner   group   mode_bits]

The following example defines a socket called /dev/printer:

   S /dev/printer root wheel 777