Command Reference Manual

bos create

Purpose

Defines a new process in the /usr/afs/local/BosConfig file and starts it running

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 /usr/afs/local/BosConfig file on the server machine specified 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

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 introductory reference page for the bos command suite.

-instance

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/afs/bin 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 /usr/afs/etc directory of the system control machine. Do not run this process in cells that use the international edition of AFS. (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

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

Specifies each command the BOS Server runs to start the process.

For a simple process, provide the complete pathname of the process's binary file on the local disk (for example, /usr/afs/bin/ptserver for the Protection Server). If including arguments to the initialization command, surround the entire command in double quotes (""); the upclient binary 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/afs/bin. If including any of an initialization command's optional arguments, surround the 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 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

Specifies the complete pathname on the local disk of a program that the BOS Server executes when the process terminates. AFS does not include any notifier programs, but makes this argument available for administrator use. For additional information, see the notes on notifier programs in the Related Information section.

-cell

Names the cell in which to run the command. Do not combine this argument with the -localauth flag. For more details, see the introductory bos reference page.

-noauth

Assigns the unprivileged identity anonymous to the issuer. Do not combine this flag with the -localauth flag. For more details, see the introductory bos reference page.

-localauth

Constructs a server ticket using a key from the local /usr/afs/etc/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 introductory bos reference page.

-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/afs/bin/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/afs/bin directory every 120 seconds.

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

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/afs/bin/fileserver /usr/afs/bin/volserver /usr/afs/bin/salvager

The following command creates the cronprocess 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/afs/bin/vos backupsys -prefix user -localauth" 03:00

Privilege Required

The issuer must be listed in the /usr/afs/etc/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.

Related Information

Related Information

This section provides information for writing a notifier program. It is meant for use by developers of notifier programs.

The format of the input to the notifier program possibly varies slightly depending on the type of process to which the notifier program is attached. In general, the format is one line of ASCII for each field in the bnode and bnode_proc structures, terminated by a new line. Each structure is preceded and followed by tokens identifying the enclosed data; BEGIN struct bnode and END struct bnode, which immediately follow the preceding new line with no intervening spaces or other characters. If the notifier program is not prepared to parse a particular structure, it can simply scan ahead in the input stream for the END token.

Below is the C code that explodes the data structures. Some of the fields are not printed out, either because they are not used by the bos command or because they are used only for internal record keeping.

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);

The BOS Server closes the standard input file descriptor to the notifier process when it has completed delivery of the data. It is the responsibility of the notifier process to terminate. The notifier process must robustly handle the presence of unexpected data structure contents on the standard input stream, and read input data until EOF is detected.