Safely Convert Linux Passwords and Groups to Shadow Files

pwconv and grpconv move your password and group databases into shadow-file form, and with no dry-run flag, a tested backup has to do that job instead. The examples use the passwd package version 1:4.13+dfsg1-4ubuntu3.2 on this machine, from shadow-utils 4.13. Allow about fifteen minutes, plus time to arrange a maintenance window if this is a production host.

Warning: this is an elevated operation. pwconv and grpconv change authentication files, so take a backup first and make sure you have another root shell or console path available. Do not experiment directly on a live system with a copied command from an unfamiliar guide.

1. Check the installed commands

First confirm which programs are installed and which package supplied them. These checks are ordinary and change nothing:

$ command -v pwconv grpconv pwunconv grpunconv
/usr/sbin/pwconv
/usr/sbin/grpconv
/usr/sbin/pwunconv
/usr/sbin/grpunconv
$ dpkg-query -W -f='${Package} ${Version}\n' passwd
passwd 1:4.13+dfsg1-4ubuntu3.2

Your package version may differ. The installed manual page identifies this set of tools as shadow-utils 4.13. The commands have only two relevant options here: --help and --root CHROOT_DIR. There is no dry-run option in this interface, so checking and backing up are separate steps.

2. Check the account databases before conversion

Malformed or duplicate entries are a real boundary for these programs. The manual page warns that bad password or group files can make conversion loop or fail in strange ways. Run the checkers before taking a lock on the conversion:

$ sudo pwck
$ sudo grpck

Read any diagnostic rather than blindly accepting a non-zero result. Fix the reported account data using your normal account-management process, then run both checks again. If these commands report problems you cannot explain, stop here: a conversion is not a repair tool.

Checkpoint: continue only when pwck and grpck complete without unresolved errors.

3. Back up the four files

The tools operate on /etc/passwd, /etc/shadow, /etc/group and /etc/gshadow. Save all four together, preserving ownership and modes:

$ sudo install -d -m 700 /root/account-files-before-pwconv
$ sudo cp -a /etc/passwd /etc/shadow /etc/group /etc/gshadow \
    /root/account-files-before-pwconv/

Warning: do not put this backup in a directory readable by ordinary users. In particular, /etc/shadow and /etc/gshadow contain password hashes or protected group data. Check the backup exists before changing anything:

$ sudo ls -l /root/account-files-before-pwconv/
$ sudo stat -c '%n %a %U:%G' /root/account-files-before-pwconv/*

The directory name above is an example; replace it with your own dated location if your recovery process requires one. The copy command overwrites files if that exact backup already exists, so choose a new directory or inspect it first.

4. Convert password entries with pwconv

Run this command with elevated privileges:

$ sudo pwconv

pwconv creates or updates /etc/shadow from /etc/passwd. It removes shadow entries with no matching main-file entry, updates entries whose password field is not x, adds missing entries, and then replaces password fields in /etc/passwd with x. It takes the necessary locks during the conversion.

There may be no success message. Verify both sides instead of relying on terminal output:

$ sudo test -s /etc/shadow && echo 'shadow file exists'
shadow file exists
$ sudo awk -F: '$2 != "x" { print $1 ": password field is not x" }' /etc/passwd
$ sudo pwck
authentication files checked

The second command should print nothing for accounts whose passwords are represented in the shadow file. The final checker is the useful checkpoint.

Warning: do not paste password hashes into tickets, shell history or chat while investigating.

5. Convert group entries with grpconv

If you also need shadow group data, convert it separately:

$ sudo grpconv
$ sudo test -s /etc/gshadow && echo 'gshadow file exists'
gshadow file exists
$ sudo grpck

grpconv applies the equivalent process to /etc/group and /etc/gshadow. Group entries are synchronised, missing shadow entries are added, and the group password field in the main file is replaced with x. A successful command may still be silent, so the file test and grpck are the checkpoint.

If your site sets MAX_MEMBERS_PER_GROUP in /etc/login.defs, grpconv can split a long group into repeated entries once the configured member limit is reached. The installed manual page gives 0 as the default, meaning no limit, and mentions 25 as an example limit for systems that need shorter lines. Split groups are not supported by every tool, so do not add this setting just because it exists.

6. Understand password ageing defaults

When pwconv adds new entries to /etc/shadow, it reads PASS_MIN_DAYS, PASS_MAX_DAYS and PASS_WARN_AGE from /etc/login.defs. If those settings are absent, the documented defaults are minimum age 0, maximum age -1, and no warning. In other words, conversion does not automatically impose a password-expiry policy that is not configured.

$ sudo grep -E '^[[:space:]]*PASS_(MIN|MAX)_DAYS|^[[:space:]]*PASS_WARN_AGE' /etc/login.defs
PASS_MAX_DAYS   99999
PASS_MIN_DAYS   0
PASS_WARN_AGE  7

Your output may be empty or different. Treat these values as policy, not as proof every existing account has the same ageing state. Inspect account ageing with the account-management tools your distribution provides, and change policy deliberately rather than editing shadow fields by hand.

7. Treat the unconv commands as destructive

pwunconv copies what it can from /etc/shadow back into /etc/passwd and then removes /etc/shadow. Some password ageing information is lost. grpunconv does the corresponding operation for /etc/gshadow. These are not routine verification commands and should not be used to test whether conversion worked.

If a rollback is genuinely required, stop password-changing activity, confirm your backup is the intended one, and restore all four files as one operation:

$ sudo install -m 644 /root/account-files-before-pwconv/passwd /etc/passwd
$ sudo install -m 640 -o root -g shadow /root/account-files-before-pwconv/shadow /etc/shadow
$ sudo install -m 644 /root/account-files-before-pwconv/group /etc/group
$ sudo install -m 640 -o root -g shadow /root/account-files-before-pwconv/gshadow /etc/gshadow
$ sudo pwck
$ sudo grpck

Use the ownership and modes from your distribution if they differ. Restoring files while another tool is editing them can lose a concurrent account change, so use the maintenance procedure for the host. If you only need to inspect a different root, the supported form is sudo pwconv --root /absolute/path; the directory must be an absolute path and contain the expected configuration files. It is still a write operation inside that root.

Done means