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.

cpanm Setup::Unix::User

perl -MCPAN -e shell
install Setup::Unix::User