NAME

Unix::Sysadmin::List - List base class

SYNOPSIS

 use Unix::Sysadmin::List::Host;
 use Unix::Sysadmin::List::User;
 use Unix::Sysadmin::List::Group;
 use Unix::Sysadmin::List::Automount;
 use Unix::Sysadmin::List::Netgroup;

 $ul = Unix::Sysadmin::List::User->new();
 $hl = Unix::Sysadmin::List::Host->new();
 $gl = Unix::Sysadmin::List::Group->new();
 $al = Unix::Sysadmin::List::Automount->new();
 $nl = Unix::Sysadmin::List::Netgroup->new();

 return empty List:: objects of the appropriate type

Or:

 use Unix::Sysadmin::List::Host;
 use Unix::Sysadmin::List::User;
 use Unix::Sysadmin::List::Group;
 use Unix::Sysadmin::List::Automount;
 use Unix::Sysadmin::List::Netgroup;

 $ul = Unix::Sysadmin::List::User->load();
 $hl = Unix::Sysadmin::List::Host->load();
 $gl = Unix::Sysadmin::List::Group->load();
 $al = Unix::Sysadmin::List::Automount->load();
 $nl = Unix::Sysadmin::List::Netgroup->load();

 load lists of  objects from files.

DESCRIPTION

This abstract class describes generic lists of objects. Particular object types are implemented by subclasses. The subclasses currently implemented are:

Unix::Sysadmin::List::Automount: See the Unix::Sysadmin::List::Automount manpage in section 5 of the manual for the format of the file maintained by this class. See Automount Specific Methods in this manpage for methods specific to this subclass.
Unix::Sysadmin::List::Group: See the Unix::Sysadmin::List::User manpage in section 5 of the manual for the format of the file maintained by this subclass. See See Group Specific Methods in this manpage for methods specific to this subclass.
Unix::Sysadmin::List::Host: See the Unix::Sysadmin::List::Host manpage in section 5 of the manual for the format of the file maintained by this subclass. See Host Specific Methods in this manpage for methods specific to this subclass.
Unix::Sysadmin::List::Netgroup: See the Unix::Sysadmin::List::Netgroup manpage in section 5 of the manual for the format of the file maintained by this class. See Netgroup Specific Methods in this manpage for methods specific to this subclass.
Unix::Sysadmin::List::User: See the Unix::Sysadmin::List::User manpage in section 5 of the manual for the format of the file maintained by this subclass. See See User Specific Methods for methods specific to this subclass.

PROPERTIES AND METHODS

The Unix::Sysadmin::List base class defines a set of methods for manipulating lists of entity objects. These methods are described first in the following section. Each derived class also implements a set of abstract methods that all List classes share. These shared methods are described briefly in the section after next. Detailed descriptions of their behavior may be found in the man page describing the specific class's programming interface. Finally, derived classes may implement methods and/or properties specific to theparticular list. These are described in their respective man pages. in the following sections, Type stands for one of Host, User, Group, Automount or Netgroup.

Shared methods and properties

The following methods and properties are implemented by the List class itself and shared by all List subclasses

Constructors

Unix::Sysadmin::List::<Type>->new(): Returns an empty object of the specified type.
Unix::Sysadmin::List::<Type>->load(): Loads a list from List::<Type>->filename() and returns the list object.

Shared Methods

add(), add($object): The first form adds an empty object of the appropriate type to the list. The second form adds the object passed as a parameter.
delete($recnum): Removes the object at index $recnum from the list $self->current() is set to undef.
deleteCurrent(): Removes the $self->current() object from the list $self->current() is set to the old current +1, or undef if at the end of the list
goto($recnum): set $self->current() to the object at index $recnum in the list Returns the object or undef if $recnum < 0 || $recnum >= $self->numobjs()
first(): $self->goto() the first object in the list Returns the object or undef if $self->numobjs() == 0
last(): $self->goto() the last object in the list Returns the object or undef if $self->numobjs() == 0
prev(): $self->goto() the previous object in the list. Returns undef if $self->current() == 0
next(): $self->goto() the next object in the list. Returns undef if $self->current() == $self->numobjs()-1
search( {SEARCH=>"value"}): searches for ``value'' in the default index of the underlying object type. Returns the object matched or undef if no match. The default index is the one returned first in the list by $self->validsortorders(). Searches of this type return only one object and require only a single hash lookup, so they are fast and efficient.
search( {SEARCH=>Index, VALUE=>value}): searches for value in any index supported by the underlying object type. These indicies are documented in the Unix::Sysadmin::Type man pages, where Type is ``User'' or ``Host''. Returns a new List object containing all objects matched or undef if no match.
dump(): print a raw dump of the list's objects to stdout. (Identical to cating the database file.)
save(): Save the list of objects to $self->filename();

