Passwd::Unix(3pm)

💖 Passwd::Unix(3pm) 💖

okay bestie, gather round, because this is the User Contributed Perl Documentation page for Passwd::Unix and it's literally your all-access pass to the standard unix files. no cap. 🎀

---

✨ NAME ✨

Passwd::Unix — access to standard unix files 🌸

---

✨ SYNOPSIS ✨

okay so first things first, you either use it object-oriented style:

use Passwd::Unix;

my $pu = Passwd::Unix->new;

my $err = $pu->user(
                "example",
                $pu->encpass("my_secret"),
                $pu->unused_uid,
                $pu->unused_gid,
                "My User",
                "/home/example",
                "/bin/bash"
);

$pu->passwd("example", $pu->encpass( "newsecret") );
foreach my $user ($pu->users) {
        print "Username: $user\nFull Name: ", $pu->gecos($user), "\n\n";
}

my $uid = $pu->uid('example');
$pu->del("example");

# or

or you go the function route, importing whatever your heart desires:

use Passwd::Unix qw(
    algorithm backup check_sanity compress del del_group del_user
    encpass exists_group exists_user gecos gid group group_file
    groups groups_from_gshadow home maxgid maxuid mingid minuid
    passwd passwd_file rename reset shadow_file shell uid user
    users users_from_shadow warnings
);

my $err = user( "example", encpass("my_secret"), unused_uid(), unused_gid(),
                "My User", "/home/example", "/bin/bash" );
passwd("example",encpass("newsecret"));
foreach my $user ( users() ) {
        print "Username: $user\nFull Name: ", gecos( $user ), "\n\n";
}

my $uid = uid( 'example' );
del( 'example' );

two vibes, one module. pick your fighter. 💅

---

🌈 ABSTRACT 🌈

Passwd::Unix hands you an abstract object-oriented and function interface to the standard Unix files, like /etc/passwd, /etc/shadow, and /etc/group. 🦋

and not only that — it also gives you a whole environment for testing your software without touching the system-critical files in /etc/. yes bestie, you can point it at totally different files than /etc/passwd etc. main character energy for your test suite fr fr. 👑

---

💜 DESCRIPTION 💜

so Passwd::Unix gives you an abstract interface to /etc/passwd, /etc/shadow, /etc/group, and /etc/gshadow format files. it was inspired by the Unix::PasswdFile module — except that one doesn't handle the /etc/shadow file, so like, not it. 🙈

the module got rewritten from the ground up in version 1.0 (to support newer hash algorithms and so on, iykyk), but it was done with compatibility in mind. that said? some incompatibilities can still occur. lowkey unavoidable. 💀

---

🎀 SUBROUTINES/METHODS 🎀

• new( [ param0 = 1, param1 => 0... ] )> — the constructor, the origin story. here's every parameter you can pass it:
  • passwd — path to passwd file; default "/etc/passwd"
  • shadow — path to shadow file; default "/etc/shadow"
  • group — path to group file; default "/etc/group"
  • gshadow — path to gshadow file if any; default "/etc/gshadow"
  • algorithm — hash algorithm, possible values: md5, blowfish, sha256, sha512; default "sha512"
  • umask — not used anymore; left only for compatibility reason
  • debug — not used anymore; left only for compatibility reason
  • backup — boolean; if set to 1, backup will be made; default 1
  • compress — boolean; if set to 1, backup compression will be made; default 1
  • warnings — boolean; if set to 1, important warnings will be displayed; default 0
