Provided by: openafs-client_1.4.1-2_i386 bug

NAME

       bos create - Defines a new process in the BosConfig file and starts it

SYNOPSIS

       bos create << -server <machine name >>>
           << -instance <server process name >>> << -type <server type >>>
           << -cmd <command lines+ >>> << [-notifier <notifier program] >>>
           << [-cell <cell name] >>> [-noauth] [-localauth] [-help]

       bos c << -s <machine name >>> << -i <server process name >>>
           << -t <server type >>> << -cm <command lines+ >>>
           << [-not <notifier program] >>> << [-ce <cell name] >>> [-noa]
           [-l] [-h]

DESCRIPTION

       The bos create command creates a server process entry in the
       /etc/openafs/BosConfig file on the server machine named by the -server
       argument, sets the process’s status to Run in the BosConfig file and in
       memory, and starts the process.

       A server process’s entry in the BosConfig file defines its name, its
       type, the command that initializes it, and optionally, the name of a
       notifier program that runs when the process terminates.

OPTIONS

       -server <machine name>
           Indicates the server machine on which to define and start the new
           process. Identify the machine by IP address or its host name
           (either fully-qualified or abbreviated unambiguously). For details,
           see the bos(8) manpage.

       -instance <server process name>
           Names the process to define and start. Any name is acceptable, but
           for the sake of simplicity it is best to use the last element of
           the process’s binary file pathname, and to use the same name on
           every server machine. The conventional names, as used in all AFS
           documentation, are:

       buserver
               The Backup Server process.

       fs      The process that combines the File Server, Volume Server, and
               Salvager processes (fileserver, volserver, and salvager).

       kaserver
               The Authentication Server process.

       ptserver
               The Protection Server process.

       runntp  The controller process for the Network Time Protocol Daemon.

       upclientbin
               The client portion of the Update Server process that retrieves
               binary files from the /usr/lib/openafs directory of the binary
               distribution machine for this machine’s CPU/operating system
               type. (The name of the binary is upclient, but the bin suffix
               distinguishes this process from upclientetc.)

       upclientetc
               The client portion of the Update Server process that retrieves
               configuration files from the /etc/openafs/server directory of
               the system control machine. (The name of the binary is
               upclient, but the etc suffix distinguishes this process from
               upclientbin.)

       upserver
               The server portion of the Update Server process.

       vlserver
               The Volume Location (VL) Server process.

       -type <server type>
           Specifies the process’s type. The acceptable values are:

       cron    Use this value for cron-type processes that the BOS Server
               starts only at a defined daily or weekly time, rather than
               whenever it detects that the process has terminated. AFS does
               not define any such processes by default, but makes this value
               available for administrator use. Define the time for command
               execution as part of the -cmd argument to the bos create
               command.

       fs      Use this value only for the fs process, which combines the File
               Server, Volume Server and Salvager processes. If one of the
               component processes terminates, the BOS Server shuts down and
               restarts the processes in the appropriate order.

       simple  Use this value for all processes listed as acceptable values to
               the -instance argument, except for the fs process.  There are
               no interdependencies between simple processes, so the BOS
               Server can stop and start them independently as necessary.

       -cmd <command lines>+
           Specifies each command the BOS Server runs to start the process.
           Specify no more than six commands (which can include the command’s
           options, in which case the entire string is surrounded by double
           quotes); any additional commands are ignored.

           For a simple process, provide the complete pathname of the
           process’s binary file on the local disk (for example,
           /usr/lib/openafs/ptserver for the Protection Server). If including
           any of the initialization command’s options, surround the entire
           command in double quotes (""). The upclient process has a required
           argument, and the commands for all other processes take optional
           arguments.

           For the fs process, provide the complete pathname of the local disk
           binary file for each of the component processes: fileserver,
           volserver, and salvager, in that order. The standard binary
           directory is /usr/lib/openafs.  If including any of an
           initialization command’s options, surround the entire command in
           double quotes ("").

           For a cron process, provide two parameters:

       ·       The complete local disk pathname of either an executable file
               or a command from one of the AFS suites (complete with all of
               the necessary arguments). Surround this parameter with double
               quotes ("") if it contains spaces.

       ·       A specification of when the BOS Server executes the file or
               command indicated by the first parameter. There are three
               acceptable values:

       ·           The string now, which directs the BOS Server to execute the
                   file or command immediately and only once. It is usually
                   simpler to issue the command directly or issue the bos exec
                   command.

       ·           A time of day. The BOS Server executes the file or command
                   daily at the indicated time. Separate the hours and minutes
                   with a colon (hh:MM), and use either 24-hour format, or a
                   value in the range from 1:00 through 12:59 with the
                   addition of am or pm. For example, both 14:30 and "2:30 pm"
                   indicate 2:30 in the afternoon. Surround this parameter
                   with double quotes ("") if it contains a space.

       ·           A day of the week and time of day, separated by a space and
                   surrounded with double quotes (""). The BOS Server executes
                   the file or command weekly at the indicated day and time.
                   For the day, provide either the whole name or the first
                   three letters, all in lowercase letters (sunday or sun,
                   thursday or thu, and so on). For the time, use the same
                   format as when specifying the time alone.

       -notifier <notifier program>
           Specifies the complete pathname on the local disk of a program that
           the BOS Server invokes when the process terminates. The AFS
           distribution does not include any notifier programs, but this
           argument is available for administrator use. See the NOTES manpage.

       -cell <cell name>
           Names the cell in which to run the command. Do not combine this
           argument with the -localauth flag. For more details, see the bos(8)
           manpage.

       -noauth
           Assigns the unprivileged identity anonymous to the issuer. Do not
           combine this flag with the -localauth flag. For more details, see
           the bos(8) manpage.

       -localauth
           Constructs a server ticket using a key from the local
           /etc/openafs/server/KeyFile file. The bos command interpreter
           presents the ticket to the BOS Server during mutual authentication.
           Do not combine this flag with the -cell or -noauth options. For
           more details, see the bos(8) manpage.

       -help
           Prints the online help for this command. All other valid options
           are ignored.

