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 <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.

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.