• algorithm() — lets you pick the algorithm used for password generation. possible values: "md5", "blowfish", "sha256", "sha512".
• backup() — lets you say whether backup files should be made before every modyfication (1 for on, 0 for off). 🫶
• compress() — lets you say whether compression should be applied to those backup files (1 for on, 0 for off).
• check_sanity() — left only for compatibility reason. currently it does nothing and always returns 1. it's giving decorative. 💀
• debug() — left only for compatibility reason. currently it does nothing.
• default_umask( [UMASK] ) — left only for compatibility reason. currently it does nothing.
• del( USERNAME0, USERNAME1... ) — an alias for "del_user". it's for transition only.
• del_user( USERNAME0, USERNAME1... ) — deletes that list of users. if the users you supplied don't exist, it has no effect. nothing happens, no drama. ✨
• del_group( GROUPNAME0, GROUPNAME1... ) — deletes that list of groups. if the groups you supplied don't exist, it has no effect either.
• encpass( PASSWORD ) — encrypts plain text into a unix style password. 🔐
• error() — returns the last error. and yes, it works even if "warnings" is disabled, so you can always find out what went wrong.
• exists_user(USERNAME) — checks if the specified user exists. returns "undef" on failure and 1 on success.
• exists_group(GROUPNAME) — checks if the specified group exists. returns "undef" on failure and 1 on success.
• gecos( USERNAME [,GECOS] ) — read or modify a user's GECOS string (typically the full name). if GECOS was specified, you get back the result of the operation (1 or "undef"). otherwhise it returns the GECOS if any. 💖
• gid( USERNAME [,GID] ) — read or modify a user's GID. returns the result of the operation (1 or "undef") if GID was specified, otherwhise returns the GID if any.
• group( GROUPNAME [,GID, ARRAYREF] ) — can add, modify, or return info about a group. give it a single groupname parameter and it returns a two element list of (GID, ARRAYREF), where ARRAYREF is a ref to an array of the names of users in this GROUP. if no such group exists, you get undef and a ref to an empty array ("undef, [ ]"). supply all three parameters and the named group gets created — or modified if it already exists. glow up. 🌟
• group_file([PATH]) — call it with an argument and it sets the path to the group file. otherwise it returns the current PATH.
• groups() — returns a list of all existing groups. 👑
• groups_from_gshadow() — returns a list of all existing groups in a gshadow file.
• gshadow_file([PATH]) — call it with an argument and it sets the path to the gshadow file. otherwise it returns the current PATH.
• home( USERNAME [,HOMEDIR] ) — read or modify a user's home directory. returns the result of the operation (1 or "undef") if HOMEDIR was specified, otherwhise returns the HOMEDIR if any. 🏠
• maxuid( ) — returns the maximum UID in use.
• maxgid() — returns the maximum GID in use.
• minuid( [UID] ) — returns the minimum UID in use that is greater then spupplied. (yes, spupplied, we love a typo, she's iconic.) 💅
• mingid() — returns the minimum GID in use that is greater then spupplied.
• passwd( USERNAME [,PASSWD] ) — read or modify a user's password. if you're holding a plaintext password, use the encpass method to encrypt it before passing it to this method. returns the result of the operation (1 or "undef") if PASSWD was specified. otherwhise returns the PASSWD if any.
• passwd_file([PATH]) — call it with an argument and it sets the path to the passwd file. otherwise it returns the current PATH.
• rename( OLDNAME, NEWNAME ) — changes the username for a user. ⚠️ if NEWNAME corresponds to an existing user, that user will be overwritten. returns "undef" on failure and 1 on success.

bestie. if that NEWNAME is already taken, the existing user is just gone. overwritten. poof. be careful out there. 😭

• reset() — sets the paths to the files passwd, shadow, group, gshadow back to the default values.
• shell( USERNAME [,SHELL] ) — read or modify a user's shell. returns the result of the operation (1 or "undef") if SHELL was specified, otherwhise returns the SHELL if any. 🐚
• uid( USERNAME [,UID] ) — read or modify a user's UID. returns the result of the operation (1 or "undef") if UID was specified, otherwhise returns the UID if any.
• user( USERNAME [,PASSWD, UID, GID, GECOS, HOMEDIR, SHELL] ) — can add, modify, or return info about a user. give it just a single username parameter and it returns a six element list of (PASSWORD, UID, GID, GECOS, HOMEDIR, SHELL), or undef if no such user exists. supply all seven parameters and the named user gets created — or modified if it already exists. ✨
• users() — returns a list of all existing usernames.
• users_from_shadow() — returns a list of all existing usernames in a shadow file.
• shadow_file([PATH]) — call it with an argument and it sets the path to the shadow file. otherwise it returns the current PATH.
• unused_uid( [MINUID] [,MAXUID] ) — returns the first unused UID in a given range. default MINUID is 0. default MAXUID is the maximal integer value (computed from $Config{ intsize }).
• unused_gid( [MINGID] [,MAXGID] ) — returns the first unused GID in a given range. default MINGID is 0. default MAXGID is the maximal integer value (computed from $Config{ intsize }).
• warnings() — lets you say whether warnings should be displayed (1 for on, 0 for off). and whether or not you do, you can always check the last warning/failure by calling "error". 🔍

---

🌸 DEPENDENCIES 🌸

• Crypt::Password
• IO::Compress::Bzip2
• Path::Tiny
• Tie::Array::CSV

---

💀 TODO 💀

• Preparation of tests.

(it's on the list okay, it's on the list 🫠)

---

🙈 INCOMPATIBILITIES 🙈

None known.

---

🐛 BUGS AND LIMITATIONS 🐛

None. I hope. 😭

---

🫶 THANKS 🫶

• Thanks to Jonas Genannt for many suggestions and patches!
• Thanks to Christian Kuelker for suggestions and reporting some bugs :-).
• Thanks to Steven Haryanto for suggestions.
• BIG THANKS to Lopes Victor for reporting some bugs and his exact sugesstions :-)
• Thanks to Foudil BRÉTEL for some remarks, suggestions as well as supplying relevant patch!
• BIG thanks to Artem Russakovskii for reporting a bug.

the community really showed up for this one and we love that for them. 💖

---

👑 AUTHOR 👑

Strzelecki Lukasz <lukasz@strzeleccy.eu>

---

⭐ LICENCE AND COPYRIGHT ⭐

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

See http://www.perl.com/perl/misc/Artistic.html

---

💀 POD ERRORS 💀

Hey! The above document had some coding errors, which are explained below:

• Around line 1365:

Non-ASCII character seen before =encoding in 'BRÉTEL'. Assuming UTF-8

not the encoding police catching us in 4k... anyway. 🫠

---

and that's the whole page bestie, slay ✨ this gem was served up by perl v5.40.1, dated 2025-11-03, and it's giving Passwd::Unix(3pm) all the way down. go touch some /etc/passwd files (safely!!) and stan. 💅🎀🦋