add_delete_user_groups

 add_delete_user_groups(%args) -> [status, msg, payload, meta]

Add or delete user from one or several groups.

This can be used to reduce several "add_user_to_group()" and/or "delete_user_from_group()" calls to a single call. So:

 add_delete_user_groups(user=>'u',add_to=>['a','b'],delete_from=>['c','d']);

is equivalent to:

 add_user_to_group     (user=>'u', group=>'a');
 add_user_to_group     (user=>'u', group=>'b');
 delete_user_from_group(user=>'u', group=>'c');
 delete_user_from_group(user=>'u', group=>'d');

except that "add_delete_user_groups()" does it in one pass.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• add_to => array[unix::groupname] (default: [])

  List of group names to add the user as member of.

• delete_from => array[unix::groupname] (default: [])

  List of group names to remove the user as member of.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• user* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

add_group

 add_group(%args) -> [status, msg, payload, meta]

Add a new group.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• backup => bool (default: 0)

  Whether to backup when modifying files.

  Backup is written with ".bak" extension in the same directory. Unmodified file will not be backed up. Previous backup will be overwritten.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• gid => unix::gid

  Pick a specific new GID.

  Adding a new group with duplicate GID is allowed.

• group* => unix::groupname
• max_gid => int (default: 65535)

  Pick a range for new GID.

  If a free GID between "min_gid" and "max_gid" is not found, error 412 is returned.

• members => any

  Fill initial members.

• min_gid => int (default: 1000)

  Pick a range for new GID.

  If a free GID between "min_gid" and "max_gid" is not found, error 412 is returned.

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

add_user

 add_user(%args) -> [status, msg, payload, meta]

Add a new user.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• backup => bool (default: 0)

  Whether to backup when modifying files.

  Backup is written with ".bak" extension in the same directory. Unmodified file will not be backed up. Previous backup will be overwritten.

• encpass => str

  Encrypted password.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• expire_date => int

  The date of expiration of the account, expressed as the number of days since Jan 1, 1970.

• gecos => str

  Usually, it contains the full username.

• gid => int

  Pick a specific GID when creating group.

  Duplicate GID is allowed.

• group => unix::groupname

  Select primary group (default is group with same name as user).

  Normally, a user's primary group with group with the same name as user, which will be created if does not already exist. You can pick another group here, which must already exist (and in this case, the group with the same name as user will not be created).

• home => dirname

  User's home directory.

• last_pwchange => int

  The date of the last password change, expressed as the number of days since Jan 1, 1970.

• max_gid => int

  Pick a range for GID when creating group.

• max_pass_age => int

  The number of days after which the user will have to change her password.

• max_uid => int (default: 65535)

  Pick a range for new UID.

  If a free UID between "min_uid" and "max_uid" is not found, error 412 is returned.

• min_gid => int

  Pick a range for GID when creating group.

• min_pass_age => int

  The number of days the user will have to wait before she will be allowed to change her password again.

• min_uid => int (default: 1000)

  Pick a range for new UID.

  If a free UID between "min_uid" and "max_uid" is not found, error 412 is returned.

• pass => str

  Password, generally should be "x" which means password is encrypted in shadow.

• pass_inactive_period => int

  The number of days after a password has expired (see max_pass_age) during which the password should still be accepted (and user should update her password during the next login).

• pass_warn_period => int

  The number of days before a password is going to expire (see max_pass_age) during which the user should be warned.

• shell => filename

  User's shell.

• uid => int

  Pick a specific new UID.

  Adding a new user with duplicate UID is allowed.

• user* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

add_user_to_group

 add_user_to_group(%args) -> [status, msg, payload, meta]

Add user to a group.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• group* => unix::groupname
• user* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

delete_group

 delete_group(%args) -> [status, msg, payload, meta]

Delete a group.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• backup => bool (default: 0)

  Whether to backup when modifying files.

  Backup is written with ".bak" extension in the same directory. Unmodified file will not be backed up. Previous backup will be overwritten.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• group* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

delete_user

 delete_user(%args) -> [status, msg, payload, meta]

Delete a user.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• backup => bool (default: 0)

  Whether to backup when modifying files.

  Backup is written with ".bak" extension in the same directory. Unmodified file will not be backed up. Previous backup will be overwritten.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• user* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

delete_user_from_group

 delete_user_from_group(%args) -> [status, msg, payload, meta]

Delete user from a group.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• group* => unix::groupname
• user* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

get_group

 get_group(%args) -> [status, msg, payload, meta]

Get group details by group name or gid.

Either "group" OR "gid" must be specified.

The function is not dissimilar to Unix's "getgrnam()" or "getgrgid()".

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• gid => unix::gid
• group => unix::username
• with_field_names => bool (default: 1)

  If false, don't return hash.

  By default, a hashref is returned containing field names and its values, e.g. "{group=>"titin", pass=>"x", gid=>500, ...}". With "with_field_names=>0", an arrayref is returned instead: "["titin", "x", 500, ...]".

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

get_max_gid

 get_max_gid(%args) -> [status, msg, payload, meta]

Get maximum GID used.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

•

etc_dir => str (default: "/etc")

Specify location of passwd files.

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

get_max_uid

 get_max_uid(%args) -> [status, msg, payload, meta]

Get maximum UID used.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

•

etc_dir => str (default: "/etc")

Specify location of passwd files.

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

get_user

 get_user(%args) -> [status, msg, payload, meta]

Get user details by username or uid.

Either "user" OR "uid" must be specified.

