diff options
Diffstat (limited to 'doc/manual/installation.xml')
| -rw-r--r-- | doc/manual/installation.xml | 475 |
1 files changed, 475 insertions, 0 deletions
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml new file mode 100644 index 000000000000..a136d3b1129e --- /dev/null +++ b/doc/manual/installation.xml @@ -0,0 +1,475 @@ +<?xml version="1.0" encoding="utf-8"?> +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xml:id="chap-installation"> + +<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.</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>Installing a binary distribution</title> + +<para>The easiest way to install Nix is to use a binary package. +Binary packages of the latest stable release are available for Fedora, +Debian, Ubuntu, Mac OS X and various other systems from the <link +xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>. +You can also get builds of the latest development release from our +<link +xlink:href="http://hydra.nixos.org/job/nix/trunk/release/latest-finished#tabs-constituents">continuous +build system</link>.</para> + +<para>For Fedora, RPM packages are available. These can be installed +or upgraded using <command>rpm -U</command>. For example, + +<screen> +$ rpm -U nix-1.0-1.i386.rpm</screen> + +</para> + +<para>For Debian and Ubuntu, you can download a Deb package and +install it like this: + +<screen> +$ dpkg -i nix_1.0-1_amd64.deb</screen> + +</para> + +<para>For other platforms, including Mac OS X (Darwin), FreeBSD and +other Linux distributions, you can download a binary tarball. It +contains Nix and all its dependencies. You should unpack it in the +root directory, then run <command>nix-finish-install</command>: + +<screen> +$ cd / +$ tar xfj nix-1.1-x86_64-darwin.tar.bz2 +$ nix-finish-install +</screen> + +After this you can delete +<filename>/usr/bin/nix-finish-install</filename>.</para> + +<para>If you plan to use Nix from a single non-root user account, it’s +probably convenient to change the ownership of the entire Nix store +and database to that user account. In that case, install as follows: + +<screen> +alice$ cd / +alice$ sudo tar xfj nix-1.1-x86_64-darwin.tar.bz2 +alice$ sudo chown -R alice /nix +alice$ nix-finish-install +</screen> + +</para> + +<para>Nix can be uninstalled using <command>rpm -e nix</command> or +<command>dpkg -r nix</command> on RPM- and Dpkg-based systems, +respectively. After this you should manually remove the Nix store and +other auxiliary data, if desired: + +<screen> +$ rm -rf /nix</screen> + +</para> + +</section> + + +<section><title>Installing Nix from source</title> + +<para>If no binary package is available, you can download and compile +a source distribution.</para> + +<section><title>Prerequisites</title> + +<itemizedlist> + + <listitem><para>GNU Make.</para></listitem> + + <listitem><para>A fairly recent version of GCC/G++. Version 2.95 + and higher should work. Clang will also work.</para></listitem> + + <listitem><para>Perl 5.8 or higher.</para></listitem> + + <listitem><para><command>pkg-config</command> to locate + dependencies. If your distribution does not provide it, you can get + it from <link + xlink:href="http://www.freedesktop.org/wiki/Software/pkg-config" + />.</para></listitem> + + <listitem><para>The bzip2 compressor program and the + <literal>libbz2</literal> library. Thus you must have bzip2 + installed, including development headers and libraries. If your + distribution does not provide these, you can obtain bzip2 from <link + xlink:href="http://www.bzip.org/"/>.</para></listitem> + + <listitem><para>The SQLite embedded database library, version 3.6.19 + or higher. If your distribution does not provide it, please install + it from <link xlink:href="http://www.sqlite.org/" />.</para></listitem> + + <listitem><para>The Perl DBI and DBD::SQLite libraries, which are + available from <link + xlink:href="http://search.cpan.org/">CPAN</link> if your + distribution does not provide them.</para></listitem> + + <listitem><para>The <link + xlink:href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm + garbage collector</link> to reduce the evaluator’s memory + consumption (optional). To enable it, install + <literal>pkgconfig</literal> and the Boehm garbage collector, and + pass the flag <option>--enable-gc</option> to + <command>configure</command>.</para></listitem> + + <listitem><para>The <command>xmllint</command> and + <command>xsltproc</command> programs to build this manual and the + man-pages. These are part of the <literal>libxml2</literal> and + <literal>libxslt</literal> packages, respectively. You also need + the <link + xlink:href="http://docbook.sourceforge.net/projects/xsl/">DocBook + XSL stylesheets</link> and optionally the <link + xlink:href="http://www.docbook.org/schemas/5x"> DocBook 5.0 RELAX NG + schemas</link>. Note that these are only required if you modify the + manual sources or when you are building from the Git + repository.</para></listitem> + + <listitem><para>Recent versions of Bison and Flex to build the + parser. (This is because Nix needs GLR support in Bison and + reentrancy support in Flex.) For Bison, you need version 2.6, which + can be obtained from the <link + xlink:href="ftp://alpha.gnu.org/pub/gnu/bison">GNU FTP + server</link>. For Flex, you need version 2.5.35, which is + available on <link + xlink:href="http://lex.sourceforge.net/">SourceForge</link>. + Slightly older versions may also work, but ancient versions like the + ubiquitous 2.5.4a won't. Note that these are only required if you + modify the parser or when you are building from the Git + repository.</para></listitem> + +</itemizedlist> + +</section> + + +<section><title>Obtaining a source distribution</title> + +<para>The source tarball of the most recent stable release can be +downloaded from the <link +xlink:href="http://nixos.org/nix/download.html">Nix homepage</link>. +You can also grab the <link +xlink:href="http://hydra.nixos.org/job/nix/trunk/release/latest-finished#tabs-constituents">most +recent development release</link>.</para> + +<para>Alternatively, the most recent sources of Nix can be obtained +from its <link +xlink:href="https://github.com/NixOS/nix">Git +repository</link>. For example, the following command will check out +the latest revision into a directory called +<filename>nix</filename>:</para> + +<screen> +$ git clone https://github.com/NixOS/nix</screen> + +<para>Likewise, specific releases can be obtained from the <link +xlink:href="https://github.com/NixOS/nix/tags">tags</link> of the +repository.</para> + +</section> + + +<section><title>Building Nix from source</title> + +<para>After unpacking or checking out the Nix sources, issue the +following commands: + +<screen> +$ ./configure <replaceable>options...</replaceable> +$ make +$ make install</screen> + +Nix requires GNU Make so you may need to invoke +<command>gmake</command> instead.</para> + +<para>When building from the Git repository, these should be preceded +by the command: + +<screen> +$ ./bootstrap.sh</screen> + +</para> + +<para>The installation path can be specified by passing the +<option>--prefix=<replaceable>prefix</replaceable></option> to +<command>configure</command>. The default installation directory is +<filename>/usr/local</filename>. You can change this to any location +you like. You must have write permission to the +<replaceable>prefix</replaceable> path.</para> + +<para>Nix keeps its <emphasis>store</emphasis> (the place where +packages are stored) in <filename>/nix/store</filename> by default. +This can be changed using +<option>--with-store-dir=<replaceable>path</replaceable></option>.</para> + +<warning><para>It is best <emphasis>not</emphasis> to change the Nix +store from its default, since doing so makes it impossible to use +pre-built binaries from the standard Nixpkgs channels — that is, all +packages will need to be built from source.</para></warning> + +<para>Nix keeps state (such as its database and log files) in +<filename>/nix/var</filename> by default. This can be changed using +<option>--localstatedir=<replaceable>path</replaceable></option>.</para> + +<para>If you want to rebuild the documentation, pass the full path to +the DocBook RELAX NG schemas and to the DocBook XSL stylesheets using +the +<option>--with-docbook-rng=<replaceable>path</replaceable></option> +and +<option>--with-docbook-xsl=<replaceable>path</replaceable></option> +options.</para> + +</section> + + +</section> + + +<!-- TODO: should be updated +<section><title>Upgrading Nix through Nix</title> + +<para>You can install the latest stable version of Nix through Nix +itself by subscribing to the channel <link +xlink:href="http://nixos.org/releases/nix/channels/nix-stable" />, +or the latest unstable version by subscribing to the channel <link +xlink:href="http://nixos.org/releases/nix/channels/nix-unstable" />. +You can also do a <link linkend="sec-one-click">one-click +installation</link> by clicking on the package links at <link +xlink:href="http://nixos.org/releases/full-index-nix.html" />.</para> + +</section> +--> + + +<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> + +</section> + + +<section xml:id="ssec-multi-user"><title>Multi-user mode</title> + +<para>To allow a Nix store to be shared safely among multiple users, +it is important that users are not able to run builders that modify +the Nix store or database in arbitrary ways, or that interfere with +builds started by other users. If they could do so, they could +install a Trojan horse in some package and compromise the accounts of +other users.</para> + +<para>To prevent this, the Nix store and database are owned by some +privileged user (usually <literal>root</literal>) and builders are +executed under special user accounts (usually named +<literal>nixbld1</literal>, <literal>nixbld2</literal>, etc.). When a +unprivileged user runs a Nix command, actions that operate on the Nix +store (such as builds) are forwarded to a <emphasis>Nix +daemon</emphasis> running under the owner of the Nix store/database +that performs the operation.</para> + +<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 are shared by all +users, so they still get the benefit from <command>nix-pull</command>s +done by <systemitem class="username">root</systemitem>.</para></note> + + +<section><title>Setting up the build users</title> + +<para>The <emphasis>build users</emphasis> are the special UIDs under +which builds are performed. They should all be members of the +<emphasis>build users group</emphasis> (usually called +<literal>nixbld</literal>). This group should have no other members. +The build users should not be members of any other group.</para> + +<para>Here is a typical <filename>/etc/group</filename> definition of +the build users group with 10 build users: + +<programlisting> +nixbld:!:30000:nixbld1,nixbld2,nixbld3,nixbld4,nixbld5,nixbld6,nixbld7,nixbld8,nixbld9,nixbld10 +</programlisting> + +In this example the <literal>nixbld</literal> group has UID 30000, but +of course it can be anything that doesn’t collide with an existing +group.</para> + +<para>Here is the corresponding part of +<filename>/etc/passwd</filename>: + +<programlisting> +nixbld1:x:30001:65534:Nix build user 1:/var/empty:/noshell +nixbld2:x:30002:65534:Nix build user 2:/var/empty:/noshell +nixbld3:x:30003:65534:Nix build user 3:/var/empty:/noshell +... +nixbld10:x:30010:65534:Nix build user 10:/var/empty:/noshell +</programlisting> + +The home directory of the build users should not exist or should be an +empty directory to which they do not have write access.</para> + +<para>The build users should have write access to the Nix store, but +they should not have the right to delete files. Thus the Nix store’s +group should be the build users group, and it should have the sticky +bit turned on (like <filename>/tmp</filename>): + +<screen> +$ chown root.nixbld /nix/store +$ chmod 1775 /nix/store +</screen> + +</para> + +<para>Finally, you should tell Nix to use the build users by +specifying the build users group in the <link +linkend="conf-build-users-group"><literal>build-users-group</literal> +option</link> in the <link linkend="sec-conf-file">Nix configuration +file</link> (usually <literal>/etc/nix/nix.conf</literal>): + +<programlisting> +build-users-group = nixbld +</programlisting> + +</para> + +</section> + + +<section><title>Running the daemon</title> + +<para>The <link linkend="sec-nix-daemon">Nix daemon</link> should be +started as follows (as <literal>root</literal>): + +<screen> +$ nix-daemon</screen> + +You’ll want to put that line somewhere in your system’s boot +scripts.</para> + +<para>To let unprivileged users use the daemon, they should set the +<link linkend="envar-remote"><envar>NIX_REMOTE</envar> environment +variable</link> to <literal>daemon</literal>. So you should put a +line like + +<programlisting> +export NIX_REMOTE=daemon</programlisting> + +into the users’ login scripts.</para> + +</section> + + +<section><title>Restricting access</title> + +<para>To limit which users can perform Nix operations, you can use the +permissions on the directory +<filename>/nix/var/nix/daemon-socket</filename>. For instance, if you +want to restrict the use of Nix to the members of a group called +<literal>nix-users</literal>, do + +<screen> +$ chgrp nix-users /nix/var/nix/daemon-socket +$ chmod ug=rwx,o= /nix/var/nix/daemon-socket +</screen> + +This way, users who are not in the <literal>nix-users</literal> group +cannot connect to the Unix domain socket +<filename>/nix/var/nix/daemon-socket/socket</filename>, so they cannot +perform Nix operations.</para> + +</section> + + +</section> <!-- end of multi-user --> + + +</section> <!-- end of security --> + + +<section><title>Using Nix</title> + +<para>To use Nix, some environment variables should be set. In +particular, <envar>PATH</envar> should contain the directories +<filename><replaceable>prefix</replaceable>/bin</filename> and +<filename>~/.nix-profile/bin</filename>. The first directory contains +the Nix tools themselves, while <filename>~/.nix-profile</filename> is +a symbolic link to the current <emphasis>user environment</emphasis> +(an automatically generated package consisting of symlinks to +installed packages). The simplest way to set the required environment +variables is to include the file +<filename><replaceable>prefix</replaceable>/etc/profile.d/nix.sh</filename> +in your <filename>~/.profile</filename> (or similar), like this:</para> + +<screen> +source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen> + +</section> + + +</chapter> |