NAME
    Setup::Unix::User - Setup Unix user (existence, home dir, group
    memberships)

VERSION
    version 0.07

SYNOPSIS
     use Setup::Unix::User 'setup_unix_user';

     # simple usage (doesn't save undo data)
     my $res = setup_unix_user name => 'foo',
                               member_of => ['admin', 'wheel'];
     die unless $res->[0] == 200 || $res->[0] == 304;

     # perform setup and save undo data (undo data should be serializable)
     $res = setup_unix_user ..., -undo_action => 'do';
     die unless $res->[0] == 200 || $res->[0] == 304;
     my $undo_data = $res->[3]{undo_data};

     # perform undo
     $res = setup_unix_user ..., -undo_action => "undo", -undo_data=>$undo_data;
     die unless $res->[0] == 200 || $res->[0] == 304;

DESCRIPTION
    This module provides one function: setup_unix_user.

    This module is part of the Setup modules family.

    This module uses Log::Any logging framework.

    This module's functions have Sub::Spec specs.

THE SETUP MODULES FAMILY
    I use the "Setup::" namespace for the Setup modules family. See
    Setup::File for more details on the goals, characteristics, and
    implementation of Setup modules family.

FUNCTIONS
    None are exported by default, but they are exportable.

  setup_unix_user(%args) -> [STATUS_CODE, ERR_MSG, RESULT]
    Setup Unix user (existence, group memberships).

    On do, will create Unix user if not already exists. And also make sure
    user belong to specified groups (and not belong to unwanted groups).

    On undo, will delete Unix user (along with its initially created home
    dir and files) if it was created by this function. Also will restore old
    group memberships.

    Returns a 3-element arrayref. STATUS_CODE is 200 on success, or an error
    code between 3xx-5xx (just like in HTTP). ERR_MSG is a string containing
    error message, RESULT is the actual result.

    This function supports undo operation. See Sub::Spec::Clause::features
    for details on how to perform do/undo/redo.

    This function supports dry-run (simulation) mode. To run in dry-run
    mode, add argument "-dry_run" => 1.

    Arguments ("*" denotes required arguments):

    *   create_home_dir => *bool* (default 1)

        Whether to create homedir when creating new user.

    *   max_new_gid => *str*

        Set maximum GID when creating new group.

        Default follows max_new_uid

    *   max_new_uid => *str* (default 65534)

        Set maximum UID when creating new user.

    *   member_of => *array*

        List of Unix group names that the user must be member of.

        If not specified, member_of will be set to just the primary group.
        The primary group will always be added even if not specified.

    *   min_new_gid => *str*

        Set minimum GID when creating new group.

        Default is UID

    *   min_new_uid => *str* (default 0)

        Set minimum UID when creating new user.

    *   name* => *str*

        User name.

    *   new_gecos => *str* (default "")

        Set gecos (usually, full name) when creating new user.

    *   new_home_dir => *str*

        Set home directory when creating new user, defaults to
        /home/<username>.

    *   new_home_dir_mode => *int* (default 448)

        Set permission mode of home dir when creating new user.

    *   new_password => *str*

        Set password when creating new user.

        Default is a random password

    *   new_shell => *str* (default "/bin/bash")

        Set shell when creating new user.

    *   not_member_of* => *str*

        List of Unix group names that the user must NOT be member of.

    *   primary_group => *str*

        Specify user's primary group.

        In Unix systems, a user must be a member of at least one group. This
        group is referred to as the primary group. By default, primary group
        name is the same as the user name. The group will be created if not
        exists.

    *   should_already_exist => *bool* (default 0)

        If set to true, require that user already exists.

        This can be used to fix user membership, but does not create user
        when it doesn't exist.

    *   skel_dir => *str* (default "/etc/skel")

        Directory to get skeleton files when creating new user.

    *   use_skel_dir => *bool* (default 1)

        Whether to copy files from skeleton dir when creating new user.

FAQ
  How to create user with a specific UID and/or GID?
    Set "min_new_uid" and "max_new_uid" (and/or "min_new_gid" and
    "max_new_gid") to your desired values. Note that the function will
    report failure if when wanting to create a user, the desired UID is
    already taken. But the function will not report failure if the user
    already exists, even with a different UID.

  How to create user without creating a group with the same name as that user?
    By default, "primary_group" is set to the same name as the user. You can
    set it to an existing group, e.g. "users" and the setup function will
    not create a new group with the same name as user.

SEE ALSO
    Setup::Unix::Group.

    Other modules in Setup:: namespace.

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2011 by Steven Haryanto.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

