Batch-create Linux Accounts Safely with newusers

You will finish with a controlled batch file that creates Linux accounts, assigns their primary groups and home directories, and lets newusers set their passwords through the system's PAM configuration. The examples match shadow-utils 4.13, installed here as passwd 1:4.13+dfsg1-4ubuntu3.2.

Allow about 20 minutes, including a careful review. You need root access, a maintenance plan for the account database, and a private working directory. This command changes /etc/passwd, /etc/shadow, /etc/group and potentially /etc/gshadow. Do not experiment on a production host without a backup and a tested recovery route.

1. Check the installed command

Read the local command help before preparing input. This is an ordinary, read-only check:

$ command -v newusers
/usr/sbin/newusers
$ newusers --help
Usage: newusers [options]

Options:
  -b, --badname                 allow bad names
  -h, --help                    display this help message and exit
  -r, --system                  create system accounts
  -R, --root CHROOT_DIR         directory to chroot into
$ dpkg-query -W -f='${Package} ${Version}\n' passwd
passwd 1:4.13+dfsg1-4ubuntu3.2

Only the options shown here are part of this installed interface. The input can be a named file or standard input. The command must be run with elevated privileges because it writes the system account databases.

2. Understand the seven input fields

Each input line has the same seven colon-separated fields as a password-file entry:

pw_name:pw_passwd:pw_uid:pw_gid:pw_gecos:pw_dir:pw_shell

For a new ordinary user, leave the UID empty, use the user's name as the GID field, describe the account in the GECOS field, choose an explicit home path, and select a real shell. For example:

alice:$6$REPLACE_WITH_A_HASH: :alice:Alice Example:/home/alice:/bin/bash

There must not be a space in the empty UID field. The compact form is:

alice:$6$REPLACE_WITH_A_HASH::alice:Alice Example:/home/alice:/bin/bash

The password field is treated as input for the account password and the file contains unencrypted password material while you prepare it. Do not put a normal plaintext password in this field. The safest operational choice is to use a locked placeholder and set passwords separately through your approved enrolment process. If your PAM policy permits it, a precomputed password hash can be supplied, but protect the file just as carefully.

The UID field accepts an empty value for automatic allocation, a number, or the name of an existing user whose UID should be reused. The GID field accepts an existing group name, a number, or a new group name. An unknown group name causes a group to be created. A numeric GID with no matching group also causes a group named after the user to be created.

3. Prepare a private batch file

Create the file in a directory accessible only to root. The following example uses a locked password marker, so it does not place a usable password in the batch file:

# install -d -m 0700 /root/newusers-work
# install -m 0600 /dev/null /root/newusers-work/accounts.txt
# editor /root/newusers-work/accounts.txt

Put one line per account, with no header:

alice:!: :alice:Alice Example:/home/alice:/bin/bash
bob:!: :bob:Bob Example:/home/bob:/bin/bash

Remove the spaces around the empty UID field before saving. The valid version is:

alice:!::alice:Alice Example:/home/alice:/bin/bash
bob:!::bob:Bob Example:/home/bob:/bin/bash

Review every username, group name, home path and shell. A shell field is not checked for existence by newusers, so a typo can leave an account unable to start a login shell. The command also does not create missing parent directories. /home must exist before /home/alice can be created.

4. Check the target paths before changing accounts

These checks do not alter account databases. Confirm that the parent directory exists and that the requested shells are present:

# test -d /home && echo '/home exists'
/home exists
# test -x /bin/bash && echo '/bin/bash is executable'
/bin/bash is executable
# getent passwd alice bob

An empty result from getent means those names are not currently returned by the configured name service. If either name already exists, stop and decide whether an update is really intended. An existing user's fields will be changed by newusers; it is not an update-free create-only command.

5. Run the batch with a review point

Take a backup using your normal system backup process before the write. Then run the file as root:

# cp --preserve=mode,ownership,timestamps /root/newusers-work/accounts.txt /root/newusers-work/accounts.txt.before-run
# newusers /root/newusers-work/accounts.txt
# printf 'newusers exit status: %s\n' "$?"
newusers exit status: 0

Do not treat the shown output as guaranteed terminal output: a successful run may be silent. The exit status is the useful first check. Shadow performs a first pass for account and group changes, then a second pass for password updates through PAM. Password-update failures are reported but do not necessarily stop all other password updates.

The database update is designed to avoid committing the first-pass changes if an error occurs before the final writes. That is not a substitute for a backup. A final database write failure, a home-directory creation failure, or a later service policy can still leave work to repair.

6. Verify identities, groups and homes

Check each account through the system's name-service view:

# getent passwd alice
alice:!:1001:1001:Alice Example:/home/alice:/bin/bash
# id alice
uid=1001(alice) gid=1001(alice) groups=1001(alice)
# stat -c '%U:%G %a %n' /home/alice
alice:alice 750 /home/alice

Your UID and mode can differ. On this host, UID_MIN and GID_MIN are 1000, and HOME_MODE is 0750. If HOME_MODE is unset, the UMASK value influences the home-directory mode instead. Check the actual result rather than assuming a default.

If a home directory could not be created because its parent was missing, newusers can continue processing the batch. The account may exist without its requested home. Create the parent, then create and chown the home deliberately, or correct the input and use a documented recovery procedure. Changing a home path for an existing account does not move or copy the old contents.

7. Set or recover passwords separately

A locked marker such as ! is useful when account creation and password delivery are separate stages. Confirm the account is locked, then use your approved password-setting or identity-management workflow:

# passwd -S alice
alice L 2026-09-25 0 99999 7 -1
# passwd alice

The exact status date and fields vary. The L indicates a locked password in the common shadow implementation. The second command is interactive and requires elevated privileges. It changes only the password, not the UID, group, home or shell.

Do not unlock an account merely because a login test failed. Check the shell, PAM rules, account expiry, directory ownership and the service that performs authentication. A batch file with a readable password is a credential exposure that cannot be undone by deleting the file from disk alone.

8. Undo a mistaken run carefully

There is no general rollback switch for newusers. For an account created by mistake, stop dependent services first, preserve evidence if required, and use your organisation's account-removal process. Do not manually edit /etc/passwd or /etc/shadow while an account-management tool is running.

Removing an account does not automatically make its files safe to delete, and it can make ownership harder to interpret. Find files owned by the old numeric UID, decide whether they belong to the account, and only then remove or reassign them. For an existing account whose UID or home was changed, restore from backup or reverse the specific change with a reviewed command; newusers does not move old home contents for you.