man AFS::BOS (3): Class to communicate with the AFS Basic Overseer Server

SYNOPSIS

use AFS::BOS;
my $bos = AFS::BOS->new('server');
my $ok = $bos->addhost('hostname');
my ($cell, $hosts) = $bos->listhosts;
$ok = $bos->removehost('hostname');
$bos->DESTROY; # destroy server connection
$bos = AFS::BOS->new('server');
$ok = $bos->addkey(11, 'My Secret');
my ($date, $keys) = $bos->listkeys;
$ok = $bos->removekey([10, 11]);
$ok = $bos->adduser('username');
my @users = $bos->listusers;
$ok = $bos->removeuser('username');
my ($generalTime, $newBinaryTime) = $bos->getrestart;
my ($general, $newbinary, $time) = (1, 0, 'sat 4:00');
$ok = $bos->setrestart($time, $general, $newbinary);
$ok = $bos->startup;
my $status = $bos->status;
$ok = $bos->shutdown;
$ok = $bos->start(['vlserver']);
$ok = $bos->restart(['fs', 'vlserver']);
$ok = $bos->restart_bos;
$ok = $bos->restart_all;
$ok = $bos->stop(['vlserver']);
my $restricted = $bos->getrestricted;
$ok = $bos->setrestricted('on');
$ok = $bos->create('kaserver', 'simple', ['/usr/afs/bin/kaserver']);
$ok = $bos->delete('instance');
$ok = $bos->exec('/sbin/shutdown -r now');
my @logentries = $bos->getlog('FileLog');
my ($all, $bak, $old, $core) = (0, 0, 0, 1);
$ok = $bos->prune($all, $bak, $old, $core);
$ok = $bos->salvage('/vicepa');
$ok = $bos->setauth('on');
$ok = $bos->setcellname('newcell.example.com');

DESCRIPTION

This class is used to communicate with a AFS Basic Overseer Server, which runs on every AFS server machine. It monitors and administers the other server processes on that machine. It has also methods to maintain system configuration files.

Before you can submit any tasks to a Basic OverSeer (BOS) Server you must establish a connection to a BOS Server. This is done by the constructor method new which returns a BOS object. A BOS object is essentially a handle to talk to a Basic OverSeer Server on a given server machine. Such a BOS object is required before any of the other BOS instance methods can be called.

COMPATIBILITY

There was no version 1 implementation and hence there are no version conflicts :-)

METHODS

CONSTRUCTOR

$bos = AFS::BOS->new(SERVER [, NOAUTH [, LOCALAUTH [, CELL [, ENCRYPT]]]]);

Creates a new object of the class AFS::BOS and establishes a connection to the Basic Overseer Server running on the SERVER machine. An AFS::BOS object is essentially a handle to talk to the Basic Overseer Server. Internally an AFS::BOS object is a pointer to a rx_connection structure, although this may change and the value returned from AFS::BOS::new should always be treaded as an opaque handle.

Set LOCALAUTH (default 0) to 1 only when issuing a command on a server machine. If NOAUTH is 1 (default 0) it establishes an unauthenticated connection to the server, in which the server treats the issuer as an unprivileged user. CELL (default NULL) specifies the cell in which to run the command. Set ENCRYPT (default 1) to 0 if you want to use an unencrypted connection. HANDLE WITH CARE!

DESTRUCTOR

$bos->DESTROY;

Destroys the connection to the Basic Overseer Server and frees the rx_connection structure.

INSTANCE METHODS

$ok = $bos->addhost(HOST [, CLONE]);

$ok = $bos->addhost(\@HOST [, CLONE]);

NOT YET RELEASED

Adds the given HOST to the local "CellServDB" file. HOST is either a scalar value or a reference to an array of hosts. If CLONE is set to 1 (default 0) the ubik vote of this host does not count. This argument is only available under OpenAFS. It calls the AFS system library function BOZO_AddCellHost.

