Unix::Mgt - lightweight Unix management tools
# get user account $user = Unix::Mgt::User->get('fred'); # display some info print 'uid: ', $user->uid, "\n"; print join(', ', $user->groups()), "\n"; # set some properties $user->gid('websters'); $user->shell('/bin/bash'); $user->add_to_group('postgres'); # create user account $user = Unix::Mgt::User->create('vera'); # get user account, creating it if necessary $user = Unix::Mgt::User->ensure('molly'); # get group $group = Unix::Mgt::Group->get('www-data'); # display some info print 'gid: ', $group->gid, "\n"; print join(', ', $group->members()), "\n"; # add a member $group->add_member('tucker');
Unix::Mgt provides simple object-oriented tools for managing your Unixish system. Currently this module provides tools for managing users and groups. Other tools may follow as they evolve.
Unix::Mgt does not directly manipulate any of the system files such as /etc/passwd. This module uses Perl's built-in Unix functions such as getgrent to get information, and Unix's built-in programs such as adduser.
/etc/passwd
getgrent
adduser
In the spirit of "release early, release often", I'm releasing this version of Unix::Mgt before it has all the features that might be expected. This version does not include methods for deleting users, removing them from groups, or other deletion oriented objectives.
A Unix::Mgt::User object represents a user in the Unix system. The object allows you to get and set information about the user account. A user object is created in one of three ways: get, create, or ensure. Note that there is no new method.
get
create
ensure
new
Unix::Mgt::User objects stringify to the account's name. For example, the following code would output miko.
miko
$user = Unix::Mgt::User->get('miko'); print $user, "\n";
Unix::Mgt::User->get() retrieves user account information using getpwnam or getpwuid. The single param for this method is either the name or the uid of the user.
getpwnam
getpwuid
$user = Unix::Mgt::User->get('vera'); $user = Unix::Mgt::User->get('1010');
If the user is not found then the do-not-have-user error id is set in $Unix::Mgt::err_id and undef is returned.
do-not-have-user
$Unix::Mgt::err_id
Unix::Mgt::User->create() creates a user account. The required param for this method is the name for the new account.
$user = Unix::Mgt::User->create('vera');
If the system param is true, then the account is created as a system user, like this:
system
$user = Unix::Mgt::User->create('lanny', system=>1);
create() uses the Unix adduser program.
Unix::Mgt::User->ensure() gets a user account if it already exists, and creates the account if it does not. For example, the following lines ensures the molly account:
molly
$user = Unix::Mgt::User->ensure('molly');
Returns the name of the user account. Currently this method cannot be used to set the account name.
print $user->name(), "\n";
Returns the user's user id (uid).
print $user->uid(), "\n";
Returns the password field from getpwname(). This method will not actually return a password, it will probably just return *.
getpwname()
*
print $user->passwd(), "\n"; # probably outputs "*"
Sets/gets the gid of the user's primary group. Called without params, it returns the user's gid:
print $user->gid(), "\n";
Called with a single param, gid() sets, then returns the user's primary group id:
print $user->gid('1010'), "\n";
If you want to get a Unix::Mgt::Group object representing the user's primary group, use $user->group().
Sets/gets the user's home directory. Called without params, it returns the directory name:
print $user->dir(), "\n";
Called with a single param, dir() sets, then returns the user's home directory:
print $user->dir('/tmp'), "\n";
Sets/gets the user's default command line shell. Called without params, it returns the shell name:
print $user->shell(), "\n";
Called with a single param, shell() sets, then returns the user's shell:
print $user->shell('/bin/sh'), "\n";
Sets/gets the user's primary group. When called without any params, group() returns a Unix::Mgt::Group object representing the user's primary group:
group()
$group = $user->group();
When called with a single param, group() sets the user's primary group. The param can be either the group's name or its gid:
$user->group('video'); $user->group(44);
secondary_groups() returns an array of the user's secondary groups. Each element in the array is a Unix::Mgt::Group object.
secondary_groups()
@groups = $user->secondary_groups();
groups() returns an array of all of the groups the user is a member of. The first element in the array will be the user's primary group.
groups()
@groups = $user->groups();
add_to_group() adds the user to a group. The group will be one of the user's secondary groups, not the primary group.
add_to_group()
$user->add_to_group('video');
A Unix::Mgt::Group object represents a group in the Unix system. The object allows you to get and set information about the group. A group object is created in one of three ways: get, create, or ensure. Note that there is no new method.
Unix::Mgt::Group objects stringify to the groups's name. For example, the following code would output video.
video
$group = Unix::Mgt::Group->get('video'); print $group, "\n";
Unix::Mgt::Group->get() retrieves group information using getgrnam or getgrgid. The single param for this method is either the name or the gid of the group.
getgrnam
getgrgid
$group = Unix::Mgt::Group->get('video'); $group = Unix::Mgt::Group->get('44');
If the group is not found then the do-not-have-group error id is set in $Unix::Mgt::err_id and undef is returned.
do-not-have-group
Unix::Mgt::Group->create() creates a group. The required param for this method is the name for the new group.
$group = Unix::Mgt::Group->create('websters');
create() uses the Unix groupadd program.
groupadd
Unix::Mgt::Group->ensure() gets a group if it already exists, and creates the group if it does not. For example, the following lines ensures the wbesters group:
wbesters
$group = Unix::Mgt::User->ensure('wbesters');
Returns the name of the group. Currently this method cannot be used to set the group name.
print $group->name(), "\n";
Returns the groups's group id (gid).
print $group->gid(), "\n";
members() returns an array of all members of the group. Both users for whom this is the primary group, and users for whom this is a secondary group are returned.
members()
@members = $group->members();
The elements in the array are Unix::Mgt::User objects.
primary_members() returns an array of users for whom this is the primary group.
primary_members()
@members = $group->primary_members();
The elements in the returned array are Unix::Mgt::User objects.
secondary_members() returns an array of users for whom this is a secondary group.
secondary_members()
@members = $group->secondary_members();
add_member() adds a user to the group as a secondary group. The single param can be a user name, uid, or Unix::Mgt::User object.
add_member()
$group->add_member('miko');
If the user is already a member of the group then nothing is done and no error is set.
Passwd::Unix and Unix::Passwd::File provide similar functionality.
Copyright (c) 2014 by Miko O'Sullivan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This software comes with no warranty of any kind.
Miko O'Sullivan miko@idocs.com
miko@idocs.com
This is an early release of Unix::Mgt. It does not include methods for deleting users, removing them from groups, or other deletion oriented objectives.
Please feel free to contribute code for these purposes.
Version: 0.11
Initial release
Changed addgroup to groupadd.
Added tests for existence of adduser, usermod, and groupadd.
Fixed some POD formatting issues.
Revised tests to include test names.
To install Unix::Mgt, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Unix::Mgt
CPAN shell
perl -MCPAN -e shell install Unix::Mgt
For more information on module installation, please visit the detailed CPAN module installation guide.