view release on metacpan or  search on metacpan

lib/AFS/Command/BOS.pod  view on Meta::CPAN

=head1 METHODS -- Inherited

All of the following methods are inherited from the AFS::Command::Base
class.  See that documentation for details.

=over

=item new

=item errors

=item supportsOperation

=item supportsArgument

=back

=head1 METHODS (with complex return values)

=head2 getdate

=over

=item Arguments

The bos help string is:

    bos getdate: get dates for programs
    Usage: bos getdate -server <machine name> -file <files to check>+ [-dir <destination dir>]
		       [-cell <cell name>] [-noauth] [-localauth]

The corresponding method invocation looks like:

    my $result = $bos->getdate
      (
       # Required arguments
       server			=> $server,
       file			=> $file, # OR [ $file1, $file2, ... ]
       # Optional arguments
       dir			=> $dir,
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
      );

=item Return Values

This method returns an AFS::Object::BosServer object, which
contains one or more generic AFS::Object, one for each file
specified in the arguments.

    my $result = $bos->getdate
      (
       file				=> [ 'bosserver', 'vlserver', 'ptserver' ],
       cell				=> $cell,
      ) || die $bos->errors();

    foreach my $fileobj ( $result->getFiles() ) {
	my ($file,$date) = ($fileobj->file(),$fileobj->date());
	print "File $file has date $date\n";
    }

Each of these objects has the following attributes and methods:

B<AFS::Object::BosServer>

This object is nothing more than a container for the generic objects
for each file.  It has several methods for extracting the file objects:

    Methods			Returns
    -------			-------
    getFileNames()		a list of filenames
    getFiles()			a list of AFS::Object objects
    getFile($filename)		the AFS::Object object for $filename

B<AFS::Object>

The following attributes should always be present:

    Attributes			Values
    ----------			------
    file			fully qualified pathname to the file
    date			last modified timestamp on the file

The following attributes may be present, if there are .BAK or .OLD
versions of the file.

    Attributes			Values
    ----------			------
    bak				last modified timestamp on the .BAK file
    old				last modified timestamp on the .OLD file

=back

=head2 getlog

=over

=item Arguments

The bos help string is:

    bos getlog: examine log file
    Usage: bos getlog -server <machine name> -file <log file to examine>
		      [-cell <cell name>] [-noauth] [-localauth]

The corresponding method invocation looks like:

    my $result = $bos->getlog
      (
       # Required arguments
       server			=> $server,
       file			=> $file,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
       # Enhanced arguments
       redirect			=> $redirect,
      );

lib/AFS/Command/BOS.pod  view on Meta::CPAN

    foreach ( split(/\n+/,$result->log()) ) {
	....
    }

The object has the following attribute:

B<AFS::Object::BosServer>

    Attributes			Values
    ----------			------
    log				Contents of the logfile, or the redirect pathname

If redirect was given, then this attribute is simply same pathname.
If redirect was not given, then the value of this attribute is the
contents of the requested logfile, as a single (potentially huge)
string.

NOTE: Since this method is usually invoked to retrieve one of the AFS
logfiles, which can be enormous on heavily loaded servers that have
not been restarted in a while, use of the redirect option is strongly
encouraged.  If not used, the memory allocated to store the logfile
may be prohibitively large.  Developer beware.

=back

=head2 getrestart

=over

=item Arguments

The bos help string is:

    bos getrestart: get restart times
    Usage: bos getrestart -server <machine name> [-cell <cell name>]
			  [-noauth] [-localauth]

The corresponding method invocation looks like:

    my $result = $bos->getrestart
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
      );

=item Return Values

This method returns an AFS::Object::BosServer object, which
contains two attributes.

    my $result = $bos->getrestart
      (
       server			=> $server,
       cell			=> $cell,
      ) || die $bos->errors();
    print "Binary restart time is " . $result->binaries() . "\n";
    print "Server restart time is " . $result->restart() . "\n";

The object has the following attributes:

B<AFS::Object::BosServer>

    Attributes			Values
    ----------			------
    restart			The server restart time
    binaries			The restart time when there are new, updated binaries

=back

=head2 listhosts

=over

=item Arguments

The bos help string is:

    bos listhosts: get cell host list
    Usage: bos listhosts -server <machine name> [-cell <cell name>]
			 [-noauth] [-localauth]

The corresponding method invocation looks like:

    my $result = $bos->listhosts
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
      );

=item Return Values

This method returns an AFS::Object::BosServer object, which
contains one attribute.

    my $result = $bos->listhosts
      (
       server			=> $server,
       cell			=> $cell,
      ) || die $bos->errors();
    my $hosts = $result->hosts();
    print "Server $server in cell $cell has hosts:\n"
    foreach my $host ( @$hosts ) {
        print "\t$host\n";
    }

The object has the following attributes:

B<AFS::Object::BosServer>

    Attributes			Values
    ----------			------
    hosts			ARRAY reference of hostnames
    cell			Cell name

=back

=head2 listkeys

=over

=item Arguments

The bos help string is:

    bos listkeys: list keys
    Usage: bos listkeys -server <machine name> [-showkey]
			[-cell <cell name>] [-noauth] [-localauth]
    Where: -showkey    show the actual key rather than the checksum

The corresponding method invocation looks like:

    my $result = $bos->listkeys
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       showkey			=> 1,
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
      );

