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 deleting users, removing them from groups, or other deletion oriented objectives.
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. Note that there is no new method.
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');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. 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.
$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 addgroup 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.
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.
VERSION
Version: 0.10