Shared Properties

numobjs(): The number of objects in the list. Read only.
current(): The current list index. Read only. 0<= current() < $self->numobjs(), or current() == undef

Abstract Methods and Properties

The following methods are implemented bt each of the list subclasses. See the man pages for each specific class for details.

Abstract Methods

loadOne(FILEHANDLE): Loads a single object of its entity type. Called by the shared load() method of the List class. The subclass calls the load() method of the entity class (e.g. Unix::Sysadmin::User) with the FILEHANDLE passed as its parameter, and returns the new entity object for storage in the list.
newChild(): Returns a new child object of the appropriate type.
indexer(OBJECT): Given an object, returns the value of the primary index.
sortorder() or sortorder(Index): sets and/or gets the index on which to sort/search the underlying objects. These indicies are specified in the Unix::Sysadmin::Type man pages, where Type is ``User'' or ``Host''. A list of these indicies is returned by $self->validsortorders().
validsortorders(): gets a list of the indicies supported by the underlying object type. The first item in the list is the default sort order, meaning the one that objects are indexed by in the list on load and that $self->search() calls with one parameter reference.
update(): Updates the list from the canonical master. Different List objects handle this in unique ways. See the entries for each specific List object later in this manpage.
genFiles({ HOST=>HostObj }): produces Unix configuration files for HostObj from the list.
installFiles({ HOST=>HostObj }): generates Unix configuration files for HostObj from the list and installs them on the host HostObj.
filename() or filename("newfilename"): sets and/or gets the filename containing objects of the underlying object type.

Automount Specific Methods

The following methods are implemented by the Unix::Sysadmin::List::Automount class:

updateFrom*amtype*(): update the list from the canonical master running *amtype*. Called by the generic update() method. *amtype* is one of 'amd' or 'autofs'. SunOS. Copies the master's configuration file or files, parses the contents and merges them with the existing list. Adds new entries with default values. Updates existing entries with changed values.
genAMDMap({ HOST=>HostObj }): Called by the genFiles() method. Generates an amd.map file from the list for host HostObj.
genAutofsMaps({ HOST=>HostObj }): Called by the genFiles() method. Generates Automounter maps drom the list for host HostObj.
refreshAMDLinks({ HOST=>HostObj }): Called by the installFiles() method. Creates links for amd from the list for host HostObj.
kickAutomounter({ HOST=>HostObj }): Called by the installFiles() method. Restarts amd or the automounter on host HostObj.

Host Specific Methods

The following method is implemented by the Unix::Sysadmin::List::Host class:

isManageable("hostname")

Subjects hostname to a series of tests and returns the Host object associated with hostname in the current list if the host passes, or an error string if it does not pass

The tests conducted are, in order:

o Is the host the ``canonical master''? The canonical master's configuration is used as the basis for much of the management of other hosts and cannot itself be managed. Returns ``hostname is the canonical master host'' if true.

o Is the host in the current list? Returns ``Can't find hostname in host database'' if not.

o Does the host respond to ping? Returns ``hostname not pingable'' if not.


o Is the host running a secure shell daemon?
Returns "hostname not running sshd" if not.

o Will the host accept our ssh key? Returns ``hostname doesn't like our ssh key'' if not.

It might seem that these tests should live in the Host object itself, but I wanted to test to see if the host was in the list too.

Use this method like this:

 $host=$list-E<gt>isManageable("hostname");
 if (ref($host) eq ''){
   print "error: $host\n";
   die "a bloody death";
 } else {
   do something Host-like with $host ..
 }

Netgroup Specific Methods

The following method is implemented by the Unix::Sysadmin::List::Netgroup class:

expand("netgroup"): Searches for the Netgroup named ``netgroup'' in the list and recursively expands its members into a list of unique hostnames

User Specific Methods

The following methods are implemented by the Unix::Sysadmin::List::User class:

updateFrom*OS*(): update the list from the canonical master running *OS*. Called by the generic update() method. *OS* is one of BSD or LinuxorSolaris. Copies the master's configuration file or files, parses the contents and merges them with the existing list.
genBSDPwFile({ HOST=>HostObj }): Called by the genFiles() method. Generates a BSD master.passwd file from the list for host HostObj. Same call is used for both FreeBSD and OpenBSD.
genLinuxPwFile({ HOST=>HostObj }): Called by the genFiles() method. Generates Linux passwd and shadow files from the list for host HostObj.
genSunOSPwFile({ HOST=>HostObj }): Called by the genFiles() method. Generates Solaris passwd and shadow files from the list for host HostObj.

AUTHOR

Howard Owen <hbo@egbok.com> =cut