diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 2642bca1d7..3a143e44fd 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -6,6 +6,39 @@
<title>Installation</title>
+<section><title>Supported platforms</title>
+
+<para>Nix is currently supported on the following platforms:
+
+<itemizedlist>
+
+ <listitem><para>Linux (particularly on x86, x86_64, and
+ PowerPC).</para></listitem>
+
+ <listitem><para>Mac OS X, both on Intel and
+ PowerPC.</para></listitem>
+
+ <listitem><para>FreeBSD (only tested on Intel).</para></listitem>
+
+ <listitem><para>Windows through <link
+ xlink:href="http://www.cygwin.com/">Cygwin</link>.</para>
+
+ <warning><para>On Cygwin, Nix <emphasis>must</emphasis> be installed
+ on an NTFS partition. It will not work correctly on a FAT
+ partition.</para></warning>
+
+ </listitem>
+
+</itemizedlist>
+
+</para>
+
+<para>Nix is pretty portable, so it should work on most other Unix
+platforms as well.</para>
+
+</section>
+
+
<section><title>Obtaining Nix</title>
<para>The easiest way to obtain Nix is to download a <link
@@ -97,7 +130,7 @@ preceded by the command:
</para>
<screen>
-$ autoreconf -i</screen>
+$ ./boostrap</screen>
<para>The installation path can be specified by passing the
<option>--prefix=<replaceable>prefix</replaceable></option> to
@@ -163,49 +196,44 @@ xlink:href="http://nix.cs.uu.nl/dist/nix/" />.</para>
</section>
-<section><title>Permissions</title>
-
-<para>All Nix operations must be performed under the user ID that owns
-the Nix store and database
-(<filename><replaceable>prefix</replaceable>/store</filename> and
-<filename><replaceable>prefix</replaceable>/var/nix/db</filename>,
-respectively). When installed from the RPM packages, these
-directories are owned by <systemitem class="username">root</systemitem>.</para>
-
-<section><title>Setuid installation</title>
-
-<para>As a somewhat <emphasis>ad hoc</emphasis> hack, you can also
-install the Nix binaries <quote>setuid</quote> so that a Nix store can
-be shared among several users. To do this, configure Nix with the
-<emphasis>--enable-setuid</emphasis> option. Nix will be installed as
-owned by a user and group specified by the
-<option>--with-nix-user=</option><parameter>user</parameter> and
-<option>--with-nix-group=</option><parameter>group</parameter>
-options. E.g.,
+<section><title>Security</title>
+
+<para>Nix has two basic security models. First, it can be used in
+“single-user mode”, which is similar to what most other package
+management tools do: there is a single user (typically <systemitem
+class="username">root</systemitem>) who performs all package
+management operations. All other users can then use the installed
+packages, but they cannot perform package management operations
+themselves.</para>
+
+<para>Alternatively, you can configure Nix in “multi-user mode”. In
+this model, all users can perform package management operations — for
+instance, every user can install software without requiring root
+privileges. Nix ensures that this is secure. For instance, it’s not
+possible for one user to overwrite a package used by another user with
+a Trojan horse.</para>
+
+
+<section><title>Single-user mode</title>
+
+<para>In single-user mode, all Nix operations that access the database
+in <filename><replaceable>prefix</replaceable>/var/nix/db</filename>
+or modify the Nix store in
+<filename><replaceable>prefix</replaceable>/store</filename> must be
+performed under the user ID that owns those directories. This is
+typically <systemitem class="username">root</systemitem>. (If you
+install from RPM packages, that’s in fact the default ownership.)
+However, on single-user machines, it is often convenient to
+<command>chown</command> those directories to your normal user account
+so that you don’t have to <command>su</command> to <systemitem
+class="username">root</systemitem> all the time.</para>
-<screen>
-$ ./configure --enable-setuid --with-nix-user=my_nix_user --with-nix-group=my_nix_group</screen>
-
-The user and group default to <literal>nix</literal>. You should make
-sure that both the user and the group exist. Any <quote>real</quote>
-users that you want to allow access should be added to the Nix
-group.</para>
+</section>
-<warning><para>A setuid installation should only by used if the users
-in the Nix group are mutually trusted, since any user in that group
-has the ability to change anything in the Nix store or database. For
-instance, they could install a trojan horse in executables used by
-other users.</para></warning>
-<warning><para>On some platforms, the Nix binaries will be installed
-as setuid <literal>root</literal>. They drop root privileges
-immediately after startup and switch to the Nix user. The reason for
-this is that both the real and effective user must be set to the Nix
-user, and POSIX has no system call to do this. This is not the case
-on systems that have the <function>setresuid()</function> system call
-(such as Linux and FreeBSD), so on those systems the binaries are
-simply owned by the Nix user.</para></warning>
+<section><title>Multi-user mode</title>
+<para></para>
<!--
@@ -219,11 +247,17 @@ one.
-->
-
+<note><para>Multi-user mode has one important limitation: only
+<systemitem class="username">root</systemitem> can run <command
+linkend="sec-nix-pull">nix-pull</command> to register the availability
+of pre-built binaries. However, those registrations
+<emphasis>are</emphasis> used by all users to speed up
+builds.</para></note>
</section>
-</section>
+
+</section> <!-- end of permissions section -->
<section><title>Using Nix</title>
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index d8fd5ddb21..35b4417f10 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -85,7 +85,7 @@
<title>nix-prefetch-url</title>
<xi:include href="nix-prefetch-url.xml" />
</section>
- <section>
+ <section xml:id="sec-nix-pull">
<title>nix-pull</title>
<xi:include href="nix-pull.xml" />
</section>
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index 43358fe553..c3bc060cb1 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -12,7 +12,9 @@
<itemizedlist>
- <listitem><para>TODO: multi-user support.</para></listitem>
+ <listitem><para>TODO: multi-user support. The old setuid method for
+ sharing a store between multiple users has been
+ removed.</para></listitem>
<listitem><para><command>nix-copy-closure</command> copies the
|