$ok = $bos->addkey(KVNO [, STRING]);

NOT YET RELEASED

Constructs a server encryption key from the text STRING provided, assigns it the key version number KVNO, and adds it to the local "KeyFile" file. If STRING is omitted, the BOS Server prompts for the string and does not echo it visibly. It calls the AFS system library function BOZO_AddKey.

$ok = $bos->adduser(USER);

$ok = $bos->adduser(\@USER);

NOT YET RELEASED

Adds the given USER to the list of privileged users in the local "UserList" file. USER is either a scalar value or a reference to an array of names. It calls the AFS system library function BOZO_AddSUser.

$ok = $bos->create(PROCESS, TYPE, COMMAND [, NOTIFIER]);

$ok = $bos->create(PROCESS, TYPE, \@COMMAND [, NOTIFIER]);

Creates a server PROCESS entry in the local "BosConfig" file on the server machine, sets the process's status to Run in the "BosConfig" file and in memory, and starts the process. TYPE specifies the process's type. Acceptable values are: 'simple', 'cron', and 'fs'. COMMAND is either a scalar value or an array reference containing the commands the BOS Server should run to start the process. NOTIFIER specifies the complete pathname of a program that the BOS Server invokes when the process terminates. It calls the AFS system library function BOZO_CreateBnode.

$ok = $bos->delete(INSTANCE);

$ok = $bos->delete(\@INSTANCE);

Deletes the entry INSTANCE from the local "BosConfig" file. INSTANCE is either a scalar value or a reference to an array of instance names.

Before using this method, issue the stop method to stop the process and set its status flag in the BosConfig file to NotRun. The delete method fails with an error message if a process's status flag is Run. It calls the AFS system library function BOZO_DeleteBnode.

$ok = $bos->exec(COMMAND);

Executes the indicated COMMAND on the BOS server machine. It calls the AFS system library function BOZO_Exec.

@logfile = $bos->getlog(LOGFILE);

Returns an array with the contents of the specified LOGFILE from the BOS server. It calls the AFS system library function StartBOZO_GetLog.

($GTIME, $BTIME) = $bos->getrestart;

Returns the restart times GTIME and BTIME from the local "BosConfig" file. GTIME is the general restart time at which the BOS Server process automatically restarts itself. BTIME is the binary restart time at which the BOS Server automatically restarts any process for which the time stamp on the binary file in the local "/usr/afs/bin" directory is later than the last restart time for the process. It calls the AFS system library function BOZO_GetRestartTime.

$restricted = $bos->getrestricted;

Returns the current restricted mode of the BOS server. Return value 1 means restriced mode enabled, 0 means disabled. This method is only available under OpenAFS if the AFS system libraries were compiled with the Restricted Mode Option. It calls the AFS system library function BOZO_GetRestrictedMode.

($CELL, $HOSTS) = $bos->listhosts;

Returns the name of the CELL and an array reference HOSTS containing the list of database server machines. It calls the AFS system library function BOZO_Listhost.

You can find an example how to print the entire content of the array reference $HOSTS in the "examples/v2/bos" directory.

my($DATE, $KEYS) = $bos->listkeys([SHOW]);

Returns the DATE when a key was last added to the local "KeyFile" file and the hash reference KEYS containing the server encryption keys. The hash keys are the key version numbers. Set SHOW to 1 (default 0) to see the octal digits that constitute each key. It calls the AFS system library function BOZO_Listkeys.

You can find an example how to print the entire content of the hash reference $KEYS in the "examples/v2/bos" directory.

@users = $bos->listusers;

Returns an array containing a list of the privileged users from the local "UserList" file. It calls the AFS system library function BOZO_ListSUsers.

$ok = $bos->prune([All [,BAK [, OLD [, CORE]]]]);

Removes files from the local disk of the server machine.

Set BAK to 1 (default 0) to remove all files from the local "/usr/afs/bin" directory that have a "BAK" extension.

