DOKK / manpages / debian 12 / dh-sysuser / dh_sysuser.1.en
DH_SYSUSER(1) User Contributed Perl Documentation DH_SYSUSER(1)

dh_sysuser - manage system users required for package operation

dh_sysuser [debhelper options] [username options] ...

dh_sysuser 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).

The user creation itself is delegated to useradd(8) utility, the behavior of which is controlled by /etc/login.defs configuration file. In the default installation:

  • 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.
  • New users have the /etc/shadow password field set to '!', making it impossible to log in.
  • New users have the shell set to /usr/sbin/nologin. It is still possible to get a new user's shell with su -s.
  • If the home directory is created (see below), its permissions are adjusted according to the UMASK variable in /etc/login.defs. By default, this results in the mode 0755 for the home directory. Files from /etc/skel are NOT copied.

    WARNING: 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.

dh_sysuser reads its arguments from command line and the debian/package.sysuser 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 dh_sysuser without any arguments does not have any effect.

Here are the options that can be specified after the username:

This option requests the creation of a home directory in /var/lib/username. You should use this form over the explicit one described below for uniformity.
This option requests the creation of a home directory at the specified path.
If you do not need any other options, specify this one.

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.

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:

  • If the user has been created without a home directory, it is considered safe to remove it.
  • 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.
  • If the user has been created with a home directory but at time of the package removal it is not empty, both the user and its home directory are left alone.

    NOTE: 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.

In debian/package.sysuser, this creates a user foo with defaults settings, with a home directory at the default location for bar, and a home directory at a custom location for baz:

    foo defaults
    bar home
    baz home=/opt/baz

useradd(8)

2023-02-24 perl v5.36.0