From 8901acc97664aa8ebf687ee904428aa57a5192be Mon Sep 17 00:00:00 2001 From: Mikey Ariel Date: Wed, 27 Aug 2014 18:41:09 +0200 Subject: Restructuring the Nix manual --- doc/manual/installation/building-source.xml | 57 ++++++++++++ doc/manual/installation/env-variables.xml | 24 +++++ doc/manual/installation/installation.xml | 34 ++++++++ doc/manual/installation/installing-binary.xml | 81 +++++++++++++++++ doc/manual/installation/installing-source.xml | 17 ++++ doc/manual/installation/multi-user.xml | 106 +++++++++++++++++++++++ doc/manual/installation/nix-security.xml | 27 ++++++ doc/manual/installation/obtaining-source.xml | 30 +++++++ doc/manual/installation/prerequisites-source.xml | 73 ++++++++++++++++ doc/manual/installation/single-user.xml | 21 +++++ doc/manual/installation/supported-platforms.xml | 38 ++++++++ 11 files changed, 508 insertions(+) create mode 100644 doc/manual/installation/building-source.xml create mode 100644 doc/manual/installation/env-variables.xml create mode 100644 doc/manual/installation/installation.xml create mode 100644 doc/manual/installation/installing-binary.xml create mode 100644 doc/manual/installation/installing-source.xml create mode 100644 doc/manual/installation/multi-user.xml create mode 100644 doc/manual/installation/nix-security.xml create mode 100644 doc/manual/installation/obtaining-source.xml create mode 100644 doc/manual/installation/prerequisites-source.xml create mode 100644 doc/manual/installation/single-user.xml create mode 100644 doc/manual/installation/supported-platforms.xml (limited to 'doc/manual/installation') diff --git a/doc/manual/installation/building-source.xml b/doc/manual/installation/building-source.xml new file mode 100644 index 000000000000..2202ec73febe --- /dev/null +++ b/doc/manual/installation/building-source.xml @@ -0,0 +1,57 @@ +
+ +Building Nix from Source + +After unpacking or checking out the Nix sources, issue the +following commands: + + +$ ./configure options... +$ make +$ make install + +Nix requires GNU Make so you may need to invoke +gmake instead. + +When building from the Git repository, these should be preceded +by the command: + + +$ ./bootstrap.sh + + + +The installation path can be specified by passing the + to +configure. The default installation directory is +/usr/local. You can change this to any location +you like. You must have write permission to the +prefix path. + +Nix keeps its store (the place where +packages are stored) in /nix/store by default. +This can be changed using +. + +It is best not 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. + +Nix keeps state (such as its database and log files) in +/nix/var by default. This can be changed using +. + +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 + +and + +options. + +
\ No newline at end of file diff --git a/doc/manual/installation/env-variables.xml b/doc/manual/installation/env-variables.xml new file mode 100644 index 000000000000..fc39cdd9dfef --- /dev/null +++ b/doc/manual/installation/env-variables.xml @@ -0,0 +1,24 @@ + + +Environment Variables + +To use Nix, some environment variables should be set. In +particular, PATH should contain the directories +prefix/bin and +~/.nix-profile/bin. The first directory contains +the Nix tools themselves, while ~/.nix-profile is +a symbolic link to the current user environment +(an automatically generated package consisting of symlinks to +installed packages). The simplest way to set the required environment +variables is to include the file +prefix/etc/profile.d/nix.sh +in your ~/.profile (or similar), like this: + + +source prefix/etc/profile.d/nix.sh + + \ No newline at end of file diff --git a/doc/manual/installation/installation.xml b/doc/manual/installation/installation.xml new file mode 100644 index 000000000000..87895935288d --- /dev/null +++ b/doc/manual/installation/installation.xml @@ -0,0 +1,34 @@ + + +Installation + + +This section describes how to install and configure Nix for first-time use. + + + + + + + + + + + diff --git a/doc/manual/installation/installing-binary.xml b/doc/manual/installation/installing-binary.xml new file mode 100644 index 000000000000..a5f9ac844e09 --- /dev/null +++ b/doc/manual/installation/installing-binary.xml @@ -0,0 +1,81 @@ + + +Installing a Binary Distribution + +The easiest way to install Nix is to run the following command: + + +$ bash <(curl https://nixos.org/nix/install) + + +This will perform a single-user installation of Nix, meaning that +/nix is owned by the invoking user. You should +run this under your usual user account, not as +root. The script will invoke sudo to create +/nix if it doesn’t already exist. If you don’t +have sudo, you should manually create +/nix first as root: + + +$ mkdir /nix +$ chown alice /nix + + + + +You can also manually download and install 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 Nix homepage. +You can also get builds of the latest development release from our +continuous +build system. + +For Fedora, RPM packages are available. These can be installed +or upgraded using rpm -U. For example, + + +$ rpm -U nix-1.7-1.i386.rpm + + + +For Debian and Ubuntu, you can download a Deb package and +install it like this: + + +$ dpkg -i nix_1.7-1_amd64.deb + + + +For other platforms, including Mac OS X (Darwin), FreeBSD and +other Linux distributions, you can download a binary tarball that +contains Nix and all its dependencies. (This is what the install +script at https://nixos.org/nix/install uses.) You should +unpack it somewhere (e.g. in /tmp), and then run +the script named install inside the binary tarball: + + +alice$ cd /tmp +alice$ tar xfj nix-1.7-x86_64-darwin.tar.bz2 +alice$ cd nix-1.7-x86_64-darwin +alice$ ./install + + + + +Nix can be uninstalled using rpm -e nix or +dpkg -r nix on RPM- and Dpkg-based systems, +respectively. After this you should manually remove the Nix store and +other auxiliary data, if desired: + + +$ rm -rf /nix + + + + \ No newline at end of file diff --git a/doc/manual/installation/installing-source.xml b/doc/manual/installation/installing-source.xml new file mode 100644 index 000000000000..77beff1bcc78 --- /dev/null +++ b/doc/manual/installation/installing-source.xml @@ -0,0 +1,17 @@ + + +Installing Nix from Source + +If no binary package is available, you can download and compile +a source distribution. + + + + + + + \ No newline at end of file diff --git a/doc/manual/installation/multi-user.xml b/doc/manual/installation/multi-user.xml new file mode 100644 index 000000000000..2eb4c258fcf7 --- /dev/null +++ b/doc/manual/installation/multi-user.xml @@ -0,0 +1,106 @@ +
+ +Multi-User Mode + +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. + +To prevent this, the Nix store and database are owned by some +privileged user (usually root) and builders are +executed under special user accounts (usually named +nixbld1, nixbld2, etc.). When a +unprivileged user runs a Nix command, actions that operate on the Nix +store (such as builds) are forwarded to a Nix +daemon running under the owner of the Nix store/database +that performs the operation. + +Multi-user mode has one important limitation: only +root can run nix-pull to register the availability +of pre-built binaries. However, those registrations are shared by all +users, so they still get the benefit from nix-pulls +done by root. + + + + +Setting up the build users + +The build users are the special UIDs under +which builds are performed. They should all be members of the +build users group nixbld. +This group should have no other members. The build users should not +be members of any other group. On Linux, you can create the group and +users as follows: + + +$ groupadd -r nixbld +$ for n in $(seq 1 10); do useradd -c "Nix build user $n" \ + -d /var/empty -g nixbld -G nixbld -M -N -r -s "$(which nologin)" \ + nixbld$n; done + + +This creates 10 build users. There can never be more concurrent builds +than the number of build users, so you may want to increase this if +you expect to do many builds at the same time. + + + + + + +Running the daemon + +The Nix daemon should be +started as follows (as root): + + +$ nix-daemon + +You’ll want to put that line somewhere in your system’s boot +scripts. + +To let unprivileged users use the daemon, they should set the +NIX_REMOTE environment +variable to daemon. So you should put a +line like + + +export NIX_REMOTE=daemon + +into the users’ login scripts. + + + + + +Restricting access + +To limit which users can perform Nix operations, you can use the +permissions on the directory +/nix/var/nix/daemon-socket. For instance, if you +want to restrict the use of Nix to the members of a group called +nix-users, do + + +$ chgrp nix-users /nix/var/nix/daemon-socket +$ chmod ug=rwx,o= /nix/var/nix/daemon-socket + + +This way, users who are not in the nix-users group +cannot connect to the Unix domain socket +/nix/var/nix/daemon-socket/socket, so they cannot +perform Nix operations. + + + + +
\ No newline at end of file diff --git a/doc/manual/installation/nix-security.xml b/doc/manual/installation/nix-security.xml new file mode 100644 index 000000000000..d888ff14d457 --- /dev/null +++ b/doc/manual/installation/nix-security.xml @@ -0,0 +1,27 @@ + + +Security + +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 root) who performs all package +management operations. All other users can then use the installed +packages, but they cannot perform package management operations +themselves. + +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. + + + + + \ No newline at end of file diff --git a/doc/manual/installation/obtaining-source.xml b/doc/manual/installation/obtaining-source.xml new file mode 100644 index 000000000000..968822cc066e --- /dev/null +++ b/doc/manual/installation/obtaining-source.xml @@ -0,0 +1,30 @@ +
+ +Obtaining a Source Distribution + +The source tarball of the most recent stable release can be +downloaded from the Nix homepage. +You can also grab the most +recent development release. + +Alternatively, the most recent sources of Nix can be obtained +from its Git +repository. For example, the following command will check out +the latest revision into a directory called +nix: + + +$ git clone https://github.com/NixOS/nix + +Likewise, specific releases can be obtained from the tags of the +repository. + +
\ No newline at end of file diff --git a/doc/manual/installation/prerequisites-source.xml b/doc/manual/installation/prerequisites-source.xml new file mode 100644 index 000000000000..47adc9a4fd67 --- /dev/null +++ b/doc/manual/installation/prerequisites-source.xml @@ -0,0 +1,73 @@ +
+ +Prerequisites + + + + GNU Make. + + A version of GCC or Clang that supports C++11. + + Perl 5.8 or higher. + + pkg-config to locate + dependencies. If your distribution does not provide it, you can get + it from . + + The bzip2 compressor program and the + libbz2 library. Thus you must have bzip2 + installed, including development headers and libraries. If your + distribution does not provide these, you can obtain bzip2 from . + + The SQLite embedded database library, version 3.6.19 + or higher. If your distribution does not provide it, please install + it from . + + The Perl DBI and DBD::SQLite libraries, which are + available from CPAN if your + distribution does not provide them. + + The Boehm + garbage collector to reduce the evaluator’s memory + consumption (optional). To enable it, install + pkgconfig and the Boehm garbage collector, and + pass the flag to + configure. + + The xmllint and + xsltproc programs to build this manual and the + man-pages. These are part of the libxml2 and + libxslt packages, respectively. You also need + the DocBook + XSL stylesheets and optionally the DocBook 5.0 RELAX NG + schemas. Note that these are only required if you modify the + manual sources or when you are building from the Git + repository. + + 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 GNU FTP + server. For Flex, you need version 2.5.35, which is + available on SourceForge. + 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. + + + +
\ No newline at end of file diff --git a/doc/manual/installation/single-user.xml b/doc/manual/installation/single-user.xml new file mode 100644 index 000000000000..09cdaa5d4898 --- /dev/null +++ b/doc/manual/installation/single-user.xml @@ -0,0 +1,21 @@ +
+ +Single-User Mode + +In single-user mode, all Nix operations that access the database +in prefix/var/nix/db +or modify the Nix store in +prefix/store must be +performed under the user ID that owns those directories. This is +typically root. (If you +install from RPM packages, that’s in fact the default ownership.) +However, on single-user machines, it is often convenient to +chown those directories to your normal user account +so that you don’t have to su to root all the time. + +
\ No newline at end of file diff --git a/doc/manual/installation/supported-platforms.xml b/doc/manual/installation/supported-platforms.xml new file mode 100644 index 000000000000..a31c6431f002 --- /dev/null +++ b/doc/manual/installation/supported-platforms.xml @@ -0,0 +1,38 @@ + + +Supported Platforms + +Nix is currently supported on the following platforms: + + + + Linux (particularly on x86, x86_64, and + PowerPC). + + Mac OS X. + + FreeBSD (only tested on Intel). + + + + + + + +Nix is pretty portable, so it should work on most other Unix +platforms as well. + + \ No newline at end of file -- cgit 1.4.1