.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "DH_SYSUSER 1"
.TH DH_SYSUSER 1 "2023-03-27" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
dh_sysuser \- manage system users required for package operation
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBdh_sysuser\fR [\fIdebhelper\ options\fR] [\fIusername\fR \fIoptions\fR] ...
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBdh_sysuser\fR is a debhelper addon providing a simple and uniform way
to create and remove system users required for package operation
(for example, to run a service with dropped privileges).
.PP
The user creation itself is delegated to \fBuseradd\fR\|(8) utility, the behavior
of which is controlled by \fI/etc/login.defs\fR configuration file. In
the default installation:
.IP "\(bu" 4
The primary group of the new user is created with the same name as the
user. The new users will not be a member of any other group except the
primary one.
.IP "\(bu" 4
New users have the \fI/etc/shadow\fR password field set to '!', making it
impossible to log in.
.IP "\(bu" 4
New users have the shell set to \fI/usr/sbin/nologin\fR. It is still possible
to get a new user's shell with \fIsu \-s\fR.
.IP "\(bu" 4
If the home directory is created (see below), its permissions are adjusted
according to the \fB\s-1UMASK\s0\fR variable in \fI/etc/login.defs\fR. By default, this
results in the mode 0755 for the home directory.
Files from \fI/etc/skel\fR are \fI\s-1NOT\s0\fR copied.
.Sp
\&\fB\s-1WARNING:\s0\fR The data stored in new user's home directory are world-readable.
If you (as package maintainer) need full control over home directory permissions,
please file a bug.
.PP
\&\fBdh_sysuser\fR reads its arguments from command line and the
\&\fIdebian/\fIpackage\fI.\fIsysuser\fI\fR file, if one exists, in pairs, the first
argument being a username and the second one is options. The configuration
file or command-line arguments must be used to create users: just calling
\&\fBdh_sysuser\fR without any arguments does not have any effect.
.PP
Here are the options that can be specified after the username:
.IP "\fBhome\fR" 4
.IX Item "home"
This option requests the creation of a home directory in
\&\fI/var/lib/\f(BIusername\fI\fR. You should use this form over the
explicit one described below for uniformity.
.IP "\fBhome\fR=\fI/path/to/home/directory\fR" 4
.IX Item "home=/path/to/home/directory"
This option requests the creation of a home directory at the specified path.
.IP "\fBdefaults\fR" 4
.IX Item "defaults"
If you do not need any other options, specify this one.
.SS "\s-1CRUFT OF SYSTEM USERS\s0"
.IX Subsection "CRUFT OF SYSTEM USERS"
Creating a system user (or a user in general) is easy, but safely removing one
is hard. There is no consensus on what should happen to its home directory or
files owned by the user elsewhere.
.PP
There was some discussion (#848239, #848240), but there is still no simple and
definitive answer to that. Therefore dh-sysuser does the following on package removal:
.IP "\(bu" 4
If the user has been created without a home directory, it is considered safe
to remove it.
.IP "\(bu" 4
If the user has been created with a home directory but at time of the package
removal it is empty, it is considered safe to remove both the user and
its empty home directory.
.IP "\(bu" 4
If the user has been created with a home directory but at time of the package
removal it is \fInot\fR empty, both the user and its home directory are left
alone.
.Sp
\&\fB\s-1NOTE:\s0\fR As a package maintainer, you are encouraged to delete files from home
directories known to be of little value. It increases chances that
home directory becomes empty and user is removed.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
In \fIdebian/\fIpackage\fI.\fIsysuser\fI\fR, this creates a user \fBfoo\fR with
defaults settings, with a home directory at the default location for \fBbar\fR,
and a home directory at a custom location for \fBbaz\fR:
.PP
.Vb 3
\&    foo defaults
\&    bar home
\&    baz home=/opt/baz
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBuseradd\fR\|(8)