Safely Replace Linux Account Files with cppw and cpgr

You will finish with a controlled way to copy a prepared account file into /etc/passwd, /etc/group, /etc/shadow or /etc/gshadow, while letting cppw or cpgr take the relevant lock. The examples use the passwd package version 1:4.13+dfsg1-4ubuntu3.2 installed on this machine.

Allow 15 to 30 minutes, plus time to validate the source file. You need a root shell or equivalent permission to replace the system account database, a prepared file readable by that account, and a maintenance plan if services or users may be affected. This is a security-sensitive operation: do not experiment against a live file or paste an untrusted path into a privileged command.

1. Check the installed command

First confirm which executable will run and read its built-in help. These checks are ordinary and do not change account files:

$ command -v cppw
/usr/sbin/cppw
$ dpkg-query -W -f='${Package} ${Version}\n' passwd
passwd 1:4.13+dfsg1-4ubuntu3.2
$ cppw -h
Usage:
`cppw <file>' copys over /etc/passwd   `cppw -s <file>' copys over /etc/shadow
`cpgr <file>' copys over /etc/group    `cpgr -s <file>' copys over /etc/gshadow

The spelling in that help text is supplied by the installed program. The useful part is the command shape: one source file, with an optional -s switch. The manual documents no long options, so use the short forms shown here.

2. Map the command to its destination

Choose the command from the destination you intend to replace. Without -s, cppw copies its source to /etc/passwd; cpgr copies to /etc/group. With -s, they target the shadow counterparts:

The name cppw is used for both password-file targets, and cpgr for both group-file targets. Do not select -s merely because the source file is private. Select it because the destination is the shadow file.

3. Prepare and inspect the source

cppw and cpgr are copy-with-lock tools. Their manual page does not promise to repair malformed records or reconcile related files. Prepare the source with a tool that understands the account database, then inspect it before replacement. Keep the path explicit and quote it:

# SOURCE='/root/account-staging/passwd.new'
# test -r "$SOURCE" && printf 'readable: %s\n' "$SOURCE"
# pwck -r "$SOURCE"
readable: /root/account-staging/passwd.new

The exact options accepted by pwck are outside cppw's contract, so use the validation tool and procedure appropriate to the file format on your host. For a group file, use the corresponding group checker if it is installed. If validation reports an error, stop and fix the source. Do not use the copy command as a test of whether the data is safe.

Before touching /etc, make a timestamped backup through your normal privileged backup process. Record which source belongs to which destination. A backup of /etc/passwd is not a substitute for a backup of /etc/shadow, and neither is a substitute for the group files.

4. Replace one file, with the correct privilege

Run only the mapping you checked in the previous step. The following example replaces the password file from a prepared source and lets the program perform its documented locking:

# cppw /root/account-staging/passwd.new

There is normally no success message. Check the exit status immediately:

# printf 'cppw exit status: %s\n' "$?"
cppw exit status: 0

For a group file, use cpgr:

# cpgr /root/account-staging/group.new
# printf 'cpgr exit status: %s\n' "$?"
cpgr exit status: 0

Writing these destinations normally needs elevated privileges. If you run the command as an ordinary user, expect a permission failure rather than a partial permission workaround. Do not make the destination world-writable and do not weaken its ownership or mode to get past the error.

5. Replace a shadow file only when that is the plan

The -s option changes the destination, not the input format or the locking idea. Use it deliberately:

# cppw -s /root/account-staging/shadow.new
# printf 'shadow replacement exit status: %s\n' "$?"
shadow replacement exit status: 0

# cpgr -s /root/account-staging/gshadow.new
# printf 'gshadow replacement exit status: %s\n' "$?"
gshadow replacement exit status: 0

Shadow files contain authentication-sensitive data. Restrict access to the staging directory and remove temporary copies through your approved process after the replacement has been verified. Never include their contents in a support ticket or a command transcript.

6. Verify the result and recover if needed

Run read-only checks after the copy. Compare the destination with the prepared source using a method that does not disclose shadow contents to other users, and run the appropriate account-file checker:

# pwck -r
# grpck -r
# getent passwd example-user
# getent group example-group

The getent lookups should show the expected records if those names exist in the active account source. Check the service or login path that motivated the change, using a test account where possible. If the command failed, or validation finds a problem, do not repeat it with a different random source.

There is no undo switch. Recovery means running cppw or cpgr again with the known-good backup for the same destination, using -s for a shadow destination, then repeating the checks. If the account database is inconsistent or authentication is already failing, use the host's documented recovery console or maintenance procedure and keep the original backup intact.