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 HISTORY HISTORY Version 0.10 December 30, 2014 Initial release POD ERRORS Hey! The above document had some coding errors, which are explained below: Around line 1527: =cut found outside a pod block. Skipping to next block.