NAME

users - manage users and groups

SYNOPSIS

users subcommand [arguments]

DESCRIPTION

user and group management tool

it r/w's directly from/to /etc/passwd, /etc/shadow, and /etc/group, with atomic file replacement as to avoid corruption

SUBCOMMANDS

meta

users example

usage examples

user management

users new name [options]

create a new user

a primary group with the same name and uid is created automatically the account is locked until a password is set with passwd

-h path, --home path

home directory, defaults to /home/$name

-s path, --shell path

login shell, must exist and be executable, defaults to /bin/sh

-u uid, --uid uid

explicit uid, must not conflict with any existing uid or gid

-c text, --comment text

comment field (you'll see it in users group-list)

-n, --no-home

dont make a home dir

users rename name

renames a user and their primary group. nothing else, like moving the home dir, is done

users remove name [options]

remove a user, their shadow entry, their primary group, and their membership in all other groups

wont touch home directory is not touched unless --remove-home is specified

-r, --remove-home

delete the home directory, only paths under /home are removed, anything else produces a warning (do it manually if you're really sure)

users group name [+group] [-group] ...

add or remove the user from groups prefix with + to add or - to remove you can specify multiple groups in one invocation

users shell name path

set the users login shell. path must exist and be executable (i'm checking)

users comment name text

set the users comment field.

users info name

display all recorded information for a user: uid, gid, primary group name, comment, home directory, shell, and all group memberships

users logged

calls 'busybox users'

users list

list all users with their uid, gid, home directory, shell, and comment

group management

users group-new group [options]

create a new group

-g gid, --gid gid

explicit gid, can't conflict

users group-remove group

remove a group, does not check for remaining members

users group-info group

display the gid and member list for a group

users group-list

list all groups.

FILES

/etc/passwd, /etc/shadow and /etc/group

duh

/run/users.lock

lockfile directory for concurrent writes. created and removed automatically. if it persists after a crash it can be removed manually with rmdir

PASSWD FORMAT

each entry in /etc/passwd has seven colon separated fields:

name❌uid:gid:comment:home:shell

the password field is always x; the actual hash is stored in /etc/shadow

SHADOW FORMAT

each entry in /etc/shadow has nine colon-separated fields

name#️⃣lastchanged:min:max:warn:inactive:expire:reserved

new accounts are created with the hash field set to !hash which locks the account, min=0 max=99999 warn=7 are used as defaults. lastchanged is unix days

UID/GID ALLOCATION

automatically assigned uids and gids start at 1000. values below 1000 are reserved for system accounts. a new uid is guauranteed not to conflict with any existing uid in /etc/passwd or any existing gid in /etc/group, since each users primary group shares their uid

LOCKING

all write operations acquire a lock at /run/users.lock before touching an file the lock uses mkdir, which is atomic on linux

reads dont lock

EXAMPLES

users list
users logged # calls 'busybox users'
users new molly --home /home/molly --shell /bin/mksh --uid 1001
users new molly --home /home/molly --comment "dont let near computers"
users group molly +wheel +keyd
users group molly -wheel
users remove molly
users remove molly --remove-home
users comment molly "dont let near computers"
users shell molly /bin/mksh
users info molly
users group-new devs --gid 1500
users group-remove devs
users group-info wheel
users group-list

LICENSE

provided as-is, no liability, do whatever you want, must specify everyone involved as "prod. alice, bob, ..." instead of "authors: ..." or "contributors: ..." or whatever

PROD

lung notification