NAME

NIS::DBM - Perl module implementing a NIS daemon.

SYNOPSIS

  use NIS::DBM;

DESCRIPTION

NIS::DBM trivializes the implementation of daemons and other scripts which maintain the NIS databases by presenting them as a hash keyed by both username and user id. If a numeric username exists in the byname databases, the number associated with that username will be used as the user id. This is the same behavior as chown and chgrp.

NIS::DBM maintains three caches of information to construct an accurate view of the NIS databases as modified by the program. The caches are for actual records from the database, modifications to the database, and deletions from the database. The caches have the following precedence: deletions, modifications, and general cache. The caches may be flushed to the database files at any time or upon object destruction.

NIS::DBM API

NIS::DBM constructor

This will construct a new NIS::DBM object. The arguments may be given in a variaty of ways:

    tie %nis, NIS::DBM, ( 'config filename' );
    tie %nis, NIS::DBM, ( { config_file => 'filename',
                            sections   => [ 'sec1', ... ],
                            default_keys => { keys1 => value1, ... },
                            required_keys => [ key1, key2, ... ]
                          } );
    tie %nis, NIS::DBM, ( config_file => 'filename',
                          sections   => [ 'sec1', ... ],
                          default_keys => { keys1 => value1, ... },
                          required_keys => [ key1, key2, ... ]
                          );
    tie %nis, NIS::DBM, ( filename => '/path/to/conf/file'
                          program_tag => 'string'
                          defaults => { keys1 => value1, ... },
                          required => [ key1, key2, ... ]
                          );

FETCH

Given a username or user id, FETCH will return the NIS record as a hash reference. FETCH will first consult any caches maintained by the tied object to provide current information that may not be available in the database files.

STORE

Given a username or user id, STORE will make any modifications to the caches necessary for the databases to reflect the changes when flushed. These same chaches are consulted by FETCH.

DELETE

Given a username or user id, DELETE marks the record for deletion. The record is not available for FETCHing or testing for EXISTance.

CLEAR

This is called when the hash is assigned an empty hash or array. This function is not implemented. You cannot remove the NIS user databases using this module.

EXISTS

Given a username or user id, will return true if the key exists in the modification, addition, or general cache or in the actual database. Will return false regardless of the existance in any database or cache if the record is marked for deletion.

FIRSTKEY

This function will initialize an array of keys and return the first. The keys are unordered.

NEXTKEY

This function will return the next key in the array of keys.

DESTROY

Flushes any changes in the chaches to the database files and closes them. This behavior may be overridden by the set_option(FLUSH=0)> method.

get_options

Returns a list of options currently set for the object.

get_option

Given a key, returns the value of the option.

set_option

Given a key/value pair, sets the option to the value. The following options are currently used:

flush

If FLUSH is set, any changes in the caches will be written out to the database files. The caches will be cleared after a flush if data is actually written.

OPTIONS

CLOBBER

 0 -> databases are read only
 1 -> STORE but not DELETE
 2 -> STORE and DELETE enabled

FLUSH

 0 -> do not flush changes from the caches to the databases
 1 -> flush changes from the caches to the databases 
      (by either the flush or DESTROY methods)

PUSH

 0 -> do not push changes to other machines
 1 -> push changes if needed to other machines

key_set

If this is set to either byuid or byname then only the keys in the respective files (i.e., uids or usernames) are available as keys. Otherwise, the default behavior is to assume username first and uid last.

name_db_files

uid_db_files

use_adjunct

If this is set, the difference between adjunct and non-adjunct files is recognized. Otherwise, the normal NIS behavior is used. If a file is in the list of dbm files with the string `adjunct' in the name, then the preparation phase of tieing the hash to the dbm files will set this flag.

yp_top

yp_src

yp_push_cmd

IDIOMS

The following are some idioms using the NIS::DBM tied hash. The username and user id are available via $username and $uid respectively.

Delete User

    my $userinfo = $nishash{$username || $uid};
    delete $nishash{$$userinfo{'username'}};
    delete $nishash{$$userinfo{'uid'}};

Change User's Username

    my $userinfo = $nishash{$username || $uid};
    delete $nishash{$$userinfo{'username'}};
    $$userinfo{'username'} = $new_username;
    $$nishash{$new_username} = $userinfo;
    $$nishash{$$userinfo{'uid'}} = $userinfo;

Change User's UID

    my $userinfo = $nishash{$username || $uid};
    delete $nishash{$$userinfo{'uid'}};
    $$userinfo{'username'} = $new_uid;
    $$nishash{$new_uid} = $userinfo;  
    $$nishash{$$userinfo{'username'}} = $userinfo;

Add New User

    my $userinfo = { username => $username,
                     uid      => $uid,
                     gid      => $gid,
                     gecos    => $gecos,
                     home     => $home,
                     shell    => $shell,
                     password => crypt($password, $salt)
                   };
    $nishash{$username} = $userinfo;
    $nishash{$uid} = $userinfo;

AUTHORS

James G. Smith, <jgsmith@tamu.edu> Philip C. Kizer, <pckizer@tamu.edu>

COPYRIGHT

Copyright (c) 1999, Texas A&M University. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
 3. Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTERS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

perl(1), Net::NIS(3).