====== esmith::AccountsDB ======
if you want the latest documentation do
  perldoc esmith::AccountsDB
===== NAME =====
esmith::AccountsDB - interface to esmith configuration database<br />

In a root terminal you can do the command below if you want to display the up-to-date content
 perldoc -U esmith::AccountsDB

===== SYNOPSIS =====
           use esmith::AccountsDB;
           my $a = esmith::AccountsDB->open;
  
           my @users    = $a->users();
           my @groups   = $a->groups();
           my @ibays    = $a->ibays();
           my @printers = $a->printers();
           my @pseudonyms = $a->pseudonyms();
  
           $a->is_user_in_group($user, $group);
           my @groups = $a->user_group_list($user);
           $a->add_user_to_groups($user, @groups);
           $a->remove_user_from_groups($user, @groups);
  
           $a->create_user_auto_pseudonyms($user);
           $a->remove_user_auto_pseudonyms($user);
           $a->remove_all_user_pseudonyms($user);
           my $dp = $a->dot_pseudonym($user);
           my $up = $a->underbar_pseudonym($user);
           my $uid = $a->get_next_uid();

===== DESCRIPTION =====
This module provides an abstracted interface to the esmith accounts database.

==== open() ====

Loads an existing account database and returns an esmith::AccountsDB object representing it.

==== open_ro() ====

Like esmith::DB->open_ro, but if given no $file it will try to open the file in the ESMITH_ACCOUNT_DB environment variable or accounts.

==== users(), groups(), ibays(), printers(), pseudonyms() ====

Returns a list of records (esmith::DB::db::Record objects) of the given type.

===== GROUP MANAGEMENT =====
==== $a->is_user_in_group($user, $group) ====

Returns true if the user is a member of the group, false otherwise. The arguments are a user name and a group name.

This routine will return undef if there is no such group, false (but defined) if the user is not in the group, and true if the user is in the group.

==== $a->user_group_list($user) ====

Get a list of groups (by name) of which a user is a member.  The $user argument is simply the username.

==== $a->add_user_to_groups($user, @groups) ====

Given a list of groups (by name), adds the user to all of them.

Doesn’t signal the group-modify event, just does the DB work.

Note: the method used here is a bit kludgy.  It could result in a user being in the same group twice.

==== $a->remove_user_from_groups($user, @groups) ====

Given a list of groups, removes a user from all of them.  Doesn’t signal the group-modify event, just does the DB work.

==== $a->set_user_groups($user, @groups) ====

Sets the user’s groups in one fell swoop.  Under the hood, it’s removing the user from every group they’re in then adding them to the set you give.

===== PSEUDONYM MANAGEMENT =====
==== $a->create_user_auto_pseudonyms($user) ====

Given a user name, creates standard pseudonyms ("dot" and "underbar" style) for that user.

==== $a->remove_all_user_pseudonyms($user) ====

Given a username, remove any pseudonyms related to that user from the accounts database. Also removes any pseudonyms related to a pseudonym being removed. Returns the number of pseudonym records deleted.

==== $a->remove_user_auto_pseudonyms($user) ====

Given a username, remove the dot_pseudonym and underbar_pseudonym related to that user from the accounts database.  Returns the number of pseudonym records deleted.

==== $a->dot_pseudonym($user) ====

Returns the "dot"-style pseudonym for a user as a string.  For instance, dot_pseudonym("bart") might return "bart.simpson".

==== $a->underbar_pseudonym($user) ====

Returns the "underbar"-style pseudonym for a user as a string.  For instance, underbar_pseudonym("bart") might return "bart_simpson".

==== $a->activeUsers() ====

Returns the number of active users, ie, accounts which have passwords set and are of type ’user’.

==== get_next_uid ====

Returns the next available UID from /etc/passwd. All UIDs are above the range reserved for ’system’ accounts (currently 5000).

==== new_record ($key, \%props) ====

This method is overridden from esmith::DB::db. We do an additional check for implicit accounts here - accounts that exist in /etc/passwd but not in the db. Otherwise it behaves just like the superclass method.

==== validate_account_name ($name) ====

Check $name to see if it is a valid account name. Valid account names start with a letter or number and contain only letters, numbers, underscores, dots and dashes.

=== AUTHOR ===
       SME Server Developers <bugs@e-smith.com>

{{tag> neth-development sme-development }}