pyrox.dev
1# User Management {#sec-user-management}
2
3NixOS supports both declarative and imperative styles of user
4management. In the declarative style, users are specified in
5`configuration.nix`. For instance, the following states that a user
6account named `alice` shall exist:
7
8```nix
9{
10 users.users.alice = {
11 isNormalUser = true;
12 home = "/home/alice";
13 description = "Alice Foobar";
14 extraGroups = [ "wheel" "networkmanager" ];
15 openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
16 };
17}
18```
19
20Note that `alice` is a member of the `wheel` and `networkmanager`
21groups, which allows her to use `sudo` to execute commands as `root` and
22to configure the network, respectively. Also note the SSH public key
23that allows remote logins with the corresponding private key. Users
24created in this way do not have a password by default, so they cannot
25log in via mechanisms that require a password. However, you can use the
26`passwd` program to set a password, which is retained across invocations
27of `nixos-rebuild`.
28
29If you set [](#opt-users.mutableUsers) to
30false, then the contents of `/etc/passwd` and `/etc/group` will be congruent
31to your NixOS configuration. For instance, if you remove a user from
32[](#opt-users.users) and run nixos-rebuild, the user
33account will cease to exist. Also, imperative commands for managing users and
34groups, such as useradd, are no longer available. Passwords may still be
35assigned by setting the user's
36[hashedPassword](#opt-users.users._name_.hashedPassword) option. A
37hashed password can be generated using `mkpasswd`.
38
39A user ID (uid) is assigned automatically. You can also specify a uid
40manually by adding
41
42```nix
43{
44 uid = 1000;
45}
46```
47
48to the user specification.
49
50Groups can be specified similarly. The following states that a group
51named `students` shall exist:
52
53```nix
54{
55 users.groups.students.gid = 1000;
56}
57```
58
59As with users, the group ID (gid) is optional and will be assigned
60automatically if it's missing.
61
62In the imperative style, users and groups are managed by commands such
63as `useradd`, `groupmod` and so on. For instance, to create a user
64account named `alice`:
65
66```ShellSession
67# useradd -m alice
68```
69
70To make all nix tools available to this new user use \`su - USER\` which
71opens a login shell (==shell that loads the profile) for given user.
72This will create the \~/.nix-defexpr symlink. So run:
73
74```ShellSession
75# su - alice -c "true"
76```
77
78The flag `-m` causes the creation of a home directory for the new user,
79which is generally what you want. The user does not have an initial
80password and therefore cannot log in. A password can be set using the
81`passwd` utility:
82
83```ShellSession
84# passwd alice
85Enter new UNIX password: ***
86Retype new UNIX password: ***
87```
88
89A user can be deleted using `userdel`:
90
91```ShellSession
92# userdel -r alice
93```
94
95The flag `-r` deletes the user's home directory. Accounts can be
96modified using `usermod`. Unix groups can be managed using `groupadd`,
97`groupmod` and `groupdel`.
98
99## Create users and groups with `systemd-sysusers` {#sec-systemd-sysusers}
100
101::: {.note}
102This is experimental.
103
104Please consider using [Userborn](#sec-userborn) over systemd-sysusers as it's
105more feature complete.
106:::
107
108Instead of using a custom perl script to create users and groups, you can use
109systemd-sysusers:
110
111```nix
112{
113 systemd.sysusers.enable = true;
114}
115```
116
117The primary benefit of this is to remove a dependency on perl.
118
119## Manage users and groups with `userborn` {#sec-userborn}
120
121::: {.note}
122This is experimental.
123:::
124
125Like systemd-sysusers, Userborn doesn't depend on Perl but offers some more
126advantages over systemd-sysusers:
127
1281. It can create "normal" users (with a GID >= 1000).
1292. It can update some information about users. Most notably it can update their
130 passwords.
1313. It will warn when users use an insecure or unsupported password hashing
132 scheme.
133
134Userborn is the recommended way to manage users if you don't want to rely on
135the Perl script. It aims to eventually replace the Perl script by default.
136
137You can enable Userborn via:
138
139```nix
140services.userborn.enable = true;
141```
142
143You can configure Userborn to store the password files
144(`/etc/{group,passwd,shadow}`) outside of `/etc` and symlink them from this
145location to `/etc`:
146
147```nix
148services.userborn.passwordFilesLocation = "/persistent/etc";
149```
150
151This is useful when you store `/etc` on a `tmpfs` or if `/etc` is immutable
152(e.g. when using `system.etc.overlay.mutable = false;`). In the latter case the
153original files are by default stored in `/var/lib/nixos`.
154
155Userborn implements immutable users by re-mounting the password files
156read-only. This means that unlike when using the Perl script, trying to add a
157new user (e.g. via `useradd`) will fail right away.