lix/doc/manual/installation/installing-binary.xml

295 lines
9 KiB
XML
Raw Normal View History

2014-08-27 16:41:09 +00:00
<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:
2014-08-27 16:41:09 +00:00
<screen>
$ sh &lt;(curl https://nixos.org/nix/install)
2014-08-27 16:41:09 +00:00
</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>
2014-08-27 16:41:09 +00:00
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
2014-11-24 14:34:17 +00:00
<command>/nix</command> first as root, e.g.:
2014-08-27 16:41:09 +00:00
<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.
2014-08-27 16:41:09 +00:00
</para>
<para>You can uninstall Nix simply by running:
2014-08-27 16:41:09 +00:00
<screen>
$ rm -rf /nix
</screen>
2014-08-27 16:41:09 +00:00
</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:
2014-08-27 16:41:09 +00:00
<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>
2014-08-27 16:41:09 +00:00
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>
2014-08-27 16:41:09 +00:00
</section>
2014-08-27 16:41:09 +00:00
2020-01-17 22:27:29 +00:00
<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
2020-01-17 22:27:29 +00:00
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
2020-01-17 22:27:29 +00:00
</screen>
</listitem>
</itemizedlist>
</section>
<section xml:id="sect-nix-install-pinned-version-url">
<title>Installing a pinned Nix version from a URL</title>
2014-08-27 16:41:09 +00:00
<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>
2014-08-27 16:41:09 +00:00
<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>
2014-08-27 16:41:09 +00:00
<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>
2014-11-24 14:34:17 +00:00
</chapter>