EXAMPLES

       The following command defines and starts the simple process kaserver on
       the machine fs3.abc.com:

          % bos create -server fs3.abc.com -instance kaserver -type simple \
                       -cmd /usr/lib/openafs/kaserver

       The following command defines and starts the simple process upclientbin
       on the machine fs4.abc.com. It references fs1.abc.com as the source for
       updates to binary files, checking for changes to the /usr/lib/openafs
       directory every 120 seconds.

          % bos create -server fs4.abc.com -instance upclientbin -type simple \
                       -cmd "/usr/lib/openafs/upclient fs1.abc.com -clear -t 120 \
                       /usr/lib/openafs"

       The following command creates the fs process fs on the machine
       fs4.abc.com. Type the command on a single line.

          % bos create -server fs4.abc.com -instance fs -type fs \
                       -cmd /usr/lib/openafs/fileserver /usr/lib/openafs/volserver \
                       /usr/lib/openafs/salvager

       The following command creates a cron process called userbackup on the
       machine fs5.abc.com, so that the BOS Server issues the indicated vos
       backupsys command each day at 3:00 a.m. (the command creates a backup
       version of every volume in the file system whose name begins with
       user). Note that the issuer provides the complete pathname to the vos
       command, includes the -localauth flag on it, and types the entire bos
       create command on one line.

          % bos create -server fs5.abc.com -instance userbackup -type cron  \
              -cmd "/usr/lib/openafs/vos backupsys -prefix user -localauth" 03:00

PRIVILEGE REQUIRED

       The issuer must be listed in the /etc/openafs/server/UserList file on
       the machine named by the -server argument, or must be logged onto a
       server machine as the local superuser root if the -localauth flag is
       included.

