adduser in Debian
=================

The adduser package includes the adduser and deluser commands for
creating and removing users and groups.

The code in this package is 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.

adduser --system is designed such that it can be called without the
caller needing to check that relevant preconditions have been met.

adduser --system take special attention on just needing a single call in
the package maintainer scripts without any conditional wrappers, error
suppression or scaffolding.

adduser honors the distinction between dynamically allocated system
users and groups and dynamically allocated user accounts that is
documented in Debian Policy, Chapter 9.2.2.


Documentation
-------------
This document contains background information that you might find
helpful to understand some of the design decisions that the adduser
maintainers took to bring adduser to where it is at the moment. For
operational reference, you might want to look at the manual pages that
come with the package (see apropos adduser, apropos deluser).

Information that is in the manual pages is probably not going to be
repeated in this README file.


Usage in maintainer scripts
---------------------------
The reference to create users and groups related to packages is
Debian Policy, Chapter 9.2.2. adduser --system can help you to create a
user in your postinst. 

The most important thing to know is that adduser --system is idempotent:
If the desired user already exists with the important properties
matching, adduser returns a zero exit code and leaves the existing user
untouched.

We might consider it a bug if your maintainer scripts need scaffolding
around an adduser/deluser --system call in your maintainer scripts other
than checking for the executable being present in postrm. Please file a
bug if your package needs an if or other bracket around your adduser
calls.

See adduser(8) for more documentation about how adduser --system behaves
regarding setting a password,  UID, group membership, shell, and home
directory. Consider whether it should be possible to run processes or
even log in as your user and configure it appropriately.

We are currently (summer 2022) re-working adduser's logging subsystem
with the ultimate goal of adduser becoming silent in the process of
creating a system user unless the log level is raised by configuration
or an error happens.

It might be advisable to not delete your users on purge of your package
since there might still be files belonging to the user. Instead, lock
your user, making it impossible to log in as the user, and unlock it in
postinst when your package gets reinstalled.

Sadly, currently (summer 2022, adduser 3.125) locking and unlocking
accounts is not well supported yet. We are planning to improve this in
time for the release of Debian bookworm.


Configuration files
-------------------
adduser and deluser have configuration files, /etc/adduser.conf and
/etc/deluser.conf, respectively. In a freshly installed package, both
files only contain comments, giving terse explanation about available
configuration options and stating what the default is that adduser and
deluser will use if not otherwise configured.

Both configuration files are dpkg-conffiles and have full conffile
support by dpkg on upgrades. Until Debian bullseye, /etc/adduser.conf
was managed by the maintainer scripts and debconf; this has been removed
in adduser 3.125 and the file was moved to being a dpkg-conffile.


Debconf
-------
Debconf support was removed in adduser 3.125. We used to just ask one
question during installation regarding DIR_MODE (system-wide readable
home directories or not).

With adduser growing, this has shown to pose issues since we did not
find an explanation to only give these limited choices in debconf. To
be consistent, we would have to add many more questions. This does not
seem to be a realistic endeavor given the available personpower.

Consequently, debconf support was removed complete, making
/etc/adduser.conf a regular dpkg-conffile.

We might be willing to reintroduce more elaborate debconf support in the
future if somebody volunteers to write the code, documentation and
tests, and to actually maintain it for the foreseeable future. Please
get in touch with the adduser team if you're willing to help.


Why not declarative?
--------------------
Adduser is intended to be used in maintainer scripts. While there are
approaches in Debian to move more and more functionality away from
maintainer scripts to a more declarative approach. The current form of
adduser is used in many hundred packages.

It is fine to use a more declarative approach to define system users in
Debian packages. There is nothing that forces package maintainers to use
adduser to create their package-related users. The packages dh-sysuser,
opensysusers, and systemd-sysusers already offer a declarative approach
to create package-related users.

For the time being, adduser's paradigm is not going to change for
compatibility's sake.


Directory services and adduser
------------------------------
We have been planning to convert adduser to a more modular approach,
allowing adduser to be used to create users in a directory service such
as NIS, NIS+ and LDAP, for more than two decades. It is not realistic to
expect this to happen any time soon.

For the time being, adduser is officially deprecating any existing
support to write to directory services. An arbitrary server in an
organization that uses a directory service is unlikely to have enough
privileges to write to a directory service anyway.

It might be possible, to add the desired support via an adduser.local
hook. If you need more hooks to locally implement what you need, let us
know and we will see what we can do for you. A more flexible hook system
might be implemented in the nearer future.

We might be willing to reintroduce support for directory services in the
future if somebody volunteers to write the code, documentation and
tests, and to actually maintain it for the foreseeable future. Please
get in touch with the adduser team if you're willing to help.


Default for DIR_MODE
--------------------
DIR_MODE and SYS_DIR_MODE specify the file mode bits for a home
directory created by adduser. This has been a controversial setting
throughout most of adduser's life since the 1990s.

