diff options
Diffstat (limited to 'doc/manual/installation/installing-binary.xml')
| -rw-r--r-- | doc/manual/installation/installing-binary.xml | 469 |
1 files changed, 0 insertions, 469 deletions
diff --git a/doc/manual/installation/installing-binary.xml b/doc/manual/installation/installing-binary.xml deleted file mode 100644 index 64c7a37fb..000000000 --- a/doc/manual/installation/installing-binary.xml +++ /dev/null @@ -1,469 +0,0 @@ -<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 versions up to 10.14 (Mojave), the - easiest way to install Nix is to run the following command: -</para> - -<screen> - $ sh <(curl -L https://nixos.org/nix/install) -</screen> - -<para> - If you're using macOS 10.15 (Catalina) or newer, consult - <link linkend="sect-macos-installation">the macOS installation instructions</link> - before installing. -</para> - -<para> - 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. - <!-- TODO: this explains *neither* why the default version is - single-user, nor why we'd recommend multi-user over the default. - True prospective users don't have much basis for evaluating this. - What's it to me? Who should pick which? Why? What if I pick wrong? - --> -</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 <(curl -L 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 doesn’t already exist. If you don’t -have <command>sudo</command>, you should manually create -<filename>/nix</filename> 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 <envar>NIX_INSTALLER_NO_MODIFY_PROFILE</envar> 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: - </para> - - <screen>sh <(curl -L https://nixos.org/nix/install) --daemon</screen> - - <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-macos-installation"> - <title>macOS Installation</title> - - <para> - Starting with macOS 10.15 (Catalina), the root filesystem is read-only. - This means <filename>/nix</filename> can no longer live on your system - volume, and that you'll need a workaround to install Nix. - </para> - - <para> - The recommended approach, which creates an unencrypted APFS volume - for your Nix store and a "synthetic" empty directory to mount it - over at <filename>/nix</filename>, is least likely to impair Nix - or your system. - </para> - - <note><para> - With all separate-volume approaches, it's possible something on - your system (particularly daemons/services and restored apps) may - need access to your Nix store before the volume is mounted. Adding - additional encryption makes this more likely. - </para></note> - - <para> - If you're using a recent Mac with a - <link xlink:href="https://www.apple.com/euro/mac/shared/docs/Apple_T2_Security_Chip_Overview.pdf">T2 chip</link>, - your drive will still be encrypted at rest (in which case "unencrypted" - is a bit of a misnomer). To use this approach, just install Nix with: - </para> - - <screen>$ sh <(curl -L https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume</screen> - - <para> - If you don't like the sound of this, you'll want to weigh the - other approaches and tradeoffs detailed in this section. - </para> - - <note> - <title>Eventual solutions?</title> - <para> - All of the known workarounds have drawbacks, but we hope - better solutions will be available in the future. Some that - we have our eye on are: - </para> - <orderedlist> - <listitem> - <para> - A true firmlink would enable the Nix store to live on the - primary data volume without the build problems caused by - the symlink approach. End users cannot currently - create true firmlinks. - </para> - </listitem> - <listitem> - <para> - If the Nix store volume shared FileVault encryption - with the primary data volume (probably by using the same - volume group and role), FileVault encryption could be - easily supported by the installer without requiring - manual setup by each user. - </para> - </listitem> - </orderedlist> - </note> - - <section xml:id="sect-macos-installation-change-store-prefix"> - <title>Change the Nix store path prefix</title> - <para> - Changing the default prefix for the Nix store is a simple - approach which enables you to leave it on your root volume, - where it can take full advantage of FileVault encryption if - enabled. Unfortunately, this approach also opts your device out - of some benefits that are enabled by using the same prefix - across systems: - - <itemizedlist> - <listitem> - <para> - Your system won't be able to take advantage of the binary - cache (unless someone is able to stand up and support - duplicate caching infrastructure), which means you'll - spend more time waiting for builds. - </para> - </listitem> - <listitem> - <para> - It's harder to build and deploy packages to Linux systems. - </para> - </listitem> - <!-- TODO: may be more here --> - </itemizedlist> - - <!-- TODO: Yes, but how?! --> - - It would also possible (and often requested) to just apply this - change ecosystem-wide, but it's an intrusive process that has - side effects we want to avoid for now. - <!-- magnificent hand-wavy gesture --> - </para> - <para> - </para> - </section> - - <section xml:id="sect-macos-installation-encrypted-volume"> - <title>Use a separate encrypted volume</title> - <para> - If you like, you can also add encryption to the recommended - approach taken by the installer. You can do this by pre-creating - an encrypted volume before you run the installer--or you can - run the installer and encrypt the volume it creates later. - <!-- TODO: see later note about whether this needs both add-encryption and from-scratch directions --> - </para> - <para> - In either case, adding encryption to a second volume isn't quite - as simple as enabling FileVault for your boot volume. Before you - dive in, there are a few things to weigh: - </para> - <orderedlist> - <listitem> - <para> - The additional volume won't be encrypted with your existing - FileVault key, so you'll need another mechanism to decrypt - the volume. - </para> - </listitem> - <listitem> - <para> - You can store the password in Keychain to automatically - decrypt the volume on boot--but it'll have to wait on Keychain - and may not mount before your GUI apps restore. If any of - your launchd agents or apps depend on Nix-installed software - (for example, if you use a Nix-installed login shell), the - restore may fail or break. - </para> - <para> - On a case-by-case basis, you may be able to work around this - problem by using <command>wait4path</command> to block - execution until your executable is available. - </para> - <para> - It's also possible to decrypt and mount the volume earlier - with a login hook--but this mechanism appears to be - deprecated and its future is unclear. - </para> - </listitem> - <listitem> - <para> - You can hard-code the password in the clear, so that your - store volume can be decrypted before Keychain is available. - </para> - </listitem> - </orderedlist> - <para> - If you are comfortable navigating these tradeoffs, you can encrypt the volume with - something along the lines of: - <!-- TODO: - I don't know if this also needs from-scratch instructions? - can we just recommend use-the-installer-and-then-encrypt? - --> - </para> - <!-- - TODO: it looks like this option can be encryptVolume|encrypt|enableFileVault - - It may be more clear to use encryptVolume, here? FileVault seems - heavily associated with the boot-volume behavior; I worry - a little that it can mislead here, especially as it gets - copied around minus doc context...? - --> - <screen>alice$ diskutil apfs enableFileVault /nix -user disk</screen> - - <!-- TODO: and then go into detail on the mount/decrypt approaches? --> - </section> - - <section xml:id="sect-macos-installation-symlink"> - <!-- - Maybe a good razor is: if we'd hate having to support someone who - installed Nix this way, it shouldn't even be detailed? - --> - <title>Symlink the Nix store to a custom location</title> - <para> - Another simple approach is using <filename>/etc/synthetic.conf</filename> - to symlink the Nix store to the data volume. This option also - enables your store to share any configured FileVault encryption. - Unfortunately, builds that resolve the symlink may leak the - canonical path or even fail. - </para> - <para> - Because of these downsides, we can't recommend this approach. - </para> - <!-- Leaving out instructions for this one. --> - </section> - - <section xml:id="sect-macos-installation-recommended-notes"> - <title>Notes on the recommended approach</title> - <para> - This section goes into a little more detail on the recommended - approach. You don't need to understand it to run the installer, - but it can serve as a helpful reference if you run into trouble. - </para> - <orderedlist> - <listitem> - <para> - In order to compose user-writable locations into the new - read-only system root, Apple introduced a new concept called - <literal>firmlinks</literal>, which it describes as a - "bi-directional wormhole" between two filesystems. You can - see the current firmlinks in <filename>/usr/share/firmlinks</filename>. - Unfortunately, firmlinks aren't (currently?) user-configurable. - </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> - supports limited user-controlled file-creation (of symlinks, - and synthetic empty directories) at <filename>/</filename>. - To create a synthetic empty directory for mounting at <filename>/nix</filename>, - add the following line to <filename>/etc/synthetic.conf</filename> - (create it if necessary): - </para> - - <screen>nix</screen> - </listitem> - - <listitem> - <para> - This configuration is applied at boot time, but you can use - <command>apfs.util</command> to trigger creation (not deletion) - of new entries without a reboot: - </para> - - <screen>alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B</screen> - </listitem> - - <listitem> - <para> - Create the new APFS volume with diskutil: - </para> - - <screen>alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix</screen> - </listitem> - - <listitem> - <para> - Using <command>vifs</command>, add the new mount to - <filename>/etc/fstab</filename>. If it doesn't already have - other entries, it should look something like: - </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,nobrowse -</screen> - - <para> - The nobrowse setting will keep Spotlight from indexing this - volume, and keep it from showing up on your desktop. - </para> - </listitem> - </orderedlist> - </section> - -</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 <(curl -L 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> |