The function is not dissimilar to Unix's "getpwnam()" or "getpwuid()".

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• uid => unix::uid
• user => unix::username
• with_field_names => bool (default: 1)

  If false, don't return hash.

  By default, a hashref is returned containing field names and its values, e.g. "{user=>"titin", pass=>"x", uid=>500, ...}". With "with_field_names=>0", an arrayref is returned instead: "["titin", "x", 500, ...]".

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

get_user_groups

 get_user_groups(%args) -> [status, msg, payload, meta]

Return groups which the user belongs to.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• detail => bool (default: 0)

  If true, return all fields instead of just group names.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• user* => unix::username
• with_field_names => bool (default: 1)

  If false, don't return hash for each entry.

  By default, when "detail=>1", a hashref is returned for each entry containing field names and its values, e.g. "{group=>"titin", pass=>"x", gid=>500, ...}". With "with_field_names=>0", an arrayref is returned instead: "["titin", "x", 500, ...]".

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

group_exists

 group_exists(%args) -> bool

Check whether group exists.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• gid => unix::gid
• group => unix::groupname

Return value: (bool)

is_member

 is_member(%args) -> bool

Check whether user is member of a group.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• group* => unix::groupname
• user* => unix::username

Return value: (bool)

list_groups

 list_groups(%args) -> [status, msg, payload, meta]

List Unix groups in group file.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• detail => bool (default: 0)

  If true, return all fields instead of just group names.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• with_field_names => bool (default: 1)

  If false, don't return hash for each entry.

  By default, when "detail=>1", a hashref is returned for each entry containing field names and its values, e.g. "{group=>"titin", pass=>"x", gid=>500, ...}". With "with_field_names=>0", an arrayref is returned instead: "["titin", "x", 500, ...]".

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

list_users

 list_users(%args) -> [status, msg, payload, meta]

List Unix users in passwd file.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• detail => bool (default: 0)

  If true, return all fields instead of just usernames.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• with_field_names => bool (default: 1)

  If false, don't return hash for each entry.

  By default, when "detail=>1", a hashref is returned for each entry containing field names and its values, e.g. "{user=>"titin", pass=>"x", uid=>500, ...}". With "with_field_names=>0", an arrayref is returned instead: "["titin", "x", 500, ...]".

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

list_users_and_groups

 list_users_and_groups(%args) -> [status, msg, payload, meta]

List Unix users and groups in passwd/group files.

This is basically "list_users()" and "list_groups()" combined, so you can get both data in a single call. Data is returned in an array. Users list is in the first element, groups list in the second.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• detail => bool (default: 0)

  If true, return all fields instead of just names.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• with_field_names => bool (default: 1)

  If false, don't return hash for each entry.

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

modify_group

 modify_group(%args) -> [status, msg, payload, meta]

Modify an existing group.

Specify arguments to modify corresponding fields. Unspecified fields will not be modified.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• admins => str

  It must be a comma-separated list of user names, or empty.

• backup => bool (default: 0)

  Whether to backup when modifying files.

  Backup is written with ".bak" extension in the same directory. Unmodified file will not be backed up. Previous backup will be overwritten.

• encpass => str

  Encrypted password.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• gid => unix::gid

  Numeric group ID.

• group* => unix::groupname

  Group name.

• members => str

  List of usernames that are members of this group, separated by commas.

• pass => str

  Password, generally should be "x" which means password is encrypted in gshadow.

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

modify_user

 modify_user(%args) -> [status, msg, payload, meta]

Modify an existing user.

Specify arguments to modify corresponding fields. Unspecified fields will not be modified.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• backup => bool (default: 0)

  Whether to backup when modifying files.

  Backup is written with ".bak" extension in the same directory. Unmodified file will not be backed up. Previous backup will be overwritten.

• encpass => str

  Encrypted password.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• expire_date => int

  The date of expiration of the account, expressed as the number of days since Jan 1, 1970.

• gecos => str

  Usually, it contains the full username.

• gid => unix::gid

  Numeric primary group ID for this user.

• home => dirname

  User's home directory.

• last_pwchange => int

  The date of the last password change, expressed as the number of days since Jan 1, 1970.

• max_pass_age => int

  The number of days after which the user will have to change her password.

• min_pass_age => int

  The number of days the user will have to wait before she will be allowed to change her password again.

• pass_inactive_period => int

  The number of days after a password has expired (see max_pass_age) during which the password should still be accepted (and user should update her password during the next login).

• pass_warn_period => int

  The number of days before a password is going to expire (see max_pass_age) during which the user should be warned.

• shell => filename

  User's shell.

• uid => unix::uid

  Numeric user ID.

• user* => unix::username

  User (login) name.

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

set_user_groups

 set_user_groups(%args) -> [status, msg, payload, meta]

Set the groups that a user is member of.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• groups* => array[unix::groupname] (default: [])

  List of group names that user is member of.

  Aside from this list, user will not belong to any other group.

• user* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

set_user_password

 set_user_password(%args) -> [status, msg, payload, meta]

Set user's password.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• backup => bool (default: 0)

  Whether to backup when modifying files.

  Backup is written with ".bak" extension in the same directory. Unmodified file will not be backed up. Previous backup will be overwritten.

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• pass* => str
• user* => unix::username

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 (payload) is optional, the actual result. Fourth element (meta) is called result metadata and is optional, a hash that contains extra information.

Return value: (any)

user_exists

 user_exists(%args) -> bool

Check whether user exists.

This function is not exported by default, but exportable.

Arguments ('*' denotes required arguments):

• etc_dir => str (default: "/etc")

  Specify location of passwd files.

• uid => unix::uid
• user => unix::username

Return value: (bool)