doc/man-pages/pod8/bos_create.pod

   1 =head1 NAME
   2
   3 bos create - Defines a new process in the BosConfig file and starts it
   4
   5 =head1 SYNOPSIS
   6
   7 B<bos create> B<-server> <I<machine name>>
   8     B<-instance> <I<server process name>> B<-type> <I<server type>>
   9     B<-cmd> <I<command lines>>+ [B<-notifier> <I<notifier program>>]
  10     [B<-cell> <I<cell name>>] [B<-noauth>] [B<-localauth>] [B<-help>]
  11
  12 B<bos c> B<-s> <I<machine name>> B<-i> <I<server process name>>
  13     B<-t> <I<server type>> B<-cm> <I<command lines>>+
  14     [B<-not> <I<notifier program>>] [B<-ce> <I<cell name>>] [B<-noa>]
  15     [B<-l>] [B<-h>]
  16
  17 =head1 DESCRIPTION
  18
  19 The B<bos create> command creates a server process entry in the
  20 F</usr/afs/local/BosConfig> file on the server machine named by the
  21 B<-server> argument, sets the process's status to C<Run> in the
  22 F<BosConfig> file and in memory, and starts the process.
  23
  24 A server process's entry in the F<BosConfig> file defines its name, its
  25 type, the command that initializes it, and optionally, the name of a
  26 notifier program that runs when the process terminates.
  27
  28 =head1 OPTIONS
  29
  30 =over 4
  31
  32 =item B<-server> <I<machine name>>
  33
  34 Indicates the server machine on which to define and start the new
  35 process. Identify the machine by IP address or its host name (either
  36 fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
  37
  38 =item B<-instance> <I<server process name>>
  39
  40 Names the process to define and start. Any name is acceptable, but for the
  41 sake of simplicity it is best to use the last element of the process's
  42 binary file pathname, and to use the same name on every server
  43 machine. The conventional names, as used in all AFS documentation, are:
  44
  45 =over 4
  46
  47 =item buserver
  48
  49 The Backup Server process.
  50
  51 =item fs
  52
  53 The process that combines the File Server, Volume Server, and Salvager
  54 processes (B<fileserver>, B<volserver>, and B<salvager>).
  55
  56 =item kaserver
  57
  58 The Authentication Server process.
  59
  60 =item ptserver
  61
  62 The Protection Server process.
  63
  64 =item runntp
  65
  66 The controller process for the Network Time Protocol Daemon.
  67
  68 =item upclientbin
  69
  70 The client portion of the Update Server process that retrieves binary
  71 files from the F</usr/afs/bin> directory of the binary distribution
  72 machine for this machine's CPU/operating system type. (The name of the
  73 binary is B<upclient>, but the C<bin> suffix distinguishes this process
  74 from C<upclientetc>.)
  75
  76 =item upclientetc
  77
  78 The client portion of the Update Server process that retrieves
  79 configuration files from the F</usr/afs/etc> directory of the system
  80 control machine. (The name of the binary is B<upclient>, but the C<etc>
  81 suffix distinguishes this process from C<upclientbin>.)
  82
  83 =item upserver
  84
  85 The server portion of the Update Server process.
  86
  87 =item vlserver
  88
  89 The Volume Location (VL) Server process.
  90
  91 =back
  92
  93 =item B<-type> <I<server type>>
  94
  95 Specifies the process's type. The acceptable values are:
  96
  97 =over 4
  98
  99 =item cron
 100
 101 Use this value for cron-type processes that the BOS Server starts only at
 102 a defined daily or weekly time, rather than whenever it detects that the
 103 process has terminated. AFS does not define any such processes by default,
 104 but makes this value available for administrator use. Define the time for
 105 command execution as part of the B<-cmd> argument to the B<bos create>
 106 command.
 107
 108 =item fs
 109
 110 Use this value only for the fs process, which combines the File Server,
 111 Volume Server and Salvager processes. If one of the component processes
 112 terminates, the BOS Server shuts down and restarts the processes in the
 113 appropriate order.
 114
 115 =item simple
 116
 117 Use this value for all processes listed as acceptable values to the
 118 B<-instance> argument, except for the B<fs> process.  There are no
 119 interdependencies between simple processes, so the BOS Server can stop and
 120 start them independently as necessary.
 121
 122 =back
 123
 124 =item B<-cmd> <I<command lines>>+
 125
 126 Specifies each command the BOS Server runs to start the process.  Specify
 127 no more than six commands (which can include the command's options, in
 128 which case the entire string is surrounded by double quotes); any
 129 additional commands are ignored.
 130
 131 For a simple process, provide the complete pathname of the process's
 132 binary file on the local disk (for example, F</usr/afs/bin/ptserver> for
 133 the Protection Server). If including any of the initialization command's
 134 options, surround the entire command in double quotes (C<"">). The
 135 B<upclient> process has a required argument, and the commands for all
 136 other processes take optional arguments.
 137
 138 For the fs process, provide the complete pathname of the local disk binary
 139 file for each of the component processes: B<fileserver>, B<volserver>, and
 140 B<salvager>, in that order. The standard binary directory is
 141 F</usr/afs/bin>.  If including any of an initialization command's options,
 142 surround the entire command in double quotes (C<"">).
 143
 144 For a cron process, provide two parameters:
 145
 146 =over 4
 147
 148 =item *
 149
 150 The complete local disk pathname of either an executable file or a command
 151 from one of the AFS suites (complete with all of the necessary
 152 arguments). Surround this parameter with double quotes (C<"">) if it
 153 contains spaces.
 154
 155 =item *
 156
 157 A specification of when the BOS Server executes the file or command
 158 indicated by the first parameter. There are three acceptable values:
 159
 160 =over 4
 161
 162 =item *
 163
 164 The string C<now>, which directs the BOS Server to execute the file or
 165 command immediately and only once. It is usually simpler to issue the
 166 command directly or issue the B<bos exec> command.
 167
 168 =item *
 169
 170 A time of day. The BOS Server executes the file or command daily at the
 171 indicated time. Separate the hours and minutes with a colon (I<hh:MM>),
 172 and use either 24-hour format, or a value in the range from C<1:00>
 173 through C<12:59> with the addition of C<am> or C<pm>. For example, both
 174 C<14:30> and C<"2:30 pm"> indicate 2:30 in the afternoon. Surround this
 175 parameter with double quotes (C<"">) if it contains a space.
 176
 177 =item *
 178
 179 A day of the week and time of day, separated by a space and surrounded
 180 with double quotes (C<"">). The BOS Server executes the file or command
 181 weekly at the indicated day and time. For the day, provide either the
 182 whole name or the first three letters, all in lowercase letters (C<sunday>
 183 or C<sun>, C<thursday> or C<thu>, and so on). For the time, use the same
 184 format as when specifying the time alone.
 185
 186 =back
 187
 188 =back
 189
 190 =item B<-notifier> <I<notifier program>>
 191
 192 Specifies the complete pathname on the local disk of a program that the
 193 BOS Server invokes when the process terminates. The AFS distribution does
 194 not include any notifier programs, but this argument is available for
 195 administrator use. See L<NOTES>.
 196
 197 =item B<-cell> <I<cell name>>
 198
 199 Names the cell in which to run the command. Do not combine this argument
 200 with the B<-localauth> flag. For more details, see L<bos(8)>.
 201
 202 =item B<-noauth>
 203
 204 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
 205 combine this flag with the B<-localauth> flag. For more details, see
 206 L<bos(8)>.
 207
 208 =item B<-localauth>
 209
 210 Constructs a server ticket using a key from the local
 211 F</usr/afs/etc/KeyFile> file. The B<bos> command interpreter presents the
 212 ticket to the BOS Server during mutual authentication. Do not combine this
 213 flag with the B<-cell> or B<-noauth> options. For more details, see
 214 L<bos(8)>.
 215
 216 =item B<-help>
 217
 218 Prints the online help for this command. All other valid options are
 219 ignored.
 220
 221 =back
 222
 223 =head1 EXAMPLES
 224
 225 The following command defines and starts the simple process
 226 C<kaserver> on the machine C<fs3.abc.com>:
 227
 228    % bos create -server fs3.abc.com -instance kaserver -type simple \
 229                 -cmd /usr/afs/bin/kaserver
 230
 231 The following command defines and starts the simple process C<upclientbin>
 232 on the machine C<fs4.abc.com>. It references C<fs1.abc.com> as the source
 233 for updates to binary files, checking for changes to the F</usr/afs/bin>
 234 directory every 120 seconds.
 235
 236    % bos create -server fs4.abc.com -instance upclientbin -type simple \
 237                 -cmd "/usr/afs/bin/upclient fs1.abc.com -clear -t 120 \
 238                 /usr/afs/bin"
 239
 240 The following command creates the fs process fs on the machine
 241 C<fs4.abc.com>. Type the command on a single line.
 242
 243    % bos create -server fs4.abc.com -instance fs -type fs \
 244                 -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \
 245                 /usr/afs/bin/salvager
 246
 247 The following command creates a cron process called C<userbackup> on the
 248 machine C<fs5.abc.com>, so that the BOS Server issues the indicated B<vos
 249 backupsys> command each day at 3:00 a.m. (the command creates a backup
 250 version of every volume in the file system whose name begins with
 251 C<user>). Note that the issuer provides the complete pathname to the
 252 B<vos> command, includes the B<-localauth> flag on it, and types the
 253 entire B<bos create> command on one line.
 254
 255    % bos create -server fs5.abc.com -instance userbackup -type cron  \
 256        -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00
 257
 258 =head1 PRIVILEGE REQUIRED
 259
 260 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
 261 machine named by the B<-server> argument, or must be logged onto a server
 262 machine as the local superuser C<root> if the B<-localauth> flag is
 263 included.
 264
 265 =head1 NOTES
 266
 267 If the B<-notifier> argument is included when this command is used to
 268 define and start a process, the BOS Server invokes the indicated
 269 I<notifier program> when the process exits. The intended use of a notifier
 270 program is to inform administrators when a process exits unexpectedly, but
 271 it can be used to perform any appropriate actions.  The following
 272 paragraphs describe the bnode and bnode_proc structures in which the
 273 BOS Server records information about the exiting process.
 274
 275 The BOS Server constructs and sends on the standard output stream one
 276 bnode and one bnode_proc structure for each exiting process associated
 277 with the notifier program. It brackets each structure with appropriate
 278 C<BEGIN> and C<END> statements (C<BEGIN bnode> and C<END bnode>, C<BEGIN
 279 bnode_proc> and C<END bnode_proc>), which immediately follow the preceding
 280 newline character with no intervening spaces or other characters. If the
 281 notifier program does not need information from a structure, it can scan
 282 ahead in the input stream for the C<END> statement.
 283
 284 In general, each field in a structure is a string of ASCII text terminated
 285 by the newline character. The format of the information within a structure
 286 possibly varies slightly depending on the type of process associated with
 287 the notifier program.
 288
 289 The C code for the bnode and bnode_proc structures follows. Note that the
 290 structures sent by the BOS Server do not necessarily include all of the
 291 fields described here, because some are used only for internal record
 292 keeping. The notifier process must robustly handle the absence of expected
 293 fields, as well as the presence of unexpected fields, on the standard
 294 input stream.
 295
 296 For proper performance, the notifier program must continue processing the
 297 input stream until it detects the end-of-file (EOF). The BOS Server closes
 298 the standard input file descriptor to the notifier process when it has
 299 completed delivery of the data, and it is the responsibility of the
 300 notifier process to terminate properly.
 301
 302 struct bnode contents:
 303
 304    struct bnode {
 305       struct bnode *next;      /* next pointer in top-level's list */
 306       char *name;              /* instance name */
 307       long nextTimeout;        /* next time this guy should be awakened */
 308       long period;             /* period between calls */
 309       long rsTime;             /* time we started counting restarts */
 310       long rsCount;            /* count of restarts since rsTime */
 311       struct bnode_type *type; /* type object */
 312       struct bnode_ops *ops;   /* functions implementing bnode class */
 313       long procStartTime;      /* last time a process was started */
 314       long procStarts;         /* number of process starts */
 315       long lastAnyExit;        /* last time a process exited for any reason */
 316       long lastErrorExit;      /* last time a process exited unexpectedly */
 317       long errorCode;          /* last exit return code */
 318       long errorSignal;        /* last proc terminating signal */
 319       char *lastErrorName;     /* name of proc that failed last */
 320       short refCount;          /* reference count */
 321       short flags;             /* random flags */
 322       char goal;               /* 1=running or 0=not running */
 323       char fileGoal;           /* same, but to be stored in file */
 324 };
 325
 326 Format of struct bnode explosion:
 327
 328    printf("name: %s\n",tp->name);
 329    printf("rsTime: %ld\n", tp->rsTime);
 330    printf("rsCount: %ld\n", tp->rsCount);
 331    printf("procStartTime: %ld\n", tp->procStartTime);
 332    printf("procStarts: %ld\n", tp->procStarts);
 333    printf("lastAnyExit: %ld\n", tp->lastAnyExit);
 334    printf("lastErrorExit: %ld\n", tp->lastErrorExit);
 335    printf("errorCode: %ld\n", tp->errorCode);
 336    printf("errorSignal: %ld\n", tp->errorSignal);
 337    printf("lastErrorName: %s\n", tp->lastErrorName);
 338    printf("goal: %d\n", tp->goal);
 339
 340 struct bnode_proc contents:
 341
 342    struct bnode_proc {
 343       struct bnode_proc *next; /* next guy in top-level's list */
 344       struct bnode *bnode;     /* bnode creating this process */
 345       char *comLine;           /* command line used to start this process */
 346       char *coreName;          /* optional core file component name */
 347       long pid;                /* pid if created */
 348       long lastExit;           /* last termination code */
 349       long lastSignal;         /* last signal that killed this guy */
 350       long flags;              /* flags giving process state */
 351 };
 352
 353 Format of struct bnode_proc explosion:
 354
 355    printf("comLine: %s\n", tp->comLine);
 356    printf("coreName: %s\n", tp->coreName);
 357    printf("pid: %ld\n", tp->pid);
 358    printf("lastExit: %ld\n", tp->lastExit);
 359    printf("lastSignal: %ld\n", tp->lastSignal);
 360
 361 =head1 SEE ALSO
 362
 363 L<BosConfig(5)>,
 364 L<KeyFile(5)>,
 365 L<UserList(5)>,
 366 L<bos(8)>,
 367 L<buserver(8)>,
 368 L<fileserver(8)>,
 369 L<kaserver(8)>,
 370 L<ptserver(8)>,
 371 L<salvager(8)>,
 372 L<upclient(8)>,
 373 L<upserver(8)>,
 374 L<vlserver(8)>,
 375 L<volserver(8)>,
 376 L<vos_backupsys(1)>
 377
 378 =head1 COPYRIGHT
 379
 380 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 381
 382 This documentation is covered by the IBM Public License Version 1.0.  It was
 383 converted from HTML to POD by software written by Chas Williams and Russ
 384 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.