usermod(3pm)

💖 usermod — the Linux::usermod era 💖

okay bestie, sit DOWN, because we're talking about usermod, from the 3pm manual section (that's Perl-user-contributed-documentation, iykyk). She's a Perl module named Linux::usermod and she is here to modify user and group accounts. Slay.

---

✨ NAME ✨

Linux::usermod — modify user and group accounts 🫶

---

🌸 SYNOPSIS 🌸

Here's the whole vibe, verbatim, no notes:

use Linux::usermod;

$user = Linux::usermod->new(username);
$grp  = Linux::usermod->new(groupname, 1);

$user->get(gid); # equal to $user->get(3);
$user->get(uid); # equal to $user->get(2);
$grp->get(gid);  # equal to $user->get(2);
$grp->get(users);# equal to $user->get(3);

#lock and unlock user account

$user->lock();
$user->unlock();

#get password(passwd file)
$user->get(ppassword);

#get encoded password(shadow file)
$user->get(password);

#set encoded password
$user->set(password);
$grp->set(password);

#set shell / group administrator
$user->set(shell);
$grp->set(ga);

#set group users
@users = qw(user1 user2);
$grp->set(users, "@users");

Linux::usermod->add(username);

#or

Linux::usermod->add(username, password, uid, gid, comment, home, shell);

#where the password goes in shadow file and gid becomes
#equal to uid unless specified and uid is becoming the
#first unreserved number after 1000 unless specified

#or

@users = qw(user1 user2 user3);
Linux::usermod->grpadd(groupname, gid, "@users")

#where the password goes in gshadow file and gid becomes
#equal to the second argument or the first unreserved number
#after 100

#delete user/group
Linux::usermod->del(username);
Linux::usermod->grpdel(groupname);

#all fields are returned from the class methods fields/gfields
print $user->get($_) for (Linux::usermod->fields);
print $grp->get($_) for (Linux::usermod->gfields);

#set working passwd and shadow files

#$Linux::usermod::file_passwd = "./my_passwd";
#$Linux::usermod::file_shadow = "./my_shadow";
#$Linux::usermod::file_group  = "./my_group";
#$Linux::usermod::file_gshadow= "./my_gshadow";

---

🦋 DESCRIPTION 🦋

So what does she actually DO? This module adds, removes and modifies user and group accounts, following the passwd and shadow file syntax — like struct passwd from pwd.h, if you speak C. 💅

And here's the part that's honestly iconic: those accounts do not have to be system accounts, as long as $Linux::usermod::file_passwd, $Linux::usermod::file_shadow, $Linux::usermod::file_group and $Linux::usermod::file_gshadow are not sitting in the "/etc" directory. Do your own thing, bestie. 🌈

---

🎀 METHODS 🎀

new

Linux::usermod->new(username)
Linux::usermod->new(grpname, 1)

If you want a group object, that second 'true' argument is non-negotiable — it must be given. 🫡

add

(username, ...) — class method, adds a shiny new user account. The arguments are optional, except username. They may be:

(username, password, uid, gid, comment, home, shell)

del

(username) — class method, removes a user account. bye bestie 👋

tobsd

converts user fields in shadow / master.passwd file to bsd style 🍓

get

If you call her on a user object, you get back one of these fields:

• 'name' or 0 — The user's name
• 'ppassword' or 1 — The passwd file password
• 'uid' or 2 — The user's id
• 'gid' or 3 — The user's group id
• 'comment' or 4 — The comment about the user (real username)
• 'home' or 5 — The user's home directory
• 'shell' or 6 — The user's shell
• 'sname' or 7 — The user's name in shadow file
• 'password' or 8 — The 13-character encoded password
• 'lastchg' or 9 — The number of days since January 1, 1970 of the last password changed date
• 'min' or 10 — The minimum number of days required between password changes
• 'max' or 11 — The maximum number of days the password is valid
• 'warn' or 12 — The number of days before expiring the password that the user is warned
• 'inactive' or 13 — The number of days of inactivity allowed for the user
• 'expire' or 14 — The number of days since January 1, 1970 that account is disabled
• 'flag' or 15 — Currently not used 🙈

If you call her on a group object instead, you get one of these:

• 'name' or 0 — The group name
• 'ppassword' or 1 — The group password
• 'gid' or 2 — The group id number
• 'users' or 3 — The group members (users)
• 'sname' or 4 — The group name in gshadow file (the same as 'name')
• 'password' or 5 — The encrypted group password
• 'ga' or 6 — The group administrators
• 'gu' or 7 — The group members (users) (the same as 'users')

and your argument can be either a string or a number, so do whatever feels right ✨

set

(field)

sets a field, which must be a string of characters:

@user_fields = Linux::usermod->fields;        #user fields
@group_fields = Linux::usermod->gfields;      #group fields

grpadd

(groupname)

grpdel

(groupname)

lock

(username) — locks the user account (puts '!' at the beginning of the encoded password) 🔒

unlock

(username) — unlocks the user account (removes '!' from the beginning of the encoded password) 🔓

users

Class method — returns a hash whose keys are all users, taken from $file_passwd.

grps

Class method — returns a hash whose keys are all groups, taken from $file_group. 👑

---

💜 FILES 💜

/etc/passwd /etc/shadow /etc/group /etc/gshadow

unless you bring your own passwd, shadow, group, gshadow files — which, heads up, must be created. 🧚

---

🌟 TO DO 🌟

Groups and user accounts consistency checks. (manifesting this for her 🕯️)

---

👑 SEE ALSO 👑

getpwent(3), getpwnam(3), usermod(8), passwd(1), gpasswd(1)

---

💀 BUGS 💀

None known. Report any to author. (if you find one, do NOT gatekeep, tell her)

---

💖 AUTHOR 💖

Vidul Petrov, vidul@abv.bg

(C) 2004 Vidul Petrov. All rights reserved.

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

---

okay and finally, the little receipts at the bottom: this whole thing is from perl v5.36.0, dated 2022-10-15, filed under usermod(3pm). periodt 💅✨🎀