Provided by: openafs-client_1.8.0~pre5-1ubuntu1.2_amd64 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.

CAUTIONS

       A server process entry of type fs as described below will not work with a demand-attach
       File Server, and a server process entry of type dafs for a demand-attach File Server will
       not work with a traditional File Server. When switching from one File Server
       implementation to another, remove the existing server process entry and create a new one.
       See "EXAMPLES" below for an example of switching from a traditional File Server to a
       demand-attach File Server.

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 bos(8).

       -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
           (or the instance type for fs and dafs), 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.

           dafs
               The process that combines the Demand Attach File Server, Volume Server,
               Salvageserver and Salvager processes (dafileserver, davolserver, salvageserver,
               and dasalvager).

           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.

           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.

           dafs
               Use this value only for the dafs process, which combines the File Server, Volume
               Server, Salvage Server, and Salvager processes in order to operate as a Demand
               Attach File Server.  If one of the component processes terminates, the BOS Server
               shuts down and restarts the process in the appropriate order.

           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 and dafs processes.  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 the dafs process, provide the complete pathname of the local disk binary file for
           each of the component processes: dafileserver, davolserver, salvageserver, and
           dasalvager, 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 "NOTES".

       -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 bos(8).

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

       -localauth
           Constructs a server ticket using a key from the local /etc/openafs/server/KeyFile or
           /etc/openafs/server/KeyFileExt 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 bos(8).

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

EXAMPLES

       The following command defines and starts the simple process "ptserver" on the machine
       "fs3.example.com":

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

       The following command defines and starts the simple process "upclientbin" on the machine
       "fs4.example.com". It references "fs1.example.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.example.com -instance upclientbin -type simple \
                       -cmd "/usr/lib/openafs/upclient fs1.example.com -clear -t 120 \
                       /usr/lib/openafs"

       The following command creates the fs process "fs" on the machine "fs4.example.com" (a
       traditional File Server with associated processes). Type the command on a single line.

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

       The following command creates the dafs process "dafs" on the machine "fs4.example.com" (a
       demand-attach File Server with associated processes).  Type the command on a single line.

          % bos create -server fs4.example.com -instance dafs -type dafs \
                       -cmd /usr/lib/openafs/dafileserver \
                       /usr/lib/openafs/davolserver \
                       /usr/lib/openafs/salvageserver /usr/lib/openafs/dasalvager

       The following command creates a cron process called "userbackup" on the machine
       "fs5.example.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.example.com -instance userbackup -type cron  \
              -cmd "/usr/lib/openafs/vos backupsys -prefix user -localauth" 03:00

       To switch from a traditional File Server to a demand-attach File Server, run:

          % bos status localhost -instance fs -long

       to see the current fileserver and volserver flags for an existing traditional File Server
       configuration. (Substitute the "dafs" instance for an existing demand-attach File Server.)
       Then, run:

          % bos stop localhost fs -localauth
          % bos delete localhost fs -localauth
          % bos create localhost dafs dafs \
              "/usr/lib/openafs/dafileserver <fileserver-flags>" \
              "/usr/lib/openafs/davolserver <volserver-flags>" \
              /usr/lib/openafs/salvageserver /usr/lib/openafs/dasalvager

       replacing <fileserver-flags> and <volserver-flags> with the flags from the previous
       configuration. This will stop the traditional File Server and start a demand-attach File
       Server. The binaries at the paths provided must already be updated to binaries built with
       demand-attach enabled.

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.

       The bos create command cannot be run against servers which are in restricted mode.

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

       BosConfig(5), KeyFile(5), KeyFileExt(5), UserList(5), bos(8), buserver(8),
       dafileserver(8), dasalvager(8), davolserver(8), fileserver(8), kaserver(8), ptserver(8),
       salvager(8), salvageserver(8), upclient(8), upserver(8), vlserver(8), volserver(8),
       vos_backupsys(1)

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.