=item Return Values

This method returns an AFS::Object::BosServer object, which
contains one or more AFS::Object objects, each of which
represents a single authentication key on the server.

    my $result = $bos->listkeys
      (
       server			=> $server,
       cell			=> $cell,
      ) || die $bos->errors();
    print "Server $server in cell $cell has the following keys:\n";
    foreach my $key ( $result->getKeys() ) {
	my ($index,$cksum) = ($key->index(),$key->cksum());
	print "\t$index => $cksum\n";
    }

    my $result = $bos->listkeys
      (
       server			=> $server,
       cell			=> $cell,
       showkey			=> 1,
      ) || die $bos->errors();
    print "Server $server in cell $cell has the following keys:\n";
    foreach my $key ( $result->getKeys() ) {
	my ($index,$value) = ($key->index(),$key->value());
	print "\t$index => $cksum\n";
    }

The objects have the following attributes and methods:

B<AFS::Object::BosServer>

    Attributes			Values
    ----------			------
    keychanged			Date the keys were last changed

    Methods			Returns
    -------			-------
    getKeyIndexes()		list of numeric key indexes
    getKeys()			list of AFS::Object objects
    getKey($index)		the AFS::Object object for the key with index $index

B<AFS::Object>

The following attribute is always present:

    Attributes			Values
    ----------			------
    index			Numeric index of the key

The following attribute is present when the 'showkey' argument is given:

    Attributes			Values
    ----------			------
    value			Value of the key, in octal, as a string

The following attribute is present when the 'showkey' argument is B<NOT> given:

    Attributes			Values
    ----------			------
    cksum			Numeric check sum of the key

=back

=head2 listusers

=over

=item Arguments

The bos help string is:

    bos listusers: list super-users
    Usage: bos listusers -server <machine name> [-cell <cell name>]
			 [-noauth] [-localauth]

The corresponding method invocation looks like:

    my $result = $bos->listusers
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       cell			=> $cell,
       noauth			=> 1,
       localauth		=> 1,
      );

=item Return Values

This method returns an AFS::Object::BosServer object, which
contains one attribute.

    my $result = $bos->listusers
      (
       server			=> $server,
       cell			=> $cell,
      ) || die $bos->errors();
    my $users = $result->susers();
    print "Server $server in cell $cell has users:\n"
    foreach my $user ( @$users ) {
        print "\t$user\n";
    }

The object has the following attribute:

B<AFS::Object::BosServer>

    Attributes			Values
    ----------			------
    susers			ARRAY reference of super user names

=back

=head2 status

=over

=item Arguments

The bos help string is:

    bos status: show server instance status
    Usage: bos status -server <machine name> [-instance <server process name>+]
		      [-long] [-cell <cell name>] [-noauth] [-localauth]
    Where: -long       long status

The corresponding method invocation looks like:

    my $result = $bos->status
      (
       # Required arguments
       server			=> $server,
       # Optional arguments
       instance			=> $instance, # OR [ $inst1, $inst2, ... ],
       cell			=> $cell,
       long			=> 1,
       noauth			=> 1,
       localauth		=> 1,
      );

=item Return Values

This method returns an AFS::Object::BosServer object, which
contains one optional attribute, and one or more
AFS::Object::Instance objects, each of which represents a
single instance of a bosserver managed process on the server.

    my $result = $bos->status
      (
       server			=> $server,
       long				=> 1,
      ) || die $bos->errors();
    foreach my $instanceobj ( $result->getInstances() ) {
	my $instance		= $instanceobj->instance();
	my $status			= $instanceobj->status();
	print "Instance $instance has status $status\n";
	foreach my $commandobj ( $instance->getCommands() ) {
	    my $index		= $commandobj->index();
	    my $command		= $commandobj->command();
	    print "\tCmd $index is '$command'\n";
	}
    }

The objects have the following attributes and methods:

B<AFS::Object::BosServer>

The following attribute is only present when "bos status" reports
inappropriate access on directories:

    Attributes			Values
    ----------			------
    access			Boolean, true indicating a potential security problem

The following methods can be used to extract the instance objects:

    Methods			Returns
    -------			-------
    getInstanceNames()		list of instance names
    getInstances()		list of AFS::Object::Instance objects
    getInstance($name)		one AFS::Object::Instance object for the instance $name

B<AFS::Object::Instance>

The following attributes are always present:

    Attributes			Values
    ----------			------
    instance			Name of the instance
    status			Status string (running normally, shutdown, etc.)

The following attribute is always present is the instance is of type
'cron':

    Attributes			Values
    ----------			------
    auxiliary			Auxiliary status (date the next execution)

The following attributes are always available when the 'long' argument
is specified:

    Attributes			Values
    ----------			------
    type			"cron", "simple", or "fs"
    startdate			Date when the process was last started
    startcount			Number of times the process has started,
				since the bosserver was started
    exitdate			Date when the process last exited

The following attributes are optionally available, depending on the
state of the instance, when the 'long' argument is specified:

    Attributes			Values
    ----------			------
    notifier			Path to the notifier application for this instance
    state			"temporarily disabled", or "disabled", or "temporarily enabled"
    errorstop			Boolean, indicating the process was
				"stopped for too many errors"
    core			Boolean, indicating the instance has a core file
    errorexitdate		Date when the process last exited with an error