Home / Alt manpages / chgpasswd(8)

  • chgpasswd(8)
  • Admin command
  • linux

Set Group Passwords in Bulk with chgpasswd

You need to set a password on a Linux group without leaving it in your shell history, and chgpasswd does exactly that. This guide covers the chgpasswd in the Ubuntu passwd package, version 1:4.13+dfsg1-4ubuntu3.2, and takes about ten minutes for one group, plus time to check your local password policy.

The route

Jump straight to the step you need, or tick off Done means at the end.

  • You need root. Normally that means sudo, and the target group must already exist.
  • It writes to /etc/gshadow. Make sure you are on the intended host before you run the write command.
  • Have a way back. There is no undo flag (see step 5).

1. Check the target group

Start with a read-only lookup to confirm the group name. Replace GROUP_NAME with the real name, without angle brackets.

$ getent group GROUP_NAME
GROUP_NAME:x:2001:alice,bob
  • Expect different numbers. The numeric ID and member list will differ on your system.
  • No output means stop. chgpasswd updates existing groups; it does not create one. Provision the group through your normal identity-management process first.

Checkpoint

The returned name is the group whose password you intend to change. A typo can select a different existing group, and a directory service may make the result look different from a local /etc/group entry.

2. Read the password without putting it on the command line

By default, chgpasswd expects each input line to be a group name, a colon and a clear-text password. Do not type that password into a command that will land in shell history. Read it silently instead:

read -r -s -p 'New group password: ' NEW_GROUP_PASSWORD
printf '\n'
printf '%s:%s\n' 'GROUP_NAME' "$NEW_GROUP_PASSWORD" | sudo chgpasswd -c SHA512
status=$?
unset NEW_GROUP_PASSWORD
printf 'chgpasswd status: %s\n' "$status"
exit "$status"
  • Input arrives on standard input. sudo elevates only chgpasswd, not the shell variable or the prompt.
  • The unset cleans up. It removes the variable from the current shell.
  • The password is still sensitive while the command runs. Use a trusted terminal, avoid recording the session, and never paste a real password into a ticket or chat.

The -c SHA512 option selects the SHA-512 crypt method for clear-text input. The installed help also lists NONE, DES, MD5, SHA256, SHA512 and YESCRYPT as method names. The installed manual documents DES, MD5, NONE, SHA256 and SHA512, and warns that DES and MD5 should not be used for new hashes.

Tip

Choose a method your local policy permits rather than copying SHA512 blindly.

3. Verify the write completed

Straight after the command, status 0 means the update completed successfully:

chgpasswd status: 0

A non-zero status means the update did not complete as expected. Keep the exact diagnostic and status, and do not retry repeatedly with a password pasted into the terminal. Check these instead:

  • The group name. Is it spelt as getent showed it?
  • Permissions. Did sudo actually elevate?
  • The selected method. Is it one this system accepts?
  • Where the database lives. Is the account database local or centrally managed?

As root, inspect only the hash format and the group name. Do not print the whole secret-bearing file into a shared log:

sudo awk -F: '$1 == "GROUP_NAME" { print $1 ":" $2 }' /etc/gshadow

For SHA-512, the second field normally begins with $6$, although the exact salt and hash are unique. The password cannot be recovered from this field.

Warning

Treat the complete /etc/gshadow file as confidential anyway, because it contains group security data.

4. Use pre-hashed input only with a verified hash

The --encrypted or -e option tells chgpasswd not to hash the supplied value. Each line keeps the same group:password shape, but the password field must already be in a format the system's crypt implementation accepts.

printf '%s\n' 'GROUP_NAME:PASTE_A_VERIFIED_CRYPT_HASH_HERE' | sudo chgpasswd --encrypted

This is not a command for a plain password. Mixing up the two modes can store the wrong value or produce a hash that cannot authenticate.

Warning

Handle the source hash as a credential, restrict its permissions, and remove temporary files using your organisation's secure procedure after the update.

5. Understand configuration and rollback

When no method is supplied, chgpasswd follows ENCRYPT_METHOD in /etc/login.defs. On this machine that setting is SHA512.

  • Round limits. The same file can define SHA_CRYPT_MIN_ROUNDS and SHA_CRYPT_MAX_ROUNDS for SHA-256 or SHA-512.
  • --sha-rounds. It accepts 0 for the system default, otherwise the manual enforces a range from 1,000 to 999,999,999. It is valid only with SHA-256 or SHA-512.

Do not edit /etc/login.defs just to repair one group password. The setting affects future group-password generation, not existing hashes, and user-password generation is handled by PAM. Coordinate any policy change separately.

Recovery

There is no generic undo flag, so before a change record the target group and, if policy allows, retain an authorised previous crypt hash. If the update caused a service or workflow problem, set a new known-good group password with the same procedure rather than trying to recover the clear text. Do not restore an untrusted copy of /etc/gshadow over the live file.

6. Apply the same operation inside a root directory

-R or --root takes an absolute directory and uses the configuration files below it. That suits an offline system image, but it is not a dry run. The directory must contain the relevant account files and the command must be able to enter it with the required privilege.

# chgpasswd --root /srv/target-root --crypt-method SHA512 < group-passwords.txt

The input file holds one group:password record per line and must be protected from other users. Test the image workflow on a disposable copy first.

Tip

An error from --root does not prove the host configuration is broken. The path may not be absolute, the directory may be incomplete, or the caller may be unable to chroot into it.

Done means

  • The group existed. You checked the name with getent before writing.
  • The password went in on standard input. It never appeared in a shell-history command.
  • The method matches policy. The command returned status 0.
  • The hash was checked safely. You looked at one field, not the whole /etc/gshadow file.
  • You have a way back. You know how to set a replacement password if the change must be reversed.