Section: AFS Command Reference (8)
Updated: OpenAFS


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


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] 


The bos create command creates a server process entry in the/usr/afs/local/BosConfig file on the server machine named by the-server argument, sets the process's status to Run in theBosConfig file and in memory, and starts the process.

A server process's entry in the BosConfig file defines its name, itstype, the command that initializes it, and optionally, the name of anotifier program that runs when the process terminates. 


-server <machine name>
Indicates the server machine on which to define and start the newprocess. Identify the machine by IP address or its host name (eitherfully-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 thesake of simplicity it is best to use the last element of the process'sbinary file pathname, and to use the same name on every servermachine. The conventional names, as used in all AFS documentation, are:
The Backup Server process.
The process that combines the File Server, Volume Server, and Salvagerprocesses (fileserver, volserver, and salvager).
The Authentication Server process.
The Protection Server process.
The controller process for the Network Time Protocol Daemon.
The client portion of the Update Server process that retrieves binaryfiles from the /usr/afs/bin directory of the binary distributionmachine for this machine's CPU/operating system type. (The name of thebinary is upclient, but the bin suffix distinguishes this processfrom upclientetc.)
The client portion of the Update Server process that retrievesconfiguration files from the /usr/afs/etc directory of the systemcontrol machine. (The name of the binary is upclient, but the etcsuffix distinguishes this process from upclientbin.)
The server portion of the Update Server process.
The Volume Location (VL) Server process.
-type <server type>
Specifies the process's type. The acceptable values are:
Use this value for cron-type processes that the BOS Server starts only ata defined daily or weekly time, rather than whenever it detects that theprocess has terminated. AFS does not define any such processes by default,but makes this value available for administrator use. Define the time forcommand execution as part of the -cmd argument to the bos createcommand.
Use this value only for the fs process, which combines the File Server,Volume Server and Salvager processes. If one of the component processesterminates, the BOS Server shuts down and restarts the processes in theappropriate order.
Use this value for all processes listed as acceptable values to the-instance argument, except for the fs process. There are nointerdependencies between simple processes, so the BOS Server can stop andstart them independently as necessary.
-cmd <command lines>+
Specifies each command the BOS Server runs to start the process. Specifyno more than six commands (which can include the command's options, inwhich case the entire string is surrounded by double quotes); anyadditional commands are ignored.

For a simple process, provide the complete pathname of the process'sbinary file on the local disk (for example, /usr/afs/bin/ptserver forthe Protection Server). If including any of the initialization command'soptions, surround the entire command in double quotes (""). Theupclient process has a required argument, and the commands for allother processes take optional arguments.

For the fs process, provide the complete pathname of the local disk binaryfile for each of the component processes: fileserver, volserver, andsalvager, in that order. The standard binary directory is/usr/afs/bin. 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 commandfrom one of the AFS suites (complete with all of the necessaryarguments). Surround this parameter with double quotes ("") if itcontains spaces.
A specification of when the BOS Server executes the file or commandindicated by the first parameter. There are three acceptable values:
The string now, which directs the BOS Server to execute the file orcommand immediately and only once. It is usually simpler to issue thecommand directly or issue the bos exec command.
A time of day. The BOS Server executes the file or command daily at theindicated 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:00through 12:59 with the addition of am or pm. For example, both14:30 and "2:30 pm" indicate 2:30 in the afternoon. Surround thisparameter with double quotes ("") if it contains a space.
A day of the week and time of day, separated by a space and surroundedwith double quotes (""). The BOS Server executes the file or commandweekly at the indicated day and time. For the day, provide either thewhole name or the first three letters, all in lowercase letters (sundayor sun, thursday or thu, and so on). For the time, use the sameformat as when specifying the time alone.
-notifier <notifier program>
Specifies the complete pathname on the local disk of a program that theBOS Server invokes when the process terminates. The AFS distribution doesnot include any notifier programs, but this argument is available foradministrator use. See the NOTES manpage.
-cell <cell name>
Names the cell in which to run the command. Do not combine this argumentwith the -localauth flag. For more details, see the bos(8) manpage.
Assigns the unprivileged identity anonymous to the issuer. Do notcombine this flag with the -localauth flag. For more details, seethe bos(8) manpage.
Constructs a server ticket using a key from the local/usr/afs/etc/KeyFile file. The bos command interpreter presents theticket to the BOS Server during mutual authentication. Do not combine thisflag with the -cell or -noauth options. For more details, seethe bos(8) manpage.
Prints the online help for this command. All other valid options areignored.


The following command defines and starts the simple processkaserver on the machine

   % bos create -server -instance kaserver -type simple \                -cmd /usr/afs/bin/kaserver
The following command defines and starts the simple process upclientbinon the machine It references as the sourcefor updates to binary files, checking for changes to the /usr/afs/bindirectory every 120 seconds.

   % bos create -server -instance upclientbin -type simple \                -cmd "/usr/afs/bin/upclient -clear -t 120 \                /usr/afs/bin"
The following command creates the fs process fs on the Type the command on a single line.

   % bos create -server -instance fs -type fs \                -cmd /usr/afs/bin/fileserver /usr/afs/bin/volserver \                /usr/afs/bin/salvager
The following command creates a cron process called userbackup on themachine, so that the BOS Server issues the indicated vosbackupsys command each day at 3:00 a.m. (the command creates a backupversion of every volume in the file system whose name begins withuser). Note that the issuer provides the complete pathname to thevos command, includes the -localauth flag on it, and types theentire bos create command on one line.

   % bos create -server -instance userbackup -type cron  \       -cmd "/usr/afs/bin/vos backupsys -prefix user -localauth" 03:00


The issuer must be listed in the /usr/afs/etc/UserList file on themachine named by the -server argument, or must be logged onto a servermachine as the local superuser root if the -localauth flag isincluded. 


If the -notifier argument is included when this command is used todefine and start a process, the BOS Server invokes the indicatednotifier program when the process exits. The intended use of a notifierprogram is to inform administrators when a process exits unexpectedly, butit can be used to perform any appropriate actions. The followingparagraphs describe the bnode and bnode_proc structures in which theBOS Server records information about the exiting process.

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

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

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

For proper performance, the notifier program must continue processing theinput stream until it detects the end-of-file (EOF). The BOS Server closesthe standard input file descriptor to the notifier process when it hascompleted delivery of the data, and it is the responsibility of thenotifier 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);


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 


IBM Corporation 2000. <> All Rights Reserved.

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




This document was created byman2html,using the manual pages.