aboutsummaryrefslogtreecommitdiff
path: root/doc/manual/installation.xml
blob: 88f76752e2948f2b3b9d4be5e13e3d37d0119f76 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
<?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/view/nix/trunk/latest">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>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.3 or
  higher (1.875 does <emphasis>not</emphasis> work), 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.33, 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/view/nix/trunk/latest/tarball/download-by-type/file/source-dist">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>

</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>
$ chgrp 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>Nix store/database owned by root</title>

<para>The simplest setup is to let <literal>root</literal> own the Nix
store and database.  I.e.,

<screen>
$ chown -R root /nix/store /nix/var/nix</screen>

</para>

<para>The <link linkend="sec-nix-worker">Nix daemon</link> should be
started as follows (as <literal>root</literal>):

<screen>
$ nix-worker --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>Nix store/database not owned by root</title>

<para>It is also possible to let the Nix store and database be owned
by a non-root user, which should be more secure<footnote><para>Note
however that even when the Nix daemon runs as root, not
<emphasis>that</emphasis> much code is executed as root: Nix
expression evaluation is performed by the calling (unprivileged) user,
and builds are performed under the special build user accounts.  So
only the code that accesses the database and starts builds is executed
as <literal>root</literal>.</para></footnote>.  Typically, this user
is a special account called <literal>nix</literal>, but it can be
named anything.  It should own the Nix store and database:

<screen>
$ chown -R nix /nix/store /nix/var/nix</screen>

and of course <command>nix-worker --daemon</command> should be started
under that user, e.g.,

<screen>
$ su - nix -c "exec /nix/bin/nix-worker --daemon"</screen>

</para>

<para>There is a catch, though: non-<literal>root</literal> users
cannot start builds under the build user accounts, since the
<function>setuid</function> system call is obviously privileged.  To
allow a non-<literal>root</literal> Nix daemon to use the build user
feature, it calls a setuid-root helper program,
<command>nix-setuid-helper</command>.  This program is installed in
<filename><replaceable>prefix</replaceable>/libexec/nix-setuid-helper</filename>.
To set the permissions properly (Nix’s <command>make install</command>
doesn’t do this, since we don’t want to ship setuid-root programs
out-of-the-box):

<screen>
$ chown root.root /nix/libexec/nix-setuid-helper
$ chmod 4755 /nix/libexec/nix-setuid-helper
</screen>

(This example assumes that the Nix binaries are installed in
<filename>/nix</filename>.)</para>

<para>Of course, the <command>nix-setuid-helper</command> command
should not be usable by just anybody, since then anybody could run
commands under the Nix build user accounts.  For that reason there is
a configuration file <filename>/etc/nix-setuid.conf</filename> that
restricts the use of the helper.  This file should be a text file
containing precisely two lines, the first being the Nix daemon user
and the second being the build users group, e.g.,

<programlisting>
nix
nixbld
</programlisting>

The setuid-helper barfs if it is called by a user other than the one
specified on the first line, or if it is asked to execute a build
under a user who is not a member of the group specified on the second
line.  The file <filename>/etc/nix-setuid.conf</filename> must be
owned by root, and must not be group- or world-writable.  The
setuid-helper barfs if this is not the case.</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>~/.bashrc</filename> (or similar), like this:</para>

<screen>
source <replaceable>prefix</replaceable>/etc/profile.d/nix.sh</screen>

</section>


</chapter>