Sync /etc/shells with update-shells

A shell an administrator added by hand can vanish the moment a package touches /etc/shells, unless update-shells knows to leave it alone. The command comes from debianutils; the machine used for these examples has package version 5.17build1.

Allow about ten minutes. You need a shell and debianutils. Previewing a real host needs write access to its temporary files, and applying the update needs root. The guide uses a temporary root first, so you can see the behaviour without changing the host.

1. Check the installed contract

Read the local manual and identify the binary before changing anything:

$ man 8 update-shells
$ command -v update-shells
/usr/sbin/update-shells
$ dpkg-query -W -f='${Package} ${Version}\n' debianutils
debianutils 5.17build1

update-shells reads packaged shell paths from /usr/share/debianutils/shells.d, updates /etc/shells, and records the packaged set in /var/lib/shells.state. It is not a general-purpose editor for /etc/shells.

2. Understand what is managed

Inspect the inputs as an ordinary, read-only operation:

$ sed -n '1,120p' /usr/share/debianutils/shells
$ find /usr/share/debianutils/shells.d -maxdepth 1 -type f -print -exec sed -n '1,40p' {} \;
$ sed -n '1,120p' /etc/shells
$ sed -n '1,120p' /var/lib/shells.state

The package template and files in shells.d describe shells supplied by packages. The state file lets the command distinguish an old packaged entry from a local addition: a line not recorded as packaged is preserved when the command rebuilds /etc/shells, including something like /usr/local/bin/my-shell.

That distinction is the main safety boundary. If you want to add or remove a local shell, use the appropriate account-management procedure and then inspect the resulting file. Do not place a package path into shells.d by hand unless you are maintaining packaging integration.

3. Preview with a disposable root

--root makes the command operate below a directory, useful for testing a proposed layout or maintaining a chroot. The root must contain the relevant etc, var/lib and Debianutils data paths.

$ ROOT_DIR='/tmp/my-login-shell-root'
$ mkdir -p "$ROOT_DIR/etc" "$ROOT_DIR/var/lib" \
    "$ROOT_DIR/usr/share/debianutils/shells.d"
$ cp /usr/share/debianutils/shells \
    "$ROOT_DIR/usr/share/debianutils/shells"
$ cp /usr/share/debianutils/shells.d/* \
    "$ROOT_DIR/usr/share/debianutils/shells.d/"
$ printf '%s\n' '# test root' '/bin/sh' '/usr/local/bin/my-shell' \
    > "$ROOT_DIR/etc/shells"
$ printf '%s\n' '/bin/sh' > "$ROOT_DIR/var/lib/shells.state"
$ update-shells --root "$ROOT_DIR" --no-act --verbose
adding shell /bin/bash
adding shell /bin/rbash
adding shell /usr/bin/dash
adding shell /usr/bin/tmux

The exact additions depend on the package files installed on your system. What matters is that --no-act reports changes without replacing the target files:

$ sed -n '1,40p' "$ROOT_DIR/etc/shells"
# test root
/bin/sh
/usr/local/bin/my-shell

4. Apply a tested update

Applying the update replaces ROOT_DIR/etc/shells and writes ROOT_DIR/var/lib/shells.state. Treat this as a system configuration change: check the verbose preview first, then run the same command without --no-act with elevated privileges.

$ sudo update-shells --verbose
adding shell /bin/bash
adding shell /bin/rbash
adding shell /usr/bin/dash
adding shell /usr/bin/tmux

No output means no packaged shell needed adding or removing. The command does not restart a service, but authentication tools can consult /etc/shells, so check the result before relying on it for new logins.

Verify both files immediately:

$ getent shells
$ sed -n '1,120p' /var/lib/shells.state
$ sudo update-shells --no-act --verbose

5. Handle removals and recovery

When a packaged shell disappears, update-shells can remove its old entry from /etc/shells if that entry is present in the state it manages. Entries not recorded as packaged are retained. That is why manually deleting lines from /var/lib/shells.state is unsafe: it destroys the information needed to classify the next change.

If a preview fails, capture the error and status without chaining another command over it:

$ sudo update-shells --no-act --verbose
$ status=$?
$ printf 'update-shells status: %s\n' "$status"
update-shells status: 0

A non-zero status means the proposed operation was not verified. Check that the root paths exist, that the target directories are writable by the elevated command, and that the shell data files are readable. Do not treat a failed preview as evidence that no update is needed.