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

VERSION
    version 0.09

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 has Rinci metadata.

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.

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.

FUNCTIONS
  setup_unix_user(%args) -> [status, msg, result, meta]
    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).
    Return the created UID/GID in the result.

    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.

    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 maxnewuid

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

    Return value:

    Returns an enveloped result (an array). First element (status) is an
    integer containing HTTP status code (200 means OK, 4xx caller error, 5xx
    function error). Second element (msg) is a string containing error
    message, or 'OK' if status is 200. Third element (result) is optional,
    the actual result. Fourth element (meta) is called result metadata and
    is optional, a hash that contains extra information.

AUTHOR
    Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2012 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.

