Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
BOS_CREATE(8)		     AFS Command Reference		 BOS_CREATE(8)

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
       /usr/local/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.

	   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/local/libexec/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 /usr/local/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/local/libexec/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/local/libexec/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/local/libexec/openafs.  If
	   including any of an initialization command's	options, surround the
	   entire command in double quotes ("").

	   For a cron process, provide two parameters:

	   o   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.

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

	       o   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.

	       o   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.

	       o   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
	   /usr/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.

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

	  % bos	create -server fs3.abc.com -instance ptserver -type simple \
		       -cmd /usr/local/libexec/openafs/ptserver

       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/local/libexec/openafs directory every 120 seconds.

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

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

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

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

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

       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/local/libexec/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/local/libexec/openafs/dafileserver <fileserver-flags>" \
	      "/usr/local/libexec/openafs/davolserver <volserver-flags>" \
	      /usr/local/libexec/openafs/salvageserver /usr/local/libexec/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	/usr/local/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), 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.

OpenAFS				  2016-12-14			 BOS_CREATE(8)

NAME | SYNOPSIS | DESCRIPTION | CAUTIONS | OPTIONS | EXAMPLES | PRIVILEGE REQUIRED | NOTES | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=bos_create&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help