Set OLD to 1 (default 0) to remove all files from the local "/usr/afs/bin" directory that have an "OLD" extension.

Set CORE to 1 (default 0) to remove all files from the local "/usr/afs/logs" directory that have a "core" prefix.

Set ALL to 1 (default 0) to remove all three types of files at once.

If none of these flags are set, no files are removed, but a warning message is displayed. It calls the AFS system library function BOZO_Prune.

$ok = $bos->removehost(HOST);

$ok = $bos->removehost(\@HOST);

NOT YET RELEASED

Removes the database server machine HOST from the local "CellServDB" file. HOST is either a scalar value or a reference to an array of names. It calls the AFS system library function BOZO_DeleteCellHost.

$ok = $bos->removekey(KVNO);

$ok = $bos->removekey(\@KVNO);

NOT YET RELEASED

Removes the server encryption key with the given key version number KVNO from the local "KeyFile" file. KVNO is either a scalar value or a reference to an array of key version numbers. It calls the AFS system library function BOZO_DeleteKey.

$ok = $bos->removeuser(USER);

$ok = $bos->removeuser(\@USER);

NOT YET RELEASED

Removes the privileged USER from the local "UserList" file. USER is either a scalar value or a reference to an array of users. It calls the AFS system library function BOZO_DeleteSuser.

$ok = $bos->restart_bos;

Stops and immediately restarts all AFS server processes, including the BOS Server. A new BOS Server starts immediately, and it starts a new instance of each process that is marked with the run status flag.

It calls the AFS system library function BOZO_ReBozo.

$ok = $bos->restart_all;

Stops and immediately restarts all AFS server processes, except the BOS Server, that are marked with the run status flag.

It calls the AFS system library function BOZO_RestartAll.

$ok = $bos->restart(SERVER);

$ok = $bos->restart(\@SERVER);

Stops and immediately restarts the SERVER processes on the server machine, regardless of its run status flag. SERVER is either a scalar value or a reference to an array of server names.

It calls the AFS system library function BOZO_Restart.

$ok = $bos->salvage([PARTITION] ...));

NOT YET RELEASED

??? The argument list must be completed CORRECTLY !!!

Salvages (restores internal consistency to) one or more volumes on the file server machine

??? Here must be a COMPLETE description of all arguments !!!

If your file server runs MR-AFS, a bunch of additional boolean options are supported: debug, nowrite, force, oktozap, rootfiles, salvagedirs, blockreads, ListResidencies, SalvageRemote, SalvageArchival, IgnoreCheck, ForceOnLine, UseRootDirACL, TraceBadLinkCounts, DontAskFS, LogLevel, rxdebug, Residencies.

Internally, a temporary cron job is created via 'BOZO_CreateBnode>.

$ok = $bos->setauth('on' | 'off');

Enables ('on') or disables('off') authorization checking for all server processes on the server machine. It calls the AFS system library function BOZO_SetNoAuthFlag.

$ok = $bos->setcellname(NAME);

NOT YET RELEASED

Establishes the cell's NAME and makes the server machine a member of it. And it records the NAME in the two local files "ThisCell" and "CellServDB". It calls the AFS system library function BOZO_SetCellName.

Cautions

Use this method only when installing the cell's first AFS server machine. The AFS Quick Beginnings documentation explains how to copy over the "ThisCell" and "CellServDB" files from this or another appropriate machine during installation of additional server machines.

$ok = $bos->setrestart(TIME [, GENERAL [, NEWBINARY]]);

NOT YET RELEASED

Sets the restart TIME at which the BOS Server restarts processes. Set GENERAL to 1 (default 0) to set the restart time of the BOS Server to TIME. This TIME is once per week. Set NEWBINARY to 1 (default 0) to set the binary restart time. The TIME is once per day. Only one of the arguments GENERAL and NEWBINARY can be set. It calls the AFS system library function BOZO_SetRestartTime.

$ok = $bos->setrestricted(MODE);

Enables (MODE = 1) or disables (MODE = 0) the restricted mode for the BOS server which disables certain bosserver functionality. This method is only available under OpenAFS if the AFS system libraries were compiled with the Restricted Mode Option. It calls the AFS system library function BOZO_SetRestrictedMode.

$ok = $bos->shutdown([SERVER, ] [WAIT]);

$ok = $bos->shutdown([\@SERVER, ] [WAIT]);

Stops on the server machine either all running server processes, excluding the BOS server process or the SERVER process. SERVER is either a scalar value or a reference to an array of process names. It does not change its status flag in the local "BosConfig" file but only in the BOS Server's memory. Set WAIT to 1 (default 0) to delay the program flow until all processes actually stop. Otherwise the method returns almost immediately even if all processes are not stopped. It calls the AFS system library function BOZO_WaitAll.

$ok = $bos->start(SERVER);

$ok = $bos->start(\@SERVER);

Sets the status flag for each SERVER process to Run in the local "BosConfig" file and in the BOS Server's memory on the server machine, then starts it. If the SERVER process is already running, the only effect is to guarantee that the status flag is Run; it does not restart the process. SERVER is either a scalar value or a reference to an array of process names. It calls the AFS system library function BOZO_SetStatus.

$ok = $bos->startup([SERVER]);

$ok = $bos->startup([\@SERVER]);

Starts on the server machine either all server processes not currently running but marked with the run status flag in the local "BosConfig" file or the process SERVER even if its status flag in the "BosConfig" file is NotRun. SERVER is either a scalar value or a reference to an array of process names. The run status flag in the local "BosConfig" file will not be changed. It calls the AFS system library function BOZO_StartupAll or BOZO_SetTStatus.

$STATUS = $bos->status([LONG [, SERVER]]);

$STATUS = $bos->status([LONG [, \@SERVER]]);

Returns the STATUS of either all server processes listed in the local "BosConfig" file or the process SERVER. SERVER is either a scalar value or a reference to an array of process names. STATUS is a hash reference containing the current process status. Set LONG to 1 (default 0) to get extended information about the process status. It calls the AFS system library function BOZO_GetStatus.

You can find an example how to print the entire content of the hash reference $STATUS in the "examples/v2/bos" directory.

$ok = $bos->stop(SERVER [, WAIT]);

$ok = $bos->stop(\@SERVER [, WAIT]);

Sets the status flag for each SERVER process to NotRun in the local "BosConfig" file on the server machine, then stops it. SERVER is either a scalar value or a reference to an array of process names. Set WAIT to 1 (default 0) to delay the program flow until all processes actually stop. Otherwise the method returns almost immediately even if all processes are not stopped. It calls the AFS system library function .

AUTHORS

The code and documentation for this class were contributed by Stanford Linear Accelerator Center, a department of Stanford University. This documentation were written by

Alf Wachsmann <[email protected]>,
Venkata Phani Kiran Achanta <[email protected]>, and
Norbert E. Gruener <[email protected]>

COPYRIGHT AND DISCLAIMER

 X 2005-2006 Norbert E. Gruener <[email protected]>
 X 2003-2004 Alf Wachsmann <[email protected]>,
             Venkata Phani Kiran Achanta <[email protected]>, and
             Norbert E. Gruener <[email protected]>
 All rights reserved.
 Most of the explanations in this document are taken from the original
 AFS documentation.
 AFS-3 Programmer's Reference:
 BOS Server Interface
 Edward R. Zayas
 X 1991 Transarc Corporation.
 All rights reserved.
 IBM AFS Administration Reference
 X IBM Corporation 2000.
 All rights reserved.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

DOCUMENT VERSION

Revision $Rev: 772 $

SYNOPSIS

DESCRIPTION

COMPATIBILITY

METHODS

AUTHORS

COPYRIGHT AND DISCLAIMER

DOCUMENT VERSION

LAST SEARCHED