<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-user-management">
  <title>User Management</title>
  <para>
    NixOS supports both declarative and imperative styles of user
    management. In the declarative style, users are specified in
    <literal>configuration.nix</literal>. For instance, the following
    states that a user account named <literal>alice</literal> shall
    exist:
  </para>
  <programlisting language="bash">
users.users.alice = {
  isNormalUser = true;
  home = &quot;/home/alice&quot;;
  description = &quot;Alice Foobar&quot;;
  extraGroups = [ &quot;wheel&quot; &quot;networkmanager&quot; ];
  openssh.authorizedKeys.keys = [ &quot;ssh-dss AAAAB3Nza... alice@foobar&quot; ];
};
</programlisting>
  <para>
    Note that <literal>alice</literal> is a member of the
    <literal>wheel</literal> and <literal>networkmanager</literal>
    groups, which allows her to use <literal>sudo</literal> to execute
    commands as <literal>root</literal> and to configure the network,
    respectively. Also note the SSH public key that allows remote logins
    with the corresponding private key. Users created in this way do not
    have a password by default, so they cannot log in via mechanisms
    that require a password. However, you can use the
    <literal>passwd</literal> program to set a password, which is
    retained across invocations of <literal>nixos-rebuild</literal>.
  </para>
  <para>
    If you set <xref linkend="opt-users.mutableUsers" /> to false, then
    the contents of <literal>/etc/passwd</literal> and
    <literal>/etc/group</literal> will be congruent to your NixOS
    configuration. For instance, if you remove a user from
    <xref linkend="opt-users.users" /> and run nixos-rebuild, the user
    account will cease to exist. Also, imperative commands for managing
    users and groups, such as useradd, are no longer available.
    Passwords may still be assigned by setting the user's
    <link linkend="opt-users.users._name_.hashedPassword">hashedPassword</link>
    option. A hashed password can be generated using
    <literal>mkpasswd</literal>.
  </para>
  <para>
    A user ID (uid) is assigned automatically. You can also specify a
    uid manually by adding
  </para>
  <programlisting language="bash">
uid = 1000;
</programlisting>
  <para>
    to the user specification.
  </para>
  <para>
    Groups can be specified similarly. The following states that a group
    named <literal>students</literal> shall exist:
  </para>
  <programlisting language="bash">
users.groups.students.gid = 1000;
</programlisting>
  <para>
    As with users, the group ID (gid) is optional and will be assigned
    automatically if it’s missing.
  </para>
  <para>
    In the imperative style, users and groups are managed by commands
    such as <literal>useradd</literal>, <literal>groupmod</literal> and
    so on. For instance, to create a user account named
    <literal>alice</literal>:
  </para>
  <programlisting>
# useradd -m alice
</programlisting>
  <para>
    To make all nix tools available to this new user use `su - USER`
    which opens a login shell (==shell that loads the profile) for given
    user. This will create the ~/.nix-defexpr symlink. So run:
  </para>
  <programlisting>
# su - alice -c &quot;true&quot;
</programlisting>
  <para>
    The flag <literal>-m</literal> causes the creation of a home
    directory for the new user, which is generally what you want. The
    user does not have an initial password and therefore cannot log in.
    A password can be set using the <literal>passwd</literal> utility:
  </para>
  <programlisting>
# passwd alice
Enter new UNIX password: ***
Retype new UNIX password: ***
</programlisting>
  <para>
    A user can be deleted using <literal>userdel</literal>:
  </para>
  <programlisting>
# userdel -r alice
</programlisting>
  <para>
    The flag <literal>-r</literal> deletes the user’s home directory.
    Accounts can be modified using <literal>usermod</literal>. Unix
    groups can be managed using <literal>groupadd</literal>,
    <literal>groupmod</literal> and <literal>groupdel</literal>.
  </para>
</chapter>