NOTES

       If the -notifier argument is included when this command is used to
       define and start a process, the BOS Server invokes the indicated
       notifier program when the process exits. The intended use of a notifier
       program is to inform administrators when a process exits unexpectedly,
       but it can be used to perform any appropriate actions.  The following
       paragraphs describe the bnode and bnode_proc structures in which the
       BOS Server records information about the exiting process.

       The BOS Server constructs and sends on the standard output stream one
       bnode and one bnode_proc structure for each exiting process associated
       with the notifier program. It brackets each structure with appropriate
       BEGIN and END statements (BEGIN bnode and END bnode, BEGIN bnode_proc
       and END bnode_proc), which immediately follow the preceding newline
       character with no intervening spaces or other characters. If the
       notifier program does not need information from a structure, it can
       scan ahead in the input stream for the END statement.

       In general, each field in a structure is a string of ASCII text
       terminated by the newline character. The format of the information
       within a structure possibly varies slightly depending on the type of
       process associated with the notifier program.

       The C code for the bnode and bnode_proc structures follows. Note that
       the structures sent by the BOS Server do not necessarily include all of
       the fields described here, because some are used only for internal
       record keeping. The notifier process must robustly handle the absence
       of expected fields, as well as the presence of unexpected fields, on
       the standard input stream.

       For proper performance, the notifier program must continue processing
       the input stream until it detects the end-of-file (EOF). The BOS Server
       closes the standard input file descriptor to the notifier process when
       it has completed delivery of the data, and it is the responsibility of
       the notifier process to terminate properly.

       struct bnode contents:

          struct bnode {
             struct bnode *next;      /* next pointer in top-level’s list */
             char *name;              /* instance name */
             long nextTimeout;        /* next time this guy should be awakened */
             long period;             /* period between calls */
             long rsTime;             /* time we started counting restarts */
             long rsCount;            /* count of restarts since rsTime */
             struct bnode_type *type; /* type object */
             struct bnode_ops *ops;   /* functions implementing bnode class */
             long procStartTime;      /* last time a process was started */
             long procStarts;         /* number of process starts */
             long lastAnyExit;        /* last time a process exited for any reason */
             long lastErrorExit;      /* last time a process exited unexpectedly */
             long errorCode;          /* last exit return code */
             long errorSignal;        /* last proc terminating signal */
             char *lastErrorName;     /* name of proc that failed last */
             short refCount;          /* reference count */
             short flags;             /* random flags */
             char goal;               /* 1=running or 0=not running */
             char fileGoal;           /* same, but to be stored in file */
       };

       Format of struct bnode explosion:

          printf("name: %s\n",tp->name);
          printf("rsTime: %ld\n", tp->rsTime);
          printf("rsCount: %ld\n", tp->rsCount);
          printf("procStartTime: %ld\n", tp->procStartTime);
          printf("procStarts: %ld\n", tp->procStarts);
          printf("lastAnyExit: %ld\n", tp->lastAnyExit);
          printf("lastErrorExit: %ld\n", tp->lastErrorExit);
          printf("errorCode: %ld\n", tp->errorCode);
          printf("errorSignal: %ld\n", tp->errorSignal);
          printf("lastErrorName: %s\n", tp->lastErrorName);
          printf("goal: %d\n", tp->goal);

       struct bnode_proc contents:

          struct bnode_proc {
             struct bnode_proc *next; /* next guy in top-level’s list */
             struct bnode *bnode;     /* bnode creating this process */
             char *comLine;           /* command line used to start this process */
             char *coreName;          /* optional core file component name */
             long pid;                /* pid if created */
             long lastExit;           /* last termination code */
             long lastSignal;         /* last signal that killed this guy */
             long flags;              /* flags giving process state */
       };

       Format of struct bnode_proc explosion:

          printf("comLine: %s\n", tp->comLine);
          printf("coreName: %s\n", tp->coreName);
          printf("pid: %ld\n", tp->pid);
          printf("lastExit: %ld\n", tp->lastExit);
          printf("lastSignal: %ld\n", tp->lastSignal);

SEE ALSO

       the BosConfig(5) manpage, the KeyFile(5) manpage, the UserList(5)
       manpage, the bos(8) manpage, the buserver(8) manpage, the fileserver(8)
       manpage, the kaserver(8) manpage, the ptserver(8) manpage, the
       salvager(8) manpage, the upclient(8) manpage, the upserver(8) manpage,
       the vlserver(8) manpage, the volserver(8) manpage, the vos_backupsys(1)
       manpage

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.
       It was converted from HTML to POD by software written by Chas Williams
       and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.