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.

 Help with BSD development

    This version does not work well on BSDish systems. Although the methods
    for retrieving information such as get and group work well, this module
    currently cannot create, modify, or delete users or group. If you'd
    like to help fill in these features, here's what needs to be done.

    Several places in the code is the comment "BSD code needed". In those
    places what we need is to build an array consisting of an external
    command and the arguments to be sent to the command. It would look
    something like this:

     # build command
     @cmd = (
        'pw', 
        'useradd', 
        $user->{'name'},
        '-G', 
        $group->{'name'},
     );

    The first element of the array is the program to be run. You don't need
    to put the full path of the program, Unix::SearchPathGuess should find
    it. (If it doesn't please let me know, we may need to fix
    Unix::SearchPathGuess.) The remaining elements are the params sent to
    the program using IPC::System::Simple. The program is not run in a
    shell, but instead is called directly, so it isn't necessary to do any
    shell escaping.

    The following methods currently need patching. In Unix::Mgt::User we
    need create(), field_get_set(), group(), add_to_group(), and remove().
    In Unix::Mgt::Group we need create() and remove(). We will need more as
    we add features to this module.

    Please email me at miko@idocs.com if you've made these mods.

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');

 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. 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 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 <http://search.cpan.org/~strzelec/Passwd-Unix/> and
    Unix::Passwd::File
    <http://search.cpan.org/~sharyanto/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.