doc/man-pages/pod8/package.pod

   1 =head1 NAME
   2
   3 package - Configures files and directories on the local disk
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<package> [I<initcmd>] S<<< [B<-config> <I<base name of configuration file>>] >>>
  11     S<<< [B<-fullconfig> <I<full name of configuration file, or stdin>>] >>>
  12     [B<-overwrite>] [B<-noaction>] [B<-verbose>] [B<-silent>]
  13     [B<-rebootfiles>] [B<-debug>] [B<-help>]
  14
  15 B<package> [B<i>] S<<< [B<-c> <I<base name of configuration file>>] >>>
  16     S<<< [B<-f> <I<full name of configuration file, or stdin>>] >>>
  17     [B<-o>] [B<-n>] [B<-v>] [B<-s>] [B<-r>] [B<-d>] [B<-h>]
  18
  19 =for html
  20 </div>
  21
  22 =head1 DESCRIPTION
  23
  24 The B<package> command configures the machine's local disk to comply with
  25 the instructions in the configuration file named by the B<-config> or
  26 B<-fullconfig> argument.
  27
  28 By default, the package command alters any existing local disk element
  29 whose contents or configuration does not match the element defined in the
  30 configuration file. For example, if a configuration file C<D> instruction
  31 defines a directory that has the same name as a symbolic link on the local
  32 disk, the B<package> command replaces the symbolic link with the
  33 directory. The C<F> and C<L> instructions include an optional
  34 I<update_code> field that alters this behavior.
  35
  36 Also by default, the package command takes no action on elements on the
  37 local disk that are not mentioned in the configuration file. Use the C<D>
  38 instruction's C<R> update code to remove files from the disk directory
  39 that are not mentioned in the configuration file.
  40
  41 Before running the package command, the administrator must create the
  42 template file and other files on the local disk. For instructions, see the
  43 I<IBM AFS Administration Guide>.
  44
  45 It is not possible to configure a remote client machine's disk using this
  46 command.
  47
  48 =head1 CAUTIONS
  49
  50 The package command interpreter exits without executing any instruction if
  51 there are any syntax errors or incorrect values in the configuration file.
  52
  53 =head1 OPTIONS
  54
  55 =over 4
  56
  57 =item [I<initcmd>]
  58
  59 Accommodates the command's use of the AFS command parser, and is optional.
  60
  61 =item B<-config> <I<base name of configuration file>>
  62
  63 Specifies the pathname of the configuration file to use, ending in the
  64 file's base name, which omits the suffix that indicates the machine
  65 type. The B<package> command determines the machine's system type name and
  66 automatically appends it to the base name. An example of the proper value
  67 for this argument is C<staff> rather than C<staff.rs_aix42>. Partial
  68 pathnames are interpreted relative to the current working directory.
  69
  70 Provide this argument or the B<-fullconfig> argument.
  71
  72 =item B<-fullconfig> <I<full name of configuration file, or stdin>>
  73
  74 Specifies the configuration file to use. Two types of values are
  75 acceptable:
  76
  77 =over 4
  78
  79 =item *
  80
  81 The full pathname of the configuration file to use, complete with an
  82 extension indicating the machine type (examples: C<staff.rs_aix42>,
  83 C<admin.sun4x_56>).
  84
  85 =item *
  86
  87 The string C<stdin> to indicate that the issuer is providing configuration
  88 information via the standard input stream, either by piping in the
  89 contents of a file, or by typing configuration lines at the shell.  In the
  90 latter case, type Ctrl-D to conclude the input.
  91
  92 =back
  93
  94 Provide this argument or the B<-config> argument.
  95
  96 =item B<-overwrite>
  97
  98 Overwrites elements on the local disk with the source version indicated in
  99 the configuration file, even if the owner write (C<w>) mode bit is turned
 100 on the disk element. Files protected by the C<I> update code on an C<F>
 101 line in the configuration file are not overwritten.
 102
 103 =item B<-noaction>
 104
 105 Checks the sequence of operations to be performed when the command
 106 actually runs and reports any problems that the B<package> command
 107 interpreter expects to encounter. No elements on the local disk or in AFS
 108 are changed. If the B<-verbose> flag is also provided, the trace includes
 109 all actions to be performed as well as anticipated errors.
 110
 111 =item B<-silent>
 112
 113 Suppresses some of the trace messages sent to the standard output stream
 114 by default. The output still reports major problems.
 115
 116 =item B<-verbose>
 117
 118 Produces on the standard output stream a detailed trace of the command's
 119 execution. If this argument is omitted, only warnings and error messages
 120 appear.
 121
 122 =item B<-rebootfiles>
 123
 124 Prevents overwriting of any file marked with the C<Q> update code on an
 125 C<F> line in the configuration file. This effectively prevents the machine
 126 from rebooting automatically again when the B<package> command is invoked
 127 in the machine's AFS initialization file.
 128
 129 =item B<-debug>
 130
 131 Enables debugging output, which is directed to the standard output stream
 132 by default. By default, no debugging output is produced.
 133
 134 =item B<-help>
 135
 136 Prints the online help for this command. All other valid options are
 137 ignored.
 138
 139 =back
 140
 141 =head1 EXAMPLES
 142
 143 This command is usually invoked in a client machine's AFS initialization
 144 file (F</etc/rc> or equivalent), rather than issued at the command shell
 145 prompt.
 146
 147 The following command invokes the version of the staff configuration file
 148 appropriate for this machine's system type, and produces verbose output.
 149
 150    # /etc/package -c staff -v
 151
 152 The following example uses the configuration file whose basename is
 153 defined in the F</.package> file on the local machine. This method enables
 154 the administrator to use the same B<package> command in every machine's
 155 AFS initialization file but still customize configuration by putting the
 156 appropriate basename in the F</.package> file.
 157
 158    # /etc/package -c `cat /.package` -v
 159
 160 =head1 PRIVILEGE REQUIRED
 161
 162 The issuer must be logged in as the local superuser C<root>.
 163
 164 =head1 SEE ALSO
 165
 166 L<package(5)>
 167
 168 =head1 COPYRIGHT
 169
 170 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 171
 172 This documentation is covered by the IBM Public License Version 1.0.  It was
 173 converted from HTML to POD by software written by Chas Williams and Russ
 174 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.