From 884b4c6137d130d34ee527e6b18032e4f50945dd Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Mon, 19 Aug 2013 18:19:52 +0200
Subject: [PATCH] Manual: Document user management

---
 doc/manual/configuration.xml | 87 ++++++++++++++++++++++++++++++++++++
 doc/manual/running.xml       |  5 +++
 2 files changed, 92 insertions(+)

diff --git a/doc/manual/configuration.xml b/doc/manual/configuration.xml
index daee0248e88..6a217243c00 100644
--- a/doc/manual/configuration.xml
+++ b/doc/manual/configuration.xml
@@ -305,6 +305,93 @@ manpage or the Nix manual.</para>
 </section>
 
 
+<!--===============================================================-->
+
+<section><title>User management</title>
+
+<para>NixOS supports both declarative and imperative styles of user
+management.  In the declarative style, users are specified in
+<filename>configuration.nix</filename>.  For instance, the following
+states that a user accound named <literal>alice</literal> shall exist:
+
+<programlisting>
+users.extraUsers.alice =
+  { createHome = true;
+    home = "/home/alice";
+    description = "Alice Foobar";
+    extraGroups = [ "wheel" ];
+    isSystemUser = false;
+    useDefaultShell = true;
+    openssh.authorizedKeys.keys = [ "ssh-dss AAAAB3Nza... alice@foobar" ];
+  };
+</programlisting>
+
+Note that <literal>alice</literal> is a member of the
+<literal>wheel</literal> group, which allows her to use
+<command>sudo</command> to execute commands as
+<literal>root</literal>.  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
+<command>passwd</command> program to set a password, which is retained
+across invocations of <command>nixos-rebuild</command>.</para>
+
+<para>A user ID (uid) is assigned automatically.  You can also specify
+a uid manually by adding
+
+<programlisting>
+    uid = 1000;
+</programlisting>
+
+to the user specification.</para>
+
+<para>Groups can be specified similarly.  The following states that a
+group named <literal>students</literal> shall exist:
+
+<programlisting>
+users.extraGroups.students.gid = 1000;
+</programlisting>
+
+As with users, the group ID (gid) is optional and will be assigned
+automatically if it’s missing.</para>
+
+<warning><para>Currently declarative user management is not perfect:
+<command>nixos-rebuild</command> does not know how to realise certain
+configuration changes.  This includes removing a user or group, and
+removing group membership from a user.</para></warning>
+
+<para>In the imperative style, users and groups are managed by
+commands such as <command>useradd</command>,
+<command>groupmod</command> and so on.  For instance, to create a user
+account named <literal>alice</literal>:
+
+<screen>
+$ useradd -m alice</screen>
+
+The flag <option>-m</option> 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 <command>passwd</command> utility:
+
+<screen>
+$ passwd alice
+Enter new UNIX password: ***
+Retype new UNIX password: ***
+</screen>
+
+A user can be deleted using <command>userdel</command>:
+
+<screen>
+$ userdel -r alice</screen>
+
+The flag <option>-r</option> deletes the user’s home directory.
+Accounts can be modified using <command>usermod</command>.  Unix
+groups can be managed using <command>groupadd</command>,
+<command>groupmod</command> and <command>groupdel</command>.</para>
+
+</section>
+
+
 <!--===============================================================-->
 
 <section><title>Networking</title>
diff --git a/doc/manual/running.xml b/doc/manual/running.xml
index ac3ce40339d..5799aeec5d0 100644
--- a/doc/manual/running.xml
+++ b/doc/manual/running.xml
@@ -282,6 +282,11 @@ Dec 29 01:30:22 mandark kernel[6131]: [1053513.909444] CPU6: Core temperature ab
 
 </para>
 
+<para>The system journal is readable by root and by users in the
+<literal>wheel</literal> and <literal>systemd-journal</literal>
+groups.  All users have a private journal that can be read using
+<command>journalctl</command>.</para>
+
 </section>