From d562c66b08a54cdb5726a14caa27065e394ebc2d Mon Sep 17 00:00:00 2001 From: upstream Date: Mon, 12 Oct 2026 19:26:37 +0200 Subject: [PATCH] Upstream debian-debian/adduser state of the touched files before ef9bdf9502 --- doc/adduser.8 | 990 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/deluser.8 | 328 +++++++++++++++++ 2 files changed, 1318 insertions(+) create mode 100644 doc/adduser.8 create mode 100644 doc/deluser.8 diff --git a/doc/adduser.8 b/doc/adduser.8 new file mode 100644 index 0000000..b4ecfa3 --- /dev/null +++ b/doc/adduser.8 @@ -0,0 +1,990 @@ +.\" Copyright: 1994 Ian A. Murdock +.\" 1995 Ted Hajek +.\" 1997-1999 Guy Maor +.\" 2000-2003 Roland Bauerschmidt +.\" 2004-2025 Marc Haber +.\" 2011 Justin B Rye +.\" 2016 Afif Elghraoui +.\" 2016 Helge Kreutzmann +.\" 2021-2022 Jason Franklin +.\" 2022 Matt Barry +. +.\" This is free software; see the GNU General Public License version +.\" 2 or later for copying conditions. There is NO warranty. +.TH ADDUSER 8 "" "Debian GNU/Linux" +.SH NAME +adduser, addgroup \- add or manipulate users or groups +.SH SYNOPSIS +.SY adduser +.OP \-\-add\-authorized\-key key +.OP \-\-add\-extra\-groups +.OP \-\-allow\-all\-names +.OP \-\-allow\-bad\-names +.OP \-\-comment comment +.OP \-\-conf file +.OP \-\-debug +.OP \-\-disabled\-login +.OP \-\-disabled\-password +.OP \-\-encrypt\-home +.OP \-\-firstgid id +.OP \-\-firstuid id +.OP \-\-force-home +.OP \-\-gid id +.OP \-\-home dir +.OP \-\-ingroup group +.OP \-\-lastgid id +.OP \-\-lastuid id +.OP \-\-no\-create\-home +.OP \-\-no\-copy\-skel +.OP \-\-shell shell +.OP \-\-quiet +.OP \-\-uid id +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B user +.YS +.SY adduser +.B \-\-system +.OP \-\-comment comment +.OP \-\-conf file +.OP \-\-debug +.OP \-\-gid id +.OP \-\-group +.OP \-\-home dir +.OP \-\-ingroup group +.OP \-\-no\-create\-home +.OP \-\-no\-copy\-skel +.OP \-\-shell shell +.OP \-\-uid id +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B user +.YS +.SY adduser +.B \-\-unlock +.OP \-\-system +.B user +.YS +.SY adduser +.B \-\-group +.OP \-\-conf file +.OP \-\-debug +.OP \-\-firstgid id +.OP \-\-gid ID +.OP \-\-lastgid id +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B group +.YS +.SY addgroup +.OP \-\-conf file +.OP \-\-debug +.OP \-\-firstgid id +.OP \-\-gid ID +.OP \-\-lastgid id +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B group +.YS +.SY addgroup +.B \-\-system +.OP \-\-gid id +.OP \-\-conf file +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B group +.YS +.SY adduser +.OP \-\-conf file +.OP \-\-debug +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B user +.B group +.YS +.SY adduser +.B \-\-help +.YS +.SY adduser +.B \-\-version +.YS +.SH DESCRIPTION +\fBadduser\fP and \fBaddgroup\fP add users and groups to the system +according to command line options +and configuration information in \fI/etc/adduser.conf\fP. +They are more Debian specific front ends to the +\fBuseradd\fP, \fBgroupadd\fP and \fBusermod\fP programs, +which are more distribution agnostic. +\fBadduser\fP and \fBaddgroup\fP +by default choose Debian policy conformant UID and GID values, +create a home directory with skeletal configuration, +run a custom script, +and have other features. +.PP +\fBadduser\fP and \fBaddgroup\fP are intended as a policy layer, +making it easier for package maintainers and local administrators +to create local system accounts +in the way Debian expects them to be created, +taking the burden to adapt to the probably changing specifications +of Debian policy. +\fBadduser \-\-system\fP takes special attention +on just needing a single call in the package maintainer scripts +without any conditional wrappers, +error suppression or other scaffolding. +.PP +\fBadduser\fP honors the distinction between +\fIdynamically allocated system users and groups\fP +and +\fIdynamically allocated user accounts\fP +that is documented in Debian Policy, Chapter 9.2.2. +.PP +For a full list and explanations of all options, +see the OPTIONS section. +.PP +\fBadduser\fP and \fBaddgroup\fP can be run in one of five modes: +.SS "Add a regular (non-system) user" +If called with one non-option argument and +without the \fB\-\-system\fP or \fB\-\-group\fP options, +\fBadduser\fP will add a regular user, +that means a +\fIdynamically allocated user account\fP +in the sense of Debian Policy. +This is commonly referred to in \fBadduser\fP as a \fInon-system user.\fP +.PP +If \fBadduser\fP is called with the \fB\-\-unlock\fP option, it will +search for an existing account, and ensure it is unlocked. +If the user is not found, \fBadduser\fP will return an error. +See \fBUnlock an account\fP below for more details. +.PP +\fBadduser\fP will choose the first available UID +from the range specified by +\fBFIRST_UID\fP and \fBLAST_UID\fP +in the configuration file. +The range may be overridden with the +\fB\-\-firstuid\fP and \fB\-\-lastuid\fP options. +Finally, the UID can be set fully manually with the \fB\-\-uid\fP option. +.PP +By default, each user is given a corresponding group with the same name +and the same numeric ID as the user, +unless \fB\-\-ingroup\fP is used (see below). +This is commonly called +\fIUsergroups\fP +and allows group writable directories to be easily maintained +by placing the appropriate users in the new group, +setting the set-group-ID bit in the directory, +and ensuring that all users use a umask of 002. +.PP +For this usergroup case, +\fBadduser\fP does not pick a UID and a GID independently. +Instead, it searches for the first number that is simultaneously +available as a UID and as a GID, +and assigns that single number to both the new user and the new group. +The range searched is the +.I intersection +of the UID range +(\fBFIRST_UID\fP to \fBLAST_UID\fP, +or \fB\-\-firstuid\fP / \fB\-\-lastuid\fP if given) +and the GID range +(\fBFIRST_GID\fP to \fBLAST_GID\fP, +or \fB\-\-firstgid\fP / \fB\-\-lastgid\fP if given): +that is, the search starts at the higher of the two range minimums +and ends at the lower of the two range maximums. +If the configured UID and GID ranges do not overlap at all, +or no number free in both ranges can be found, +\fBadduser\fP fails outright; +it does not fall back to assigning the user and group different numbers. +.PP +If \fB\-\-ingroup\fP is given +to add the new user to an already existing group +instead of a new usergroup, +this combined search does not apply. +Instead, +if the requested group's GID happens to also be free as a UID +within the configured UID range, +\fBadduser\fP prefers that number for the new user's UID, +so the user still ends up with a UID matching the group's GID +even though the group was not newly created as a usergroup. +If the GID is not free as a UID, +or falls outside the UID range, +\fBadduser\fP falls back to choosing +the first available UID from the UID range, +as it always did. +.PP +Finally, the UID and/or GID can each be set fully manually +with the \fB\-\-uid\fP and \fB\-\-gid\fP options, +which bypass the search(es) above for the value(s) given. +.PP +The interaction between +\fBUSERS_GID\fP, \fBUSERS_GROUP\fP, and \fBUSERGROUPS\fP +is explained in detail in +.BR adduser.conf (5). +.PP +The new user's primary group can also be overridden +from the command line +with the \fB\-\-gid\fP or \fB\-\-ingroup\fP options +to set the group by id or name, +respectively. +Also, +users can be added +to one or more supplemental groups +defined as \fBEXTRA_GROUPS\fP +either by setting \fBADD_EXTRA_GROUPS\fP to 1 +in the configuration file, +or by passing \fB\-\-add\-extra\-groups\fP on the command line. +.PP +\fBadduser\fP will copy files from \fI/etc/skel\fP +into the home directory and +prompt for the comment field and a password +if those functions have not been turned off / overridden +from the command line. +.PP +UID, comment, home directory and shell +might be pre-determined with the \fBUID_POOL\fP and \fBGID_POOL\fP option, +documented in +.BR adduser.conf (5). + +To set up an encrypted home directory for the new user, add the +.B \-\-encrypt\-home +option. +For more information, refer to the \-b option of +.BR ecryptfs-setup-private (1). + +.SS "Add a system user" +If called with one non-option argument and the \fB\-\-system\fP option, +\fBadduser\fP will add a +\fIdynamically allocated system user,\fP +often abbreviated as +\fIsystem user\fP +in the context of the \fBadduser\fP package. +.PP +If the user already exists and is a system account, then +\fBadduser\fP will ensure the account is unlocked and return +successfully. +See \fBUnlock a user account\fP below. +.PP +\fBadduser\fP will choose the first available UID +from the range specified by +\fBFIRST_SYSTEM_UID\fP and \fBLAST_SYSTEM_UID\fP +in the configuration file. +This can be overridden with the \fB\-\-uid\fP option. +.PP +By default, system users are assigned \fBnogroup\fP as primary group. +To assign an already existing group as primary group, +use the \fB\-\-gid\fP or \fB\-\-ingroup\fP options. +.PP +If the \fB\-\-group\fP option is given +and the identically named group does not already exist, +it is created with the same numeric ID as the user, +following the same logic as for a non-system usergroup +(see \fBAdd a regular (non-system) user\fP above): +\fBadduser\fP searches for the first number that is simultaneously +available as a UID and as a GID, +within the intersection of the UID range +(\fBFIRST_SYSTEM_UID\fP to \fBLAST_SYSTEM_UID\fP, +or \fB\-\-firstuid\fP / \fB\-\-lastuid\fP if given) +and the GID range +(\fBFIRST_SYSTEM_GID\fP to \fBLAST_SYSTEM_GID\fP, +or \fB\-\-firstgid\fP / \fB\-\-lastgid\fP if given). +As with a regular usergroup, +if the configured UID and GID ranges do not overlap at all, +or no number free in both ranges can be found, +\fBadduser\fP fails outright +rather than assigning the user and group different numbers. +.PP +If instead \fB\-\-gid\fP or \fB\-\-ingroup\fP is used +to assign an already existing group as primary group, +this combined search does not apply. +Instead, +if that group's GID happens to also be free as a UID +within the configured UID range, +\fBadduser\fP prefers that number for the new system user's UID. +Note that for a non-system user (see above), +only \fB\-\-ingroup\fP triggers this preference; +\fB\-\-gid\fP alone does not. +If the GID is not free as a UID, +or falls outside the UID range, +\fBadduser\fP falls back to choosing +the first available UID from the UID range, +as it always did. +.PP +If no home directory is specified, +the default home directory for a new system user +is \fI\%/nonexistent\fP. +This directory should never exist on any Debian system, +and \fBadduser\fP will never create it automatically. +.PP +If a home directory is specified with the \fB\-\-home\fP option, +and the directory does already exist +(for example, if the package ships with files in that directory), +\fBadduser\fP silently does not set the owner of the directory +to the newly created user. +Setting the owner might override a decision of the local admin, +and reporting the fact would break \fBadduser\fP's silence +during package installation. +If you use \fBadduser \-\-home\fP in your package's maintainer scripts, +you might want to issue an explicit recursive \fBchown\fP for the +home directory after the call to \fBadduser\fP. +.PP +Unless a shell is explicitly set with the \fB\-\-shell\fP option, +the new system user will have the shell set to +\fI/usr/sbin/nologin\fP. +\fBadduser \-\-system\fP does not set a password for the new account. +It is an error if \fBadduser \-\-system\fP is called +for an account that has a password. +Skeletal configuration files are not copied. +.PP +Other options will behave as for the creation of a regular user. +The files referenced by \fBUID_POOL\fP and \fBGID_POOL\fP are also honored. + +.SS "Unlock a user account" +If called with the \fB\-\-unlock\fP option, \fBadduser\fP will +unlock an existing, previously locked account. +If found, the user's password will be re-enabled, +and expiry restrictions will be removed. +Any previous expiry settings will have to be +added manually after unlocking the account. + +.SS "Add a group" +If \fBadduser\fP is called with the \fB\-\-group\fP option and +without the \fB\-\-system\fP option, or +\fBaddgroup\fP is called respectively, +a user group will be added. +.PP +A +\fIdynamically allocated system group,\fP +often abbreviated as \fIsystem group\fP +in the context of the \fBadduser\fP package, +will be created +if \fBadduser \-\-group\fP or \fBaddgroup\fP +are called with the \fB\-\-system\fP option. +.PP +A GID will be chosen from the respective range specified for GIDs +in the configuration file +(\fBFIRST_GID\fP, \fBLAST_GID\fP, +\fBFIRST_SYSTEM_GID\fP, \fBLAST_SYSTEM_GID\fP). +To override that mechanism, +you can give the GID using the \fB\-\-gid\fP option. +.PP +For non-system groups, +the range specified in the configuration file may be overridden +with the \fB\-\-firstgid\fP and \fB\-\-lastgid\fP options. +.PP +The group is created with no members. + +.SS "Add an existing user to an existing group" +If called with two non-option arguments, +\fBadduser\fP will add an existing user to an existing group. + +.SH OPTIONS +Different modes of \fBadduser\fP allow different options. +If no valid modes are listed for a option, +it is accepted in all modes. +.PP +Short versions for certain options may exist for historical reasons. +They are going to stay supported, but are removed from the documentation. +Users are advised to migrate to the long version of options. +.TP +.B \-\-add\-authorized\-key key +Add +.I key +to the \fI\%~/.ssh/authorized_keys\fP file of the new user. +If +.I key +is the name of an existing file, +the contents of that file are added, +which allows to add several keys at once. +Otherwise, +.I key +is taken literally as a single key. +The option can be given more than once. +Keys are appended to \fI\%authorized_keys\fP, +so that keys shipped in \fI\%/etc/skel\fP are kept. +Keys are not checked for validity; +an unusable key is going to be rejected by the SSH daemon later. +No key is installed if the home directory has not been created by +\fB\%adduser\fP, +for example if \fB\-\-no\-create\-home\fP has been given, +if the home directory is \fI\%/nonexistent\fP, +or if the home directory does already exist. +In that case, +a warning is issued and the user is still created. +Note that \fB\%sshd\fP with \fBStrictModes\fP enabled ignores +\fI\%authorized_keys\fP if the home directory or \fI\%~/.ssh\fP +is writable by group or other, +which can happen with a permissive \fBDIR_MODE\fP setting. +Valid modes: \fBadduser\fP. +.TP +.B \-\-add\-extra\-groups +Add new user to extra groups defined in the configuration files' +\fBEXTRA_GROUPS\fP setting. +The old spelling \fB\-\-add_extra_groups\fP is deprecated and +will be supported in Debian bookworm only. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.B \-\-allow\-all\-names +Allow any user- and groupname which is supported by the underlying +\fBuseradd\fP(8). +See VALID NAMES below. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP, +\fBaddgroup\fP, \fBaddgroup \-\-system\fP. +.TP +.B \-\-allow\-bad\-names +Disable \fBNAME_REGEX\fP and \fBSYS_NAME_REGEX\fP check of names. +Only a weaker check for validity of the name is applied. +See VALID NAMES below. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP, +\fBaddgroup\fP, \fBaddgroup \-\-system\fP. +.TP +.BI \-\-comment " comment" +Set the comment field for the new entry generated. +\fBadduser\fP will not ask for the information if this option is given. +This field is also known under the name GECOS field +and contains information that is used by the \fBfinger\fR(1) command. +This used to be the \fB\-\-gecos\fR option, +which is deprecated and will be removed after Debian bookworm. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.BI \-\-conf " file" +Use \fIfile\fP instead of \fI/etc/adduser.conf\fP. +Multiple \fB\-\-conf\fR options can be given. +.TP +.B \-\-debug +Synonymous to +.BR \-\-stdoutmsglevel=debug . +Deprecated. +.TP +.B \-\-disabled\-login +.TQ +.B \-\-disabled\-password +Do not run \fBpasswd\fP(1) to set a password. +In most situations, logins are still possible though +(for example using SSH keys or through PAM) +for reasons that are beyond \fBadduser\fP's scope. +\fB\-\-disabled\-login\fP will additionally set the shell to +\fI/usr/sbin/nologin\fP. +Valid mode: \fBadduser\fP. +.TP +.BI \-\-firstuid " ID" +.TQ +.BI \-\-lastuid " ID" +.TQ +.BI \-\-firstgid " ID" +.TQ +.BI \-\-lastgid " ID" +Override the first UID / last UID / first GID / last GID +in the range that the uid is chosen from +(\fBFIRST_UID\fP, \fBLAST_UID\fP, \fBFIRST_GID\fP and \fBLAST_GID\fP, +\fBFIRST_SYSTEM_UID\fP, \fBLAST_SYSTEM_UID\fP, +\fBFIRST_SYSTEM_GID\fP and \fBLAST_SYSTEM_GID\fP +in the configuration file). +If a group is created as a usergroup +(that is, for \fBadduser\fP without \fB\-\-ingroup\fP, +or for \fBadduser \-\-system \-\-group\fP without \fB\-\-ingroup\fP), +\fB\-\-firstgid\fP and \fB\-\-lastgid\fP are +.B not +ignored: +they bound the GID side of the combined UID/GID search +described under +\fBAdd a regular (non-system) user\fP +above, +so a narrower or shifted \fB\-\-firstgid\fP\^/\fB\-\-lastgid\fP\^ +range can change which number is chosen, +or cause the search to fail +if it no longer overlaps the UID range at all. +The resulting group always gets the same numeric ID as the user. +If \fB\-\-ingroup\fP is used instead, +\fB\-\-firstgid\fP and \fB\-\-lastgid\fP have no effect; +\fB\-\-firstuid\fP and \fB\-\-lastuid\fP still bound +whether the requested group's GID +can be preferred as the new user's UID +(see \fBAdd a regular (non-system) user\fP above). +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP, +for \fP\-\-firstgid\fP and \fB\-\-lastgid\fR also +\fBaddgroup\fP. +.TP +.B \-\-force\-badname +.TQ +.B \-\-allow\-badname +These are the deprecated forms of \fB\-\-allow\-bad\-names\fR. +They will be removed +during the release cycle of Debian 13. +.TP +.BI \-\-gid " GID" +When creating a group, +this option sets the group ID number of the new group to \fIGID\fP. +When creating a user, +this option sets the primary group ID number of the new user +to \fIGID\fP. +For \fBadduser \-\-system\fP specifically, +if the chosen UID is not also given explicitly with \fB\-\-uid\fP, +and \fIGID\fP happens to also be free as a UID +within the UID range in effect, +\fBadduser\fP prefers that number for the new user's UID +(see \fB\-\-ingroup\fP). +This does not apply to a non-system \fBadduser\fP: +there, \fB\-\-gid\fP alone never influences UID selection this way. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP, +\fBaddgroup\fP, \fBaddgroup \-\-system\fP. +.TP +.B \-\-group +Using this option in \fBadduser \-\-system\fP +indicates that the new user should get +an identically named group as its primary group. +If that identically named group is not already present, it is created. +If not combined with \fB\-\-system\fP, +a group with the given name is created. +The latter is the default action if +the program is invoked as \fBaddgroup\fP. +Valid modes: \fBadduser \-\-system\fP, +\fBaddgroup\fP, \fBaddgroup \-\-system\fP. +.TP +.B \-\-help +Display brief instructions. +.TP +.BI \-\-home " dir" +Use \fIdir\fP as the user's home directory, +rather than the default specified by the configuration file +(or \fI/nonexistent\fP if \fBadduser \-\-system\fP is used). +If the directory does not exist, it is created. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.BI \-\-ingroup " GROUP" +When creating a user, +this option sets the primary group ID number of the new user +to the GID of the named group. +Unlike with the \fB\-\-gid\fP option, +the group is specified here by name rather than by numeric ID number. +The group must already exist. +If the chosen UID is not also given explicitly with \fB\-\-uid\fP, +and \fIGROUP\fP's GID happens to also be free as a UID +within the UID range in effect +(see \fB\-\-firstuid\fP / \fB\-\-lastuid\fP), +\fBadduser\fP prefers that number for the new user's UID, +so the user ends up with a UID matching the group's GID +even though the group itself was not newly created. +Otherwise, the first available UID in range is used, as before. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.BI \-\-lastuid " ID" +.TQ +.BI \-\-lastgid " ID" +Override the last UID / last GID. +See \fB\-\-firstuid\fP. +.TP +.B \-\-no\-create\-home +Do not create a home directory for the new user. +Note that the pathname for the new user's home directory +will still be entered in the appropriate field +in the \fI\%/etc/passwd\fP file. +The use of this option does not imply that this field should be empty. +Rather, it indicates to \fB\%adduser\fP +that some other mechanism will be responsible +for initializing the new user's home directory. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.B \-\-force\-home +Assume the home directory does already exist +and has been taken care of by the local administrator. +\fIchown\fP the directory to the newly created user and +populate it with the files from \fI\%/etc/skel\fP +without double checking. +This allows to put new home directories on an +md, lvm, or dm-crypt device. +Valid modes: \fBadduser\fP. +.TP +.B \-\-no\-copy\-skel +Do not populate the home directory for the new user with +files from \fI\%/etc/skel\fP. +If the home directory is newly created, it will be empty. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.B \-\-quiet +Synonymous to +.BR \-\-stdoutmsglevel=warn . +Deprecated. +.TP +.BI \-\-shell " shell" +Use \fIshell\fP as the user's login shell, +rather than the default specified by the configuration file +(or \fI/usr/sbin/nologin\fP if \fBadduser \-\-system\fP is used). +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.B \-\-system +Normally, \fBadduser\fP creates +\fIdynamically allocated user accounts and groups\fP +as defined in Debian Policy, Chapter 9.2.2. +With this option, \fBadduser\fP creates a +\fIdynamically allocated system user and group\fP +and changes its mode respectively. +Valid modes: \fBadduser\fP, \fBaddgroup\fP. +.TP +.BI \-\-uid " ID" +Force the new userid to be the given number. +\fBadduser\fP will fail if the userid is already taken. +Valid modes: \fBadduser\fP, \fBadduser \-\-system\fP. +.TP +.B \-\-verbose +Synonymous to +.BR \-\-stdoutmsglevel=info . +Deprecated. +.TP +.BI \-\-stdoutmsglevel " prio" +.TQ +.BI \-\-stderrmsglevel " prio" +.TQ +.BI \-\-logmsglevel " prio" +Minimum priority for messages logged to syslog/journal and the console, +respectively. +Values are +\fItrace\fP, \fIdebug\fP, \fIinfo\fP, \fIwarn\fP, \fIerr\fP, and \fIfatal\fP. +Messages with the priority set here or higher get printed to the +respective medium. +Messages printed to stderr are not repeated on stdout. +That allows the local admin to control \fBadduser\fP's chattiness +on the console and in the log independently, keeping probably confusing +information to itself while still leaving helpful information in the log. +stdoutmsglevel, stderrmsglevel, and logmsglevel default to warn, warn, info, +respectively. +.TP +.BR \-v " , " \-\-version +Display version and copyright information. + +.SH VALID NAMES +Historically, +\fBadduser\fP(8) and \fBaddgroup\fP(8) enforced +conformity to IEEE Std 1003.1-2001, +which allows only the following characters to appear +in group- and usernames: +letters, digits, underscores, periods, at signs (@) and dashes. +The name may not start with a dash or @. +The "$" sign is allowed at the end of usernames +to allow typical Samba machine accounts. +.PP +The default settings for \fBNAME_REGEX\fP and \fBSYS_NAME_REGEX\fP +allow usernames to contain letters and digits, +plus dash (\-) and underscore (_); +the name must begin with a letter +(or an underscore for system users). +.PP +The least restrictive policy, +available by using the \fB\-\-allow-all-names\fP option, +simply makes the same checks as \fBuseradd\fP(8). +Please note that useradd's checks have become quite a bit more restrictive +in Debian 13. +.PP +Changing the default behavior can be used to create +confusing or misleading names; use with caution. + +.SH LOGGING + +.B Adduser +uses extensive and configurable logging to tailor its verbosity to +the needs of the system administrator. + +Every message that \fBadduser\fR prints has a priority value +assigned by the authors. +This priority can not be changed at run time. +Available priority values are +\fBfatal\fR, +\fBerror\fR, +\fBwarn\fR, +\fBinfo\fR, +\fBdebug\fR, +and +\fBtrace\fR. + +If you find that a message has the wrong priority, +please file a bug. + +Every time a message is generated, +the code decides whether to print the message to +standard output, +standard error, +or +syslog. +This is mainly and independently controlled by the configuration settings +\fBSTDOUTMSGLEVEL\fR, +\fBSTDERRMSGLEVEL\fR, +and +\fBLOGMSGLEVEL\fR. +For testing purposes, +these settings can be overridden on the command line. + +Only messages with a priority higher or equal to the respective +message level are logged to the respective output medium. +A message that was written to standard error is not written +a second time to standard output. + +.SH EXIT VALUES + +.TP +.B 0 +Success: The user or group exists as specified. +This can have 2 causes: +The user or group was created by this call to \fBadduser\fP +or the user or group was already present on the system +as specified before \fBadduser\fP was invoked. +If \fBadduser \-\-system\fP is invoked for a user +already existing with the requested or compatible attributes, +it will also return 0. +.TP +.B 11 +The object that \fBadduser\fP was asked to create does already exist. +.TP +.B 12 +The object that \fBadduser\fP or \fBdeluser\fP was asked to operate on +does not exist. +.TP +.B 13 +The object that \fBadduser\fP or \fBdeluser\fP was asked to operate on +does not have the properties +that are required to complete the operation: +A user (a group) that was requested to be created +as a system user (group) +does already exist and +is not a system user (group), +or +a user (group) that was requested to be created +with a certain UID (GID) +does already exist and +has a different UID (GID), +or +a system user (group) that was requested to be deleted +does exist, but is not a system user (group). +.TP +.B 21 +The UID (GID) that was explicitly requested for a new user (group) +is already in use. +.TP +.B 22 +There is no available UID (GID) in the requested range. +.TP +.B 23 +There is no group with the requested GID for the primary group +for a new user. +.TP +.B 31 +The chosen name or comment for a new user or a new group +does not conform to the selected naming rules. +.TP +.B 32 +The home directory of a new user must be an absolute path. +.TP +.B 33 +useradd returned exit code 19 "invalid user or group name". +That means the user or group name chosen does not fit useradd's restrictions +and adduser cannot create the user. +.TP +.B 41 +The group that was requested to be deleted is not empty. +.TP +.B 42 +The user that was requested to be removed from a group is +not a member in the first place. +.TP +.B 43 +It is not possible to remove a user from its primary group, +or +no primary group selected for a new user by any method. +.TP +.B 51 +Incorrect number or order of command line parameters detected. +.TP +.B 52 +Incompatible options set in configuration file. +.TP +.B 53 +Mutually incompatible command line options detected. +.TP +.B 54 +\fBadduser\fP and \fBdeluser\fP invoked as non-root and thus cannot work. +.TP +.B 55 +\fBdeluser\fP will refuse to delete the \fIroot\fP account. +.TP +.B 56 +A function was requested that needs more packages to be installed. +See Recommends: and Suggests: of the adduser package. +.TP +.B 61 +.B Adduser +was aborted for some reason and +tried to roll back the changes that were done during execution. +.TP +.B 62 +Internal +.B adduser +error. +This should not happen. +Please try to reproduce the issue and file a bug report. +.TP +.B 71 +Error creating and handling the lock. +.TP +.B 72 +Error accessing the configuration file(s). +.TP +.B 73 +Error accessing a pool file. +.TP +.B 74 +Error reading a pool file, syntax error in file. +.TP +.B 75 +Error accessing auxiliary files. +.TP +.B 81 +An executable that is needed by \fBadduser\fP or \fBdeluser\fP +cannot be found. +Check your installation and dependencies. +.TP +.B 82 +Executing an external command returned some unexpected error. +.TP +.B 83 +An external command was terminated with a signal. +.TP +.B 84 +A syscall terminated with unexpected error. +.PP +Or for many other yet undocumented reasons which +are printed to console then. +You may then consider to increase a log level +to make \fBadduser\fP more verbose. + +.SH SECURITY +\fBadduser\fP needs root privileges and offers, +via the \fB\-\-conf\fP command line option +to use different configuration files. +Do not use \fBsudo\fP(8) or similar tools to +give partial privileges to \fBadduser\fP +with restricted command line parameters. +This is easy to circumvent and might +allow users to create arbitrary accounts. +If you want this, +consider writing your own wrapper script +and giving privileges to execute that script. + +.SH FILES +.TP +.I /etc/adduser.conf +Default configuration file for \fBadduser\fP(8) and \fBaddgroup\fP(8) +.TP +.I /usr/local/sbin/adduser.local +Optional custom add-ons, see +.BR adduser.local (8) +. + +.SH NOTES +Unfortunately, the term +\fIsystem account\fP +suffers from double use in Debian. +It both means an account for the actual Debian system, +distinguishing itself from an \fIapplication account\fP +which might exist in the user database +of some application running on Debian. +A \fIsystem account\fP in this definition has the potential +to log in to the actual system, has a UID, +can be member in system groups, +can own files and processes. +Debian Policy, au contraire, in its Chapter 9.2.2, +makes a distinguishment of +\fIdynamically allocated system users and groups\fP and +\fIdynamically allocated user accounts\fP, +meaning in both cases special instances of \fIsystem accounts\fP. +Care must be taken to not confuse this terminology. +Since \fBadduser\fP and \fBdeluser\fP(8) never address +\fIapplication accounts\fP and +everything in this package concerns \fIsystem accounts\fP here, +the usage of the terms \fIuser account\fP and \fIsystem account\fP +is actually not ambiguous in the context of this package. +For clarity, this document uses the definition +\fIlocal system account or group\fP if the distinction to +\fIapplication accounts\fP or +accounts managed in a directory service is needed. +.PP +\fBadduser\fP used to have the vision to be the universal front end +to the various directory services for +creation and deletion of regular and system accounts in Debian +since the 1990ies. +This vision has been abandoned as of 2022. +The rationale behind this includes: +that in practice, +a small server system is not going to have +write access to an enterprise-wide directory service anyway, +that locally installed packages are hard to manage with +centrally controlled system accounts, +that enterprise directory services have +their own management processes anyway and +that the personpower of the \fBadduser\fP team +is unlikely to be ever strong enough to write and maintain support for +the plethora of directory services that need support. +.PP +\fBadduser\fP will constrict itself to being a policy layer +for the management of local system accounts, +using the tools from the \fBpasswd\fP package for the actual work. +.PP +Group membership changes do not affect processes that are already running. +When a user is added to a group, the new membership becomes effective only for +sessions started after the change. +This behavior is a common source of +confusion for administrators who expect the results of \fBadduser user +group\fP to apply immediately to existing sessions. + +To make the new group membership available immediately, the user must +start a new login session. +Alternatively, the +.BR newgrp (1) +command can be used to start a new shell with the updated group +membership. + +This behavior is a fundamental property of Unix-like operating systems +and cannot be altered by \fBadduser\fP. + +.SH BUGS +Inconsistent use of terminology around the term \fIsystem account\fP +in docs and code is a bug. +Please report this and allow us to improve our docs. +.PP +\fBadduser\fP takes special attention to be directly usable in +Debian maintainer scripts without conditional wrappers, +error suppression and other scaffolding. +The only thing that the package maintainer should need to code +is a check for the presence of the executable in the postrm script. +The \fBadduser\fP maintainers consider the need +for additional scaffolding a bug and +encourage their fellow Debian package maintainers +to file bugs against the \fBadduser\fP package in this case. + +.SH SEE ALSO +.BR adduser.conf (5), +.BR deluser (8), +.BR groupadd (8), +.BR useradd (8), +.BR usermod (8), +.B /usr/share/doc/base\-passwd/users\-and\-groups.html +on any Debian system, +Debian Policy 9.2.2, +RFC8264 "PRECIS Framework: Preparation, Enforcement, and Comparison of +Internationalized Strings in Application Protocols", +RFC8265 "PRECIS Representing Usernames and Passwords", +https://wiki.debian.org/UserAccounts. diff --git a/doc/deluser.8 b/doc/deluser.8 new file mode 100644 index 0000000..bf7cc47 --- /dev/null +++ b/doc/deluser.8 @@ -0,0 +1,328 @@ +.\" Copyright: 1994 Ian A. Murdock +.\" 1995 Ted Hajek +.\" 1997-1999 Guy Maor +.\" 2000-2003 Roland Bauerschmidt +.\" 2004-2025 Marc Haber +.\" 2006-2009 Jörg Hoh +.\" 2011 Justin B Rye +.\" 2016 Helge Kreutzmann +.\" 2021-2022 Jason Franklin +.\" +.\" This is free software; see the GNU General Public License version +.\" 2 or later for copying conditions. There is NO warranty. +.TH DELUSER 8 "" "Debian GNU/Linux" +.SH NAME +deluser, delgroup \- remove a user or group from the system +.SH SYNOPSIS +.SY deluser +.OP \-\-backup +.OP \-\-backup\-suffix str +.OP \-\-backup\-to dir +.OP \-\-conf file +.OP \-\-debug +.OP \-\-remove\-all\-files +.OP \-\-remove\-home +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.OP \-\-lock +.B user +.YS + +.SY deluser +.OP \-\-system +.OP \-\-backup +.OP \-\-backup\-suffix str +.OP \-\-backup\-to dir +.OP \-\-conf file +.OP \-\-debug +.OP \-\-remove\-all\-files +.OP \-\-remove\-home +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.OP \-\-lock +.OP \-\-force\-delete +.B user +.YS + +.SY deluser +.B \-\-group +.OP \-\-conf file +.OP \-\-debug +.OP \-\-only\-if\-empty +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B group +.YS + +.SY delgroup +.OP \-\-system +.OP \-\-conf file +.OP \-\-debug +.OP \-\-only\-if\-empty +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B group +.YS + +.SY deluser +.OP \-\-conf file +.OP \-\-debug +.OP \-\-quiet +.OP \-\-verbose +.OP \-\-stdoutmsglevel prio +.OP \-\-stderrmsglevel prio +.OP \-\-logmsglevel prio +.B user +.B group +.YS + +.SY deluser +.B \-\-help +.YS +.SY deluser +.B \-\-version +.YS +.SH DESCRIPTION +\fBdeluser\fP and \fBdelgroup\fP remove users and groups +from the system according to command line options +and configuration information in +\fI/etc/deluser.conf\fP and \fI/etc/adduser.conf\fP. +.PP +They are more Debian specific front ends to the +\fBuserdel\fP and \fBgroupdel\fP programs, +which are more distribution agnostic. +\fBdeluser\fP and \fBdelgroup\fP can remove the home directory as option +or even all files on the system owned by the user to be removed, +run a custom script, +and have other features. +.PP +For a full list and explanations of all options, +see the OPTIONS section. +.PP +\fBdeluser\fP and \fBdelgroup\fP can be run in one of three modes: + +.SS "Remove a user" +If called with one non-option argument and +without the \fB\-\-group\fP option, +\fBdeluser\fP will remove a non-system user. +.PP +Note: If \fBdeluser\fP is called with the \fB\-\-lock\fP option, +the user account will be locked rather than removed as described +here; see \fB\-\-lock\fP, below. +.PP +By default, +\fBdeluser\fP will remove the user +without removing the home directory, +the mail spool or +any other files on the system owned by the user. +Removing the home directory and mail spool +can be achieved using the \fB\-\-remove\-home\fP option. +.PP +The \fB\-\-remove\-all\-files\fP option +removes all files on the system owned by the user. +Note that if you activate both options +\fB\-\-remove\-home\fP will have no additional effect +because all files including +the home directory and mail spool +are already covered by the \fB\-\-remove\-all\-files\fP option. +.PP +If you want to backup all files before deleting them +you can activate the \fB\-\-backup\fP option +which will create a file \fIusername.tar(.gz|.bz2)\fP +in the directory specified by the \fB\-\-backup\-to\fP option. +.PP +By default, +the backup archive is compressed with \fBgzip\fP(1). +To change this, +the \fB\-\-backup\-suffix\fP option can be set +to any suffix supported by \fBtar \-\-auto\-compress\fP. +.PP +\fBdeluser\fP will refuse to remove the root account. +.PP +If the \fB\-\-system\fP option is given on the command line, the +delete operation is actually executed only if the user is a system user. +This avoids accidentally deleting non-system users. +Additionally, +if the user does not exist, +no error value is returned. +Debian package maintainer scripts +may use this flag +to remove system users or groups +while ignoring the case where the removal already occurred. + +.SS "Remove a group" +If \fBdeluser\fP is called with the \fB\-\-group\fP option, +or \fBdelgroup\fP is called, +a group will be removed. +The primary group of an existing user cannot be removed. +If the option \fB\-\-only\-if\-empty\fP is given, +the group won't be removed if it has any members left. +.PP +The \fB\-\-system\fP option adds the same functionality as for users, +respectively. + +.SS "Remove a user from a specific group" +If called with two non-option arguments, +\fBdeluser\fP will remove a user from a specific group. + +.SH OPTIONS +Different modes of \fBdeluser\fP allow different options. +If no valid modes are listed for a option, +it is accepted in all modes. +.PP +Short versions for certain options may exist for historical reasons. +They are going to stay supported, but are removed from the documentation. +Users are advised to migrate to the long version of options. +.TP +.B \-\-backup +Backup all files contained in the userhome and the mailspool file +to a file named \fIusername.tar.bz2\fP or \fIusername.tar.gz\fP. +Valid modes: \fBdeluser\fP, \fBdeluser \-\-system\fP. +.TP +.BR "\-\-backup\-suffix "str +Select compression algorithm for a home directory backup. +Can be set to any suffix recognized by \fBtar \-\-auto\-compress\fP. +Defaults to \fI.gz\fP. +Valid modes: \fBdeluser\fP, \fBdeluser \-\-system\fP. +.TP +.BI "\-\-backup\-to "dir +Place the backup files not in the current directory but in \fIdir\fP. +This implicitly sets \fB\-\-backup\fP also. +Defaults to the current working directory. +Valid modes: \fBdeluser\fP, \fBdeluser \-\-system\fP. +.TP +.BI \-\-conf " file" +Use \fIfile\fP instead of the default files +\fI/etc/deluser.conf\fP and \fI/etc/adduser.conf\fP. +Multiple \-\-conf options may be given. +.TP +.B \-\-debug +Synonymous to +.BR \-\-stdoutmsglevel=debug . +Deprecated. +.TP +.B \-\-group +Remove a group. +This is the default action if the program is +invoked as \fIdelgroup\fP. +Valid mode: \fBdeluser\fP. +.TP +.B \-\-help +Display brief instructions. +.TP +.B \-\-only\-if\-empty +Only remove if no members are left. +Valid modes: \fBdeluser \-\-group\fP, \fBdelgroup\fP. +.TP +.B \-\-quiet +Synonymous to +.BR \-\-stdoutmsglevel=warn . +Deprecated. +.TP +.B \-\-remove\-all\-files +Remove all files from the system owned by this user. +Note: \-\-remove\-home does not have an effect any more. +If \fB\-\-backup\fP is specified, +the files are deleted after having performed the backup. +Valid modes: \fBdeluser\fP, \fBdeluser \-\-system\fP. +.TP +.B \-\-remove\-home +Remove the home directory of the user and its mailspool. +If \fB\-\-backup\fP is specified, +the files are deleted after having performed the backup. +Valid modes: \fBdeluser\fP, \fBdeluser \-\-system\fP. +.TP +.B \-\-system +Only delete if user/group is a system user/group. +If the user does not exist, no error value is returned. +Valid modes: \fBdeluser\fP, \fBdeluser \-\-system\fP. +.TP +.B \-\-verbose +Synonymous to +.BR \-\-stdoutmsglevel=info . +Deprecated. +.TP +.BI \-\-stdoutmsglevel " prio" +.TQ +.BI \-\-stderrmsglevel " prio" +.TQ +.BI \-\-logmsglevel " prio" +Minimum priority for messages logged to syslog/journal and the console, +respectively. +Values are +\fItrace\fP, \fIdebug\fP, \fIinfo\fP, \fIwarn\fP, \fIerr\fP, and \fIfatal\fP. +Messages with the priority set here or higher get printed to the +respective medium. +Messages printed to stderr are not repeated on stdout. +That allows the local admin to control \fBadduser\fP's chattiness +on the console and in the log independently, keeping probably confusing +information to itself while still leaving helpful information in the log. +.TP +.B \-\-lock +If \fBdeluser\fP is called with the \fB\-\-lock\fP option, +the user account will be locked rather than removed. In this +case, the user's password is invalidated and the account is +set to expired; no other action is taken. A locked account may be +subsequently unlocked using \fBadduser\fP \fB\-\-unlock\fP. + +System users may be set to lock upon delete by default by setting +\fBSYS_DELETE_ACTION\fP=\fBlock\fP in \fB/etc/deluser.conf\fP. +.B \-\-force\-delete +If deleting a system user, and the default \fBSYS_DELETE_ACTION\fP +would lock the account, instead delete it normally. +.TP +.B \-\-version +Display version and copyright information. + +.SH LOGGING + +\fBdeluser\fR uses extensive and configurable logging to tailor its verbosity +to the needs and wishes of the system administrator. + +This works similar to \fBadduser\fR. +See \fBadduser\fR(8) for all the details. + +.SH EXIT VALUES + +The exit values documented in adduser(8) also apply for \fBdeluser\fP. + +.SH SECURITY +\fBdeluser\fP needs root privileges and offers, +via the \fB\-\-conf\fP command line option +to use different configuration files. +Do not use \fBsudo\fP(8) or similar tools to +give partial privileges to \fBdeluser\fP +with restricted command line parameters. +This is easy to circumvent and might +allow users to obtain privileges they are not supposed to have. +If you want this, +consider writing your own wrapper script +and giving privileges to execute that script. + +.SH FILES +.I /etc/deluser.conf +Default configuration file for \fBdeluser\fP(8) and \fBdelgroup\fP(8) +.TP +.I /usr/local/sbin/deluser.local +Optional custom add-ons, see +.BR deluser.local (8) +. + +.SH "SEE ALSO" +.BR adduser (8), +.BR deluser.conf (5), +.BR deluser.local.conf (8), +.BR groupdel (8), +.BR userdel (8)