Unix::Passwd::File - Manipulate /etc/{passwd,shadow,group,gshadow} entries
This document describes version 0.251 of Unix::Passwd::File (from Perl distribution Unix-Passwd-File), released on 2020-04-29.
use Unix::Passwd::File; # list users. by default uses files in /etc (/etc/passwd, /etc/shadow, et al) my $res = list_users(); # [200, "OK", ["root", ...]] # change location of files, return details $res = list_users(etc_dir=>"/some/path", detail=>1); # [200, "OK", [{user=>"root", uid=>0, ...}, ...]] # also return detail, but return array entries instead of hash $res = list_users(detail=>1, with_field_names=>0); # [200, "OK", [["root", "x", 0, ...], ...]] # get user/group information $res = get_group(user=>"paijo"); # [200, "OK", {user=>"paijo", uid=>501, ...}] $res = get_user(user=>"titin"); # [404, "Not found"] # check whether user/group exists say user_exists(user=>"paijo"); # 1 say group_exists(group=>"titin"); # 0 # get all groups that user is member of $res = get_user_groups(user=>"paijo"); # [200, "OK", ["paijo", "satpam"]] # check whether user is member of a group $res = is_member(user=>"paijo", group=>"satpam"); # 1 # adding user/group, by default adding user will also add a group with the same # name $res = add_user (user =>"ujang", ...); # [200, "OK", {uid=>540, gid=>541}] $res = add_group(group=>"ujang", ...); # [412, "Group already exists"] # modify user/group $res = modify_user(user=>"ujang", home=>"/newhome/ujang"); # [200, "OK"] $res = modify_group(group=>"titin"); # [404, "Not found"] # deleting user will also delete user's group $res = delete_user(user=>"titin"); # change user password $res = set_user_password(user=>"ujang", pass=>"foobar"); $res = modify_user(user=>"ujang", pass=>"foobar"); # same thing # add/delete user to/from group $res = add_user_to_group(user=>"ujang", group=>"wheel"); $res = delete_user_from_group(user=>"ujang", group=>"wheel"); # others $res = get_max_uid(); # [200, "OK", 65535] $res = get_max_gid(); # [200, "OK", 65534]
This module can be used to read and manipulate entries in Unix system password files (/etc/passwd, /etc/group, /etc/group, /etc/gshadow; but can also be told to search in custom location, for testing purposes).
This module uses a procedural (non-OO) interface. Each function in this module open and read the passwd files once. Read-only functions like `list_users()` and `get_max_gid()` open in read-only mode. Functions that might write to the files like `add_user()` or `delete_group()` first lock `passwd` file, open in read+write mode and also read the files in the first pass, then seek to the beginning and write back the files.
No caching is done so you should do your own if you need to.
Usage:
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_user_to_group()
delete_user_from_group()
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.
add_delete_user_groups()
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(%args) -> [status, msg, payload, meta]
Add a new group.
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.
.bak
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.
min_gid
max_gid
members => any
Fill initial members.
min_gid => int (default: 1000)
add_user(%args) -> [status, msg, payload, meta]
Add a new user.
encpass => str
Encrypted password.
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_uid
max_uid
min_gid => int
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)
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.
add_user_to_group(%args) -> [status, msg, payload, meta]
Add user to a group.
delete_group(%args) -> [status, msg, payload, meta]
Delete a group.
group* => unix::username
delete_user(%args) -> [status, msg, payload, meta]
Delete a user.
delete_user_from_group(%args) -> [status, msg, payload, meta]
Delete user from a group.
get_group(%args) -> [status, msg, payload, meta]
Get group details by group name or gid.
Either group OR gid must be specified.
group
gid
The function is not dissimilar to Unix's getgrnam() or getgrgid().
getgrnam()
getgrgid()
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, ...].
{group=>"titin", pass=>"x", gid=>500, ...}
with_field_names=>0
["titin", "x", 500, ...]
get_max_gid(%args) -> [status, msg, payload, meta]
Get maximum GID used.
get_max_uid(%args) -> [status, msg, payload, meta]
Get maximum UID used.
get_user(%args) -> [status, msg, payload, meta]
Get user details by username or uid.
Either user OR uid must be specified.
user
uid
The function is not dissimilar to Unix's getpwnam() or getpwuid().
getpwnam()
getpwuid()
uid => unix::uid
user => unix::username
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, ...].
{user=>"titin", pass=>"x", uid=>500, ...}
get_user_groups(%args) -> [status, msg, payload, meta]
Return groups which the user belongs to.
detail => bool (default: 0)
If true, return all fields instead of just group names.
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, ...].
detail=>1
group_exists(%args) -> bool
Check whether group exists.
Return value: (bool)
is_member(%args) -> bool
Check whether user is member of a group.
list_groups(%args) -> [status, msg, payload, meta]
List Unix groups in group file.
list_users(%args) -> [status, msg, payload, meta]
List Unix users in passwd file.
If true, return all fields instead of just usernames.
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, ...].
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.
list_users()
list_groups()
If true, return all fields instead of just names.
modify_group(%args) -> [status, msg, payload, meta]
Modify an existing group.
Specify arguments to modify corresponding fields. Unspecified fields will not be modified.
admins => str
It must be a comma-separated list of user names, or empty.
Numeric group ID.
Group name.
members => str
List of usernames that are members of this group, separated by commas.
Password, generally should be "x" which means password is encrypted in gshadow.
modify_user(%args) -> [status, msg, payload, meta]
Modify an existing user.
Numeric primary group ID for this user.
Numeric user ID.
User (login) name.
set_user_groups(%args) -> [status, msg, payload, meta]
Set the groups that a user is member of.
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.
set_user_password(%args) -> [status, msg, payload, meta]
Set user's password.
pass* => str
user_exists(%args) -> bool
Check whether user exists.
Please visit the project's homepage at https://metacpan.org/release/Unix-Passwd-File.
Source repository is at https://github.com/perlancar/perl-Unix-Passwd-File.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Unix-Passwd-File
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Old modules on CPAN which do not support shadow files are pretty useless to me (e.g. Unix::ConfigFile). Shadow passwords have been around since 1988 (and in Linux since 1992), FFS!
Passwd::Unix. I created a fork of Passwd::Unix v0.52 called Passwd::Unix::Alt in 2011 to fix some of the deficiencies/quirks in Passwd::Unix, including: lack of tests, insistence of running as root (despite allowing custom passwd files), use of not-so-ubiquitous bzip2, etc. Then in 2012 I decided to create Unix::Passwd::File. Here are how Unix::Passwd::File differs compared to Passwd::Unix (and Passwd::Unix::Alt):
tests in distribution
no need to run as root
no need to be able to read the shadow file for some operations
For example, list_users() will simply not return the encpass field if the shadow file is unreadable. Of course, access to shadow file is required when getting or setting password.
encpass
strictly procedural (non-OO) interface
I consider this a feature :-)
detailed error message for each operation
removal of global error variable
working locking
Locking is done by locking passwd file.
passwd
Setup::Unix::User and Setup::Unix::Group, which use this module.
Rinci
perlancar <perlancar@cpan.org>
This software is copyright (c) 2020, 2017, 2016, 2015, 2014, 2012 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Unix::Passwd::File, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Unix::Passwd::File
CPAN shell
perl -MCPAN -e shell install Unix::Passwd::File
For more information on module installation, please visit the detailed CPAN module installation guide.