Pierre Warnier
b516b87be8
* docs: the upstream suite is not GNU, and is mostly BSD-licensed The README called the original shadow-utils a GNU project and GPL-2.0+, and CONTRIBUTING grounded the clean-room policy on that. Neither holds, as #320 points out: shadow-maint/shadow is not a GNU project, and its tree is mostly BSD-3-Clause with GPL-2.0-or-later files among it -- su.c, vipw.c, contributed scripts, some translated manuals. Checked against Debian's copyright file for the package and Fedora's licence tag, BSD-3-Clause AND GPL-2.0-or-later, not against the source. The policy stands, on the accurate ground: this is an independent MIT implementation that copies from neither part. Copying from the BSD part would carry attribution terms this project does not take on; from the GPL part, a derivative work; sorting files by licence would mean reading them. So the rule is unchanged: do not read that tree. Every "GNU" that meant upstream is now "upstream" or "the distribution's package": README, CONTRIBUTING, Makefile, the man pages' section heading, the e2e image and suite, test comments. make test-gnu-compat is make test-upstream-compat and its script is renamed with it. The 2026-05-04 audit record gets an erratum at the top and is otherwise left as it was run. * docs: the last upstream-as-GNU mentions in the compat suite and the tool table * tests: say upstream, not GNU, in the test comments and skip messages too * tests: one more * docs: keep the README's clean-room line as it was, reworded around it
3.8 KiB
vipw(8) - edit the password, group, shadow or gshadow file
NAME
vipw, vigr - edit the password, group, shadow or gshadow file
SYNOPSIS
vipw [options]
vigr [options]
DESCRIPTION
The vipw and vigr commands edit /etc/passwd and /etc/group respectively. With the -s flag they edit the shadow versions of those files, /etc/shadow and /etc/gshadow. The two are one program: vigr is vipw with the group file as its default.
The point of using them rather than an editor directly is the lock. vipw takes the same lock every other tool in the suite takes, so a hand edit cannot interleave with a useradd(8) running at the same moment — the other tool waits — and the result is installed atomically, so a crash mid-write cannot leave a half-written /etc/passwd.
The editor is taken from VISUAL, then EDITOR, then vi. The string
goes through the shell, so EDITOR="emacs -nw" works. Signals such as Ctrl-C
reach the editor normally; they do not reach vipw, which would otherwise
die holding the lock.
HOW AN EDIT PROCEEDS
- The lock is taken and the file copied to a working copy beside it,
/etc/passwd.edit, with the same mode and ownership. A stale copy from a crashed run is replaced. - The editor runs on the working copy.
- If the editor exits with an error, the working copy is removed and nothing is installed.
- If the working copy is identical to the original, nothing is installed and file is unchanged is reported.
- The working copy is parsed as the file it is meant to be. If it does not parse, it is kept, its location is printed, and the live file is left alone.
- Otherwise the working copy's bytes are installed as they are — comments and blank lines included — and the companion file that usually has to change alongside is named.
OPTIONS
- -g, --group
- Edit the group database.
- -p, --passwd
- Edit the passwd database.
- -s, --shadow
- Edit the shadow counterpart of the selected database.
- -q, --quiet
- Do not report an unchanged file or suggest the companion edit.
- -R, --root CHROOT_DIR
- Apply changes in CHROOT_DIR and use its configuration files.
- -P, --prefix PREFIX_DIR
- Edit the account files under PREFIX_DIR without chrooting.
DIFFERENCES FROM UPSTREAM SHADOW
The result is checked before it is installed. upstream vipw installs whatever the editor saved — a line with no colons, or a UID 0 account with an empty password field — and leaves pwck(8) to find it later. Here a file the rest of the suite could not parse is refused. The check is structural: it does not judge the contents, and pwck(8) and grpck(8) remain the tools for that. When it refuses, the edited copy is kept rather than discarded: an administrator whose ten minutes of work vanished would use a raw editor next time, which is the outcome this tool exists to prevent.
Changes are detected by content, not by timestamp. upstream compares modification times in whole seconds, so an edit saved within the same second as the copy was made is silently thrown away. Any edit that changes a byte is installed here.
EXIT STATUS
- 0
- The file was installed, or was unchanged.
- 1
- The editor failed, the result did not parse, the lock could not be taken, or the caller is not root. Nothing was installed.
- 2
- Invalid command syntax.
- 3
- The --root directory could not be entered.
ENVIRONMENT
- VISUAL, EDITOR
- The editor, in that order of preference. An empty value counts as unset.
FILES
- /etc/passwd, /etc/shadow, /etc/group, /etc/gshadow
- The files edited.
- /etc/passwd.edit and so on
- The working copy, beside the file it copies. Left in place only when the edit was refused.
SEE ALSO
group(5), grpck(8), passwd(5), pwck(8), shadow(5), useradd(8)