The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

AFS::BOS - 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]);

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

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

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

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

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 <alfw@slac.stanford.edu>,
Venkata Phani Kiran Achanta <neo_phani@hotmail.com>, and
Norbert E. Gruener <nog@MPA-Garching.MPG.de>

COPYRIGHT AND LICENSE

 Copyright (c) 2005-2012 Norbert E. Gruener <nog@MPA-Garching.MPG.de>
 Copyright (c) 2003-2004 Alf Wachsmann <alfw@slac.stanford.edu>,
                         Venkata Phani Kiran Achanta <neo_phani@hotmail.com>, and
                         Norbert E. Gruener <nog@MPA-Garching.MPG.de>
 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
 Copyright (c) 1991 Transarc Corporation.
 All rights reserved.

 IBM AFS Administration Reference
 Copyright (c) IBM Corporation 2000.
 All rights reserved.

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

DOCUMENT VERSION

Revision $Rev: 1130 $