DESCRIPTION

The boscreate 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 <machinename>
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 <serverprocessname>
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.
runntp
The controller process for the Network Time Protocol Daemon
(obsolete).
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 <servertype>
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 boscreate
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 <commandlines>+
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
bosexec 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 <notifierprogram>
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 <cellname>
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 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.

PRIVILEGEREQUIRED

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

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.