lix/doc/manual/installation/installing-binary.xml
2020-05-21 19:58:11 +02:00

295 lines
9 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="ch-installing-binary">
<title>Installing a Binary Distribution</title>
<para>If you are using Linux or macOS, the easiest way to install Nix
is to run the following command:
<screen>
$ sh &lt;(curl https://nixos.org/nix/install)
</screen>
As of Nix 2.1.0, the Nix installer will always default to creating a
single-user installation, however opting in to the multi-user
installation is highly recommended.
</para>
<section xml:id="sect-single-user-installation">
<title>Single User Installation</title>
<para>
To explicitly select a single-user installation on your system:
<screen>
sh &lt;(curl https://nixos.org/nix/install) --no-daemon
</screen>
</para>
<para>
This will perform a single-user installation of Nix, meaning that
<filename>/nix</filename> is owned by the invoking user. You should
run this under your usual user account, <emphasis>not</emphasis> as
root. The script will invoke <command>sudo</command> to create
<filename>/nix</filename> if it doesnt already exist. If you dont
have <command>sudo</command>, you should manually create
<command>/nix</command> first as root, e.g.:
<screen>
$ mkdir /nix
$ chown alice /nix
</screen>
The install script will modify the first writable file from amongst
<filename>.bash_profile</filename>, <filename>.bash_login</filename>
and <filename>.profile</filename> to source
<filename>~/.nix-profile/etc/profile.d/nix.sh</filename>. You can set
the <command>NIX_INSTALLER_NO_MODIFY_PROFILE</command> environment
variable before executing the install script to disable this
behaviour.
</para>
<para>You can uninstall Nix simply by running:
<screen>
$ rm -rf /nix
</screen>
</para>
</section>
<section xml:id="sect-multi-user-installation">
<title>Multi User Installation</title>
<para>
The multi-user Nix installation creates system users, and a system
service for the Nix daemon.
</para>
<itemizedlist>
<title>Supported Systems</title>
<listitem>
<para>Linux running systemd, with SELinux disabled</para>
</listitem>
<listitem><para>macOS</para></listitem>
</itemizedlist>
<para>
You can instruct the installer to perform a multi-user
installation on your system:
<screen>
sh &lt;(curl https://nixos.org/nix/install) --daemon
</screen>
</para>
<para>
The multi-user installation of Nix will create build users between
the user IDs 30001 and 30032, and a group with the group ID 30000.
You should run this under your usual user account,
<emphasis>not</emphasis> as root. The script will invoke
<command>sudo</command> as needed.
</para>
<note><para>
If you need Nix to use a different group ID or user ID set, you
will have to download the tarball manually and <link
linkend="sect-nix-install-binary-tarball">edit the install
script</link>.
</para></note>
<para>
The installer will modify <filename>/etc/bashrc</filename>, and
<filename>/etc/zshrc</filename> if they exist. The installer will
first back up these files with a
<literal>.backup-before-nix</literal> extension. The installer
will also create <filename>/etc/profile.d/nix.sh</filename>.
</para>
<para>You can uninstall Nix with the following commands:
<screen>
sudo rm -rf /etc/profile/nix.sh /etc/nix /nix ~root/.nix-profile ~root/.nix-defexpr ~root/.nix-channels ~/.nix-profile ~/.nix-defexpr ~/.nix-channels
# If you are on Linux with systemd, you will need to run:
sudo systemctl stop nix-daemon.socket
sudo systemctl stop nix-daemon.service
sudo systemctl disable nix-daemon.socket
sudo systemctl disable nix-daemon.service
sudo systemctl daemon-reload
# If you are on macOS, you will need to run:
sudo launchctl unload /Library/LaunchDaemons/org.nixos.nix-daemon.plist
sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist
</screen>
There may also be references to Nix in
<filename>/etc/profile</filename>,
<filename>/etc/bashrc</filename>, and
<filename>/etc/zshrc</filename> which you may remove.
</para>
</section>
<section xml:id="sect-apfs-volume-installation">
<title>APFS Volume Installation</title>
<para>
The root filesystem is read-only as of macOS 10.15 Catalina, all writable
paths to a separate data volume. This means creating or writing to <filename>/nix</filename>
is not allowed. While changing the default prefix would be possible, it's
a very intrusive change that has side effects we want to avoid for now.
</para>
<para>
For common writable locations <literal>firmlinks</literal> where introduced,
described by Apple as a "bi-directional wormhole" between two filesystems.
Essentially a bind mount for APFS volumes. However this is (currently) not
user configurable and only available for paths like <filename>/Users</filename>.
</para>
<para>
For special cases like NFS mount points or package manager roots <link xlink:href="https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man5/synthetic.conf.5.html">synthetic.conf(5)</link>
provides a mechanism for some limited, user-controlled file-creation at <filename>/</filename>.
This only applies on a reboot, but <command>apfs.util</command> can be used
to trigger the creation (not deletion) of new entries.
</para>
<screen>
alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B
</screen>
<itemizedlist>
<listitem>
<para>
The simplest solution is creating a symlink with <filename>/etc/synthetic.conf</filename>
to the data volume. (not recommended)
</para>
<screen>
nix /System/Volumes/Data/nix
</screen>
<screen>
alice$ ls -l /
lrwxr-xr-x 1 root wheel 25 Jan 1 2019 nix -> /System/Volumes/Data/nix
</screen>
<para>
However builds that detect or resolve this symlink will leak the canonical
location or even fail in certain cases, making this approach undesirable.
</para>
</listitem>
<listitem>
<para>
An empty directory can also be created using <filename>/etc/synthetic.conf</filename>,
this won't be writable but can be used as a mount point. And with
<literal>APFS</literal> it's relatively easy to create an separate
volume for nix instead.
</para>
<screen>
nix
</screen>
<screen>
alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B
alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix
alice$ mount
/dev/disk1s6 on /nix (apfs, local, journaled)
</screen>
<para>
This does make the installation more complicated, requiring both
<filename>/etc/synthetic.conf</filename> as well as <filename>/etc/fstab</filename>
</para>
<screen>
#
# Warning - this file should only be modified with vifs(8)
#
# Failure to do so is unsupported and may be destructive.
#
LABEL=Nix\040Store /nix apfs rw
</screen>
<para>
On macOS volumes are also mounted quite late, launchd services or other
things that start during login will start before our volume is mounted.
For these cases eg. <command>wait4path</command> must be used for
things that depend on <filename>/nix</filename>.
</para>
<para>
This new volume also won't be encrypted by default, and enabling is
only possible interactively?
</para>
<screen>
alice$ diskutil apfs enableFileVault /nix -user disk
</screen>
</listitem>
</itemizedlist>
</section>
<section xml:id="sect-nix-install-pinned-version-url">
<title>Installing a pinned Nix version from a URL</title>
<para>
NixOS.org hosts version-specific installation URLs for all Nix
versions since 1.11.16, at
<literal>https://releases.nixos.org/nix/nix-<replaceable>version</replaceable>/install</literal>.
</para>
<para>
These install scripts can be used the same as the main
NixOS.org installation script:
<screen>
sh &lt;(curl https://nixos.org/nix/install)
</screen>
</para>
<para>
In the same directory of the install script are sha256 sums, and
gpg signature files.
</para>
</section>
<section xml:id="sect-nix-install-binary-tarball">
<title>Installing from a binary tarball</title>
<para>
You can also download a binary tarball that contains Nix and all
its dependencies. (This is what the install script at
<uri>https://nixos.org/nix/install</uri> does automatically.) You
should unpack it somewhere (e.g. in <filename>/tmp</filename>),
and then run the script named <command>install</command> inside
the binary tarball:
<screen>
alice$ cd /tmp
alice$ tar xfj nix-1.8-x86_64-darwin.tar.bz2
alice$ cd nix-1.8-x86_64-darwin
alice$ ./install
</screen>
</para>
<para>
If you need to edit the multi-user installation script to use
different group ID or a different user ID range, modify the
variables set in the file named
<filename>install-multi-user</filename>.
</para>
</section>
</chapter>