Currently, DIR_MODE defaults to 0700, while SYS_DIR_MODE defaults to
0755. The separation between DIR_MODE and SYS_DIR_MODE happened in
adduser 3.122 because we got convinced that a normal user needs a
different setting than a system user. This allowed us to tighten the
file mode bits of a regular user's home directory to 0700 while keeping
the more permissive setting for system users.

Historically, the separation was also implemented to finally solve
#643559, which requested setting the setgid bit for the home directory of
a non-system user by default, in order to ease setting access
permissions of shared workspaces in multi-user systems.  This default
has oscillated back and forth in adduser multiple times since the
1990s, because both ways to set this bit by default have advantages
and disadvantages.  After a preliminary request for comment (see
https://lists.debian.org/debian-devel/2022/03/msg00098.html), the
default value for DIR_MODE was changed to 2700 in adduser 3.122 (July
2022).  Sadly, though the technical reasoning for NOT setting the bit
did largely not survive the last two decades, some use cases that we
were not fully aware of were adversely impacted by this change.

Promptly, #1014901 was filed, requesting that DIR_MODE be changed to
0700, effectively causing home directories of non-system users to be
created without the setgid bit. The biggest point in the reasoning is that
having the setgid bit set will need special measures to keep the home
directory's group ownership from propagating to file system images,
chroots, and archives, causing wrong file ownership/permissions in those
entities, which in turn might propagate to different systems and cause
security-related effects there.  The bug report gives instructions to
reproduce the behavior.

System administrators who run multi-user environments which require
shared workspaces have tools at their disposal to change the default
behavior as their individual needs require, and likely are aware of how
to work around any issues that arise as part of that configuration; it
is also very possible that such systems may be managed using
configuration management software. In an age of general purpose use on
one end, and single purpose containers on the other, this is unlikely to
be the majority of newly installed systems.

So what remains is the decision to provide a sane default for a system
that is installed by an end-user, who may not understand or be aware of
this setting at all, but who still might use Internet HOW-TOs to build
chroots, images or archives, inadvertently causing security issues on
third-party systems. The clear and unsurprising solution is to leave the
setgid bit for newly created users off by default. This is also important
to keep the support effort for other packages down. Users surprised by
the behavior might file bugs against other packages, increasing the
effort necessary to support those other packages.

So, in adduser 3.123, DIR_MODE reached its final default setting of
0700, flipping the default for the setgid bit one last time to the value
we had for the majority of Debian's existence period. With this change,
Debian is re-joining ranks again with ALL other major Linux
distributions, none of which setting the setgid bit on home directories to
1 (research done in July 2022).

This primarily affects the one user that can be created in the Installer
before there is any possibility to configure adduser. Those users will
now again have the setgid bit of the home directory set to 0. Again,
system administrators have the tools and documentation to configure
their systems as their individual requirements dictate (using the
DIR_MODE setting in adduser.conf, and/or fixing those initial
directories).

As mode 0700 provides both the most secure, unsurprising default, and is
in line with most other major distributions, the adduser team considers
the matter to be settled; any further discussion should come prepared
with rationale, support, convincing use cases and a significant public
discussion period.



Rewrite
-------
adduser needs a rewrite. The code base was started in the 1990s and
this fact can easily be seen. The introduction of our test suite has
made changes to adduser much easier, but the code is still 25 years old.

We support any effort for a rewrite, but we strongly believe that this
should be done in a dedicated project with a new name, such as
adduser-ng or adduser4. But such a project needs to be externally
driven.



Participating in development
----------------------------
adduser is developed on
[Salsa](https://salsa.debian.org/debian/adduser). Our main communication
channel is the [Debian Tracker Package Mail
Address](mailto:adduser@packages.debian.org). You can subscribe to the
messages through the [Debian Tracker Package
Page](https://tracker.debian.org/pkg/adduser). If you want to
participate, create an account on Salsa, clone the Debian/adduser
project and submit a Merge Request. Feel free to use Salsa CI to have
your work tested automatically when you push.

Adduser has a test suite. If you implement new features, please also
write appropriate test cases and test them. Don't forget to adapt the
documentation and the manual pages. If you fix a bug, please write a
test case first that fails because of the bug, put the test case in its
own commit, and then implement the fix. We want to see the test fail
when just the test commit is cherry picked.

Working with branches and merge requests means rebasing a lot. To make
this easier, please don't squash your work into one huge commit. 
Use small, independent commits that can easily be understood. It is OK
to rebase or force-push to your development branch even after opening
the merge request. We love merges that can be pulled into master as a
fast-forward merge.

adduser should be coded according to the style suggestions given in
perldoc perlstyle. Indentation should be in increments of four
characters per level, using spaces, not tabs.



Credits
-------
This document was compiled by the adduser maintainers. Ximon Eighteen
helped to polish the language of the first revisions in August 2022.
