User::SUMS - School User Management System
This library provides methods for easy administration and management of large groups of system accounts on a FreeBSD system. It's mainly targeted for schools, but can easily be used in other environments. SUMS takes use of the FreeBSD utility pw and is therefore not supported on other operating systems at the moment.
The module comes with pre-written programs placed in the /bin directory. The programs give access to the facilities provided by the library, and are designed for use in a typical school environment.
The library provides methods for adding, deleting and editing user accounts in a structured way. This implies managing system accounts in ordered groups, or classes if you will. The two terms groups and classes are used interchangeably since classes are represented as system groups.
The method add() that creates the users generates account information files (aka. info-files), which are files containing individual usernames and passwords for the purpose of being able hand out account information to students/users easily. As an addition there is also generated delete scripts which make it easy removing whole classes again. And since SUMS intentionally is to be used on a web server, on which students may publish via their website, each user created gets made a index.html placeholder automatically.
The previously mentioned features (expect the index.html placeholder) produce their output in the admin directory in the base path, which by default is /files (se new() to change this). Besides from the admin directory, the base path is used as a base path for system account home directories, which are created in year-interval directories representing school years, where a school year's duration is from August to following August.
Besides the base path the library uses one more directory, which is /usr/local/etc/sums. This directory holds 2 files unless the pre-written scripts are used, in which case the number is 3. Note: The use of either file is completely optional.
This file contains a list in key-value style of the groups created via the library, where keys are GIDs and values are GID names. The file itself is only updated by the library, but not used for anything else. Its purpose is to provide an index over the classes created via SUMS for other programs to use in various situations. As an example the script sums_users.pl in /bin uses it to generate a web indexed browseable list over all the classes.
This file contains a space delimited list of "blocked" users, whose appearance on the web indexed list generated by sums_users.pl will not have an active link. The file's purpose is to provide a way to restrict users from publishing on their websites. Users can by default be added to the list when created, for this see the "block" argument for new().
Although this file is meant to be used as a list over users who are restricted from publishing on their websites, it could easily be used for other things and should probably be called something else like the "marked"-list. The file's two first entries are configuration directives for the Apache web server, and are automatically managed. This feature makes it possible to entirely bring down a user's web page, if added to the block list. See the Apache "UserDir" module documentation for more on that.
The directory and files will be created first time the new() method is run, if permissions are OK.
The library is used by both programs in the /bin directory.
They are
Command line interface based program for using the SUMS library.
CGI script that indexes all the users allowing a visitor to browse their websites in an organized manner.
The programs located in /bin are set up to use the configuration file /usr/local/etc/sums/sums.conf to override the default library settings. The file is created first time sums.pl is run.
Methods that take multiple arguments use a hash key-value pair for passing arguments. If only one argument is required a single scalar value is passed.
Note: Methods all return undef if bad or insufficient parameters are passed to method.
Default constructor options are (if none overriding passed)
Arguments:
Base path for admin related files and home folders.
Common user GID which all users will be a member of if added through the add() method. This becomes the user's primary GID.
Boolean deciding whether or not newly created users should be added to the block.list file.
String to be printed in each user's info file. Good for informing about password policies and so.
String to be printed in the HTML placeholder for each user created.
Reference to a list of commands that will be executed for each user added via the add() method, where
%U will be replaced by the username.
%F will be replaced by the full name.
%P will be replaced by the password for the username.
%I will be replaced by the full path to the user's info file.
Example:
use User::SUMS;
my $tasks_ref = ['/usr/local/bin/MakeMediaWikiUser.pl username=%U fullname=%F password=%P'];
my $sums = User::SUMS->new(add_tasks => $tasks_ref);
Would result in any user being added through the add() method also being added to a MediaWiki system at the same time, with the same account details.
This integer represents the offset in school years since the class the student is to become a member of, first began at the school. '0' means no offset, meaning the class began this school year. '1' means last school year and so on.
This affects the add() method when creating new users. For example if the 'offset' argument was set to '1', a newly added user in the school year 2006-2007 would be created with the configuration that the current school year is 2005-2006.
Adds a new user to SUMS.
Arguments:
Full user name with first letter uppercased after white space.
Note: add() calls make_nick() with abbreviated year as suffix.
This is the class (group name, not number, from /etc/group) that the user will become a member of. If it does not exist it is created.
Note: Spaces are not allowed!
Returns a /etc/passwd login/nickname.
Note: This method converts non-ASCII characters to their ASCII equivalents for compatibility with the /etc/passwd file.
Arguments:
Full user name with first letter uppercased after white space.
Where $arg is a suffix appended to the nickname without change. For example the abbreviated year as used in add().
Note: This argument is optional and can be omitted.
Example:
use User::SUMS;
my $sums = User::SUMS->new;
my $nickname;
$nickname = $sums->make_nick('Donald Duck', 15); # $nickname contains "donaldd15".
$nickname = $sums->make_nick('Nicholas Mossor Rathmann', '06'); # $nickname contains "nicholasmr06". Notice the suffix is quoted, since the nick else would become "nicholasmr6"
$nickname = $sums->make_nick('Daniel Gabriel Fahrenheit', 'ABC'); # $nickname contains "danielgfABC".
Returns list of abbreviated years in use by users.
Arguments:
Takes no arguments.
Adds a group to the system group database /etc/group.
Arguments:
Where $arg is the GID name. Note: Spaces are not allowed.
Removes a group from the system group database /etc/group.
Arguments:
Where $arg is the GID name.
Renames a group in the system group database /etc/group
Arguments:
old => "Old_group_name"
new => "New_group_name"
Note: No spaces allowed.
Adds a group to the gid.list file.
Arguments:
Where $arg is either the GID or equivalent GID name.
Removes a group from the gid.list file.
Arguments:
Where $arg is either the GID or equivalent GID name.
Renames a group from the gid.list file.
Arguments:
old => "Old_group_name"
new => "New_group_name"
Note: No spaces allowed.
Returns contents of gid.list in a hash containing GIDs as keys, and their equivalent GID names as values.
Arguments:
Takes no arguments.
Adds user to group.
Arguments:
Removes user from group.
Arguments:
Returns list of GIDs the user is a member of.
Arguments:
Where $arg contains a valid nickname.
Add a user to the block.list file.
Arguments:
Where $arg is a valid nickname.
Remove a user from the block.list file.
Arguments:
Where $arg is a valid nickname.
Returns the list of blocked users from the block.list file.
Arguments:
Takes no arguments.
Returns 1 if nickname is on the blocked list and otherwise 0.
Arguments:
Where $arg contains a valid nickname.
Returns a hash with all the members of the common SUMS GID. Hash keys are nicknames, values are GCOS fields (full names).
Arguments:
Takes no arguments.
Returns hash with nicknames as keys, whose nicknames are suffixed with the requested abbreviated year. Values are the corresponding GCOS fields (full names).
Arguments:
Where $arg is the abbreviated year suffixed on nick names. For example '06' for 2006.
Returns hash with all members of the requested class. Hash keys are nicknames, values are GCOS fields (full names).
Arguments:
Where $arg is either the class GID or the corresponding GID name.
Returns the corresponding GID name from gid.list.
Arguments:
Where $arg is a valid GID number.
Returns the corresponding GID number from gid.list.
Arguments:
Where $arg is a valid GID name.
Nicholas Mossor Rathmann <nicholas.rathmann@gmail.com>
Copyright (c) 2006-2007 by Nicholas Mossor Rathmann. All Rights Reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.