NAME
Unix::Mgt - lightweight Unix management tools
SYNOPSIS
# 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');
DESCRIPTION
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
.
Early release
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 removing users from groups, renaming users or groups, or several other methods.
Unix::Mgt::User
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
. The new
method is an alias for get
.
Unix::Mgt::User objects stringify to the account's name. For example, the following code would output miko
.
$user = Unix::Mgt::User->get('miko');
print $user, "\n";
get
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.
$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.
create
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:
$user = Unix::Mgt::User->create('lanny', system=>1);
create() uses the Unix adduser
program.
ensure
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:
$user = Unix::Mgt::User->ensure('molly');
name
Returns the name of the user account. Currently this method cannot be used to set the account name.
print $user->name(), "\n";
uid
Returns the user's user id (uid).
print $user->uid(), "\n";
passwd
Returns the password field from getpwname()
. This method will not actually return a password, it will probably just return *
.
print $user->passwd(), "\n"; # probably outputs "*"
gid
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().
dir
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";
shell
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";
group
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 = $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
secondary_groups()
returns an array of the user's secondary groups. Each element in the array is a Unix::Mgt::Group object.
@groups = $user->secondary_groups();
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 = $user->groups();
add_to_group
add_to_group()
adds the user to a group. The group will be one of the user's secondary groups, not the primary group.
$user->add_to_group('video');
remove
remove
removes the user account from the system. remove
does not take any parameters.
$user->remove();
Unix::Mgt::Group
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
. The new
method is an alias for get
.
Unix::Mgt::Group objects stringify to the groups's name. For example, the following code would output video
.
$group = Unix::Mgt::Group->get('video');
print $group, "\n";
get
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.
$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.
create
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.
ensure
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:
$group = Unix::Mgt::User->ensure('wbesters');
name
Returns the name of the group. Currently this method cannot be used to set the group name.
print $group->name(), "\n";
gid
Returns the groups's group id (gid).
print $group->gid(), "\n";
members
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 = $group->members();
The elements in the array are Unix::Mgt::User objects.
primary_members
primary_members()
returns an array of users for whom this is the primary group.
@members = $group->primary_members();
The elements in the returned array are Unix::Mgt::User objects.
secondary_members
secondary_members()
returns an array of users for whom this is a secondary group.
@members = $group->secondary_members();
The elements in the returned array are Unix::Mgt::User objects.
add_member
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.
$group->add_member('miko');
If the user is already a member of the group then nothing is done and no error is set.
remove
remove
removes the group from the system. remove
does not take any parameters.
$group->remove();
If any users have the group as a primary group then this method will fail.
SEE ALSO
Passwd::Unix and Unix::Passwd::File provide similar functionality.
TERMS AND CONDITIONS
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.
AUTHOR
Miko O'Sullivan miko@idocs.com
TO DO
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.
HISTORY
- Version 0.10 December 30, 2014
-
Initial release
- Version 0.11 December 31, 2014
-
Changed addgroup to groupadd.
Added tests for existence of adduser, usermod, and groupadd.
- Version 0.12 January 3, 2015
-
Fixed some POD formatting issues.
Revised tests to include test names.
- Version 0.13 January 4, 2015
-
Added $user->remove() and $group->remove().
Added slots where BSD-style commands will go. Currently, methods for creating, modifying, or deleting users or group will fail on BSD.
- Version 0.14 February 2, 2015
-
Added support for BSD. The support is poorly tested because I don't have a BSD system. Any feedback is appreciated.
Added Unix::Mgt::User::new and Unix::Mgt::Group::new as aliases to get().