diff --git a/doc/manual/installation/installing-binary.xml b/doc/manual/installation/installing-binary.xml
index 498248662..8d548f0ea 100644
--- a/doc/manual/installation/installing-binary.xml
+++ b/doc/manual/installation/installing-binary.xml
@@ -6,16 +6,30 @@
Installing a Binary Distribution
-If you are using Linux or macOS, the easiest way to install Nix
-is to run the following command:
+
+ 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:
+
$ sh <(curl https://nixos.org/nix/install)
-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.
+
+ If you're using macOS 10.15 (Catalina) or newer, consult
+ the macOS installation instructions
+ before installing.
+
+
+
+ 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.
+
@@ -36,7 +50,7 @@ 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, e.g.:
+/nix first as root, e.g.:
$ mkdir /nix
@@ -47,7 +61,7 @@ The install script will modify the first writable file from amongst
.bash_profile, .bash_login
and .profile to source
~/.nix-profile/etc/profile.d/nix.sh. You can set
-the NIX_INSTALLER_NO_MODIFY_PROFILE environment
+the NIX_INSTALLER_NO_MODIFY_PROFILE environment
variable before executing the install script to disable this
behaviour.
@@ -81,12 +95,10 @@ $ rm -rf /nix
You can instruct the installer to perform a multi-user
installation on your system:
-
-
- sh <(curl https://nixos.org/nix/install) --daemon
-
+ sh <(curl https://nixos.org/nix/install) --daemon
+
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.
@@ -136,82 +148,253 @@ sudo rm /Library/LaunchDaemons/org.nixos.nix-daemon.plist
-
- APFS Volume Installation
+
+ macOS Installation
- The root filesystem is read-only as of macOS 10.15 Catalina, all writable
- paths were moved to a separate data volume. This means creating or writing
- to /nix 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.
+ Starting with macOS 10.15 (Catalina), the root filesystem is read-only.
+ This means /nix can no longer live on your system
+ volume, and that you'll need a workaround to install Nix.
- For common writable locations firmlinks were 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 /Users.
+ The recommended approach, which creates an unencrypted APFS volume
+ for your Nix store and a "synthetic" empty directory to mount it
+ over at /nix, is least likely to impair Nix
+ or your system.
+
+ 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.
+
+
- For special cases like NFS mount points or package manager roots synthetic.conf(5)
- provides a mechanism for some limited, user-controlled file-creation at /.
- This only applies at boot time, however apfs.util can be used
- to trigger the creation (not deletion) of new entries without a reboot.
- It would be ideal if this could create firmlinks, however a symlink or mountpoint
- are the only options.
+ If you're using a recent Mac with a
+ T2 chip,
+ 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:
-
-alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B
-
+ $ sh <(curl https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume
-
-
-
- The simplest solution is creating a symlink with /etc/synthetic.conf
- to the data volume. (not recommended)
-
+
+ If you don't like the sound of this, you'll want to weigh the
+ other approaches and tradeoffs detailed in this section.
+
-
-nix /System/Volumes/Data/nix
-
+
+ Eventual solutions?
+
+ 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:
+
+
+
+
+ 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.
+
+
+
+
+ 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.
+
+
+
+
-
-alice$ ls -l /
-lrwxr-xr-x 1 root wheel 25 Jan 1 2019 nix -> /System/Volumes/Data/nix
-
+
+ Change the Nix store path prefix
+
+ 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:
-
- However builds that detect or resolve this symlink will leak the canonical
- location or even fail in certain cases, making this approach undesirable.
-
-
+
+
+
+ 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.
+
+
+
+
+ It's harder to build and deploy packages to Linux systems.
+
+
+
+
-
-
- An empty directory can also be created using /etc/synthetic.conf,
- this won't be writable but can be used as a mount point. And with
- APFS it's relatively easy to create an separate
- volume for nix instead.
-
+
-
-nix
-
+ 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.
+
+
+
+
+
-
-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)
-
+
+ Use a separate encrypted volume
+
+ 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.
+
+
+
+ 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:
+
+
+
+
+ The additional volume won't be encrypted with your existing
+ FileVault key, so you'll need another mechanism to decrypt
+ the volume.
+
+
+
+
+ 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.
+
+
+ On a case-by-case basis, you may be able to work around this
+ problem by using wait4path to block
+ execution until your executable is available.
+
+
+ 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.
+
+
+
+
+ You can hard-code the password in the clear, so that your
+ store volume can be decrypted before Keychain is available.
+
+
+
+
+ If you are comfortable navigating these tradeoffs, you can encrypt the volume with
+ something along the lines of:
+
+
+
+ alice$ diskutil apfs enableFileVault /nix -user disk
+
+
+
+
+
+
+ Symlink the Nix store to a custom location
+
+ Another simple approach is using /etc/synthetic.conf
+ 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.
+
+
+ Because of these downsides, we can't recommend this approach.
+
+
+
+
+
+ Notes on the recommended approach
+
+ 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.
+
+
+
+
+ In order to compose user-writable locations into the new
+ read-only system root, Apple introduced a new concept called
+ firmlinks, which it describes as a
+ "bi-directional wormhole" between two filesystems. You can
+ see the current firmlinks in /usr/share/firmlinks.
+ Unfortunately, firmlinks aren't (currently?) user-configurable.
+
+
+
+ For special cases like NFS mount points or package manager roots,
+ synthetic.conf(5)
+ supports limited user-controlled file-creation (of symlinks,
+ and synthetic empty directories) at /.
+ To create a synthetic empty directory for mounting at /nix,
+ add the following line to /etc/synthetic.conf
+ (create it if necessary):
+
+
+ nix
+
+
+
+
+ This configuration is applied at boot time, but you can use
+ apfs.util to trigger creation (not deletion)
+ of new entries without a reboot:
+
+
+ alice$ /System/Library/Filesystems/apfs.fs/Contents/Resources/apfs.util -B
+
+
+
+
+ Create the new APFS volume with diskutil:
+
+
+ alice$ sudo diskutil apfs addVolume diskX APFS 'Nix Store' -mountpoint /nix
+
+
+
+
+ Using vifs, add the new mount to
+ /etc/fstab. If it doesn't already have
+ other entries, it should look something like:
+
#
@@ -219,29 +402,16 @@ alice$ mount
#
# Failure to do so is unsupported and may be destructive.
#
-LABEL=Nix\040Store /nix apfs rw
+LABEL=Nix\040Store /nix apfs rw,nobrowse
-
- 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. wait4path must be used for
- things that depend on /nix.
-
-
-
- This new volume also won't be encrypted by default, and enabling it
- requires extra setup. For machines with a T2 chip
- all data is already entrypted at rest, older hardware won't even when
- FileVault is enabled for the rest of the system.
-
-
-
-alice$ diskutil apfs enableFileVault /nix -user disk
-
-
-
-
+
+ The nobrowse setting will keep Spotlight from indexing this
+ volume, and keep it from showing up on your desktop.
+
+
+
+
diff --git a/scripts/create-darwin-volume.sh b/scripts/create-darwin-volume.sh
index a0da85f43..47cc3e913 100755
--- a/scripts/create-darwin-volume.sh
+++ b/scripts/create-darwin-volume.sh
@@ -59,10 +59,45 @@ test_nix() {
test -d "/nix"
}
-test_filevault() {
+test_t2_chip_present(){
+ # Use xartutil to see if system has a t2 chip.
+ #
+ # This isn't well-documented on its own; until it is,
+ # let's keep track of knowledge/assumptions.
+ #
+ # Warnings:
+ # - Don't search "xart" if porn will cause you trouble :)
+ # - Other xartutil flags do dangerous things. Don't run them
+ # naively. If you must, search "xartutil" first.
+ #
+ # Assumptions:
+ # - the "xART session seeds recovery utility"
+ # appears to interact with xartstorageremoted
+ # - `sudo xartutil --list` lists xART sessions
+ # and their seeds and exits 0 if successful. If
+ # not, it exits 1 and prints an error such as:
+ # xartutil: ERROR: No supported link to the SEP present
+ # - xART sessions/seeds are present when a T2 chip is
+ # (and not, otherwise)
+ # - the presence of a T2 chip means a newly-created
+ # volume on the primary drive will be
+ # encrypted at rest
+ # - all together: `sudo xartutil --list`
+ # should exit 0 if a new Nix Store volume will
+ # be encrypted at rest, and exit 1 if not.
+ sudo xartutil --list >/dev/null 2>/dev/null
+}
+
+test_filevault_in_use() {
disk=$1
- apfs_volumes_for "$disk" | volume_list_true FileVault | grep -q true || return
- ! sudo xartutil --list >/dev/null 2>/dev/null
+ # list vols on disk | get value of Filevault key | value is true
+ apfs_volumes_for "$disk" | volume_list_true FileVault | grep -q true
+}
+
+# use after error msg for conditions we don't understand
+suggest_report_error(){
+ # ex "error: something sad happened :(" >&2
+ echo " please report this @ https://github.com/nixos/nix/issues" >&2
}
main() {
@@ -89,7 +124,8 @@ main() {
echo "Configuring /etc/synthetic.conf..." >&2
echo nix | sudo tee /etc/synthetic.conf
if ! test_synthetic_conf; then
- echo "error: failed to configure synthetic.conf" >&2
+ echo "error: failed to configure synthetic.conf;" >&2
+ suggest_report_error
exit 1
fi
fi
@@ -101,7 +137,8 @@ main() {
sudo mkdir -p /nix 2>/dev/null || true
fi
if ! test_nix; then
- echo "error: failed to bootstrap /nix, a reboot might be required" >&2
+ echo "error: failed to bootstrap /nix; if a reboot doesn't help," >&2
+ suggest_report_error
exit 1
fi
fi
@@ -111,10 +148,25 @@ main() {
if [ -z "$volume" ]; then
echo "Creating a Nix Store volume..." >&2
- if test_filevault "$disk"; then
- echo "error: FileVault detected, refusing to create unencrypted volume" >&2
- echo "See https://nixos.org/nix/manual/#sect-apfs-volume-installation" >&2
- exit 1
+ if test_filevault_in_use "$disk"; then
+ # TODO: Not sure if it's in-scope now, but `diskutil apfs list`
+ # shows both filevault and encrypted at rest status, and it
+ # may be the more semantic way to test for this? It'll show
+ # `FileVault: No (Encrypted at rest)`
+ # `FileVault: No`
+ # `FileVault: Yes (Unlocked)`
+ # and so on.
+ if test_t2_chip_present; then
+ echo "warning: boot volume is FileVault-encrypted, but the Nix store volume" >&2
+ echo " is only encrypted at rest." >&2
+ echo " See https://nixos.org/nix/manual/#sect-macos-installation" >&2
+ else
+ echo "error: refusing to create Nix store volume because the boot volume is" >&2
+ echo " FileVault encrypted, but encryption-at-rest is not available." >&2
+ echo " Manually create a volume for the store and re-run this script." >&2
+ echo " See https://nixos.org/nix/manual/#sect-macos-installation" >&2
+ exit 1
+ fi
fi
sudo diskutil apfs addVolume "$disk" APFS 'Nix Store' -mountpoint /nix
@@ -128,13 +180,6 @@ main() {
label=$(echo "$volume" | sed 's/ /\\040/g')
printf "\$a\nLABEL=%s /nix apfs rw,nobrowse\n.\nwq\n" "$label" | EDITOR=ed sudo vifs
fi
-
- echo "" >&2
- echo "The following options can be enabled to disable spotlight indexing" >&2
- echo "of the volume, which might be desirable." >&2
- echo "" >&2
- echo " $ sudo mdutil -i off /nix" >&2
- echo "" >&2
}
main "$@"
diff --git a/scripts/install-nix-from-closure.sh b/scripts/install-nix-from-closure.sh
index 2f291ed4c..72aa5abf5 100644
--- a/scripts/install-nix-from-closure.sh
+++ b/scripts/install-nix-from-closure.sh
@@ -52,7 +52,7 @@ while [ $# -gt 0 ]; do
NIX_INSTALLER_NO_CHANNEL_ADD=1;;
--no-modify-profile)
NIX_INSTALLER_NO_MODIFY_PROFILE=1;;
- --create-volume)
+ --darwin-use-unencrypted-nix-store-volume)
CREATE_DARWIN_VOLUME=1;;
*)
(
@@ -77,12 +77,13 @@ while [ $# -gt 0 ]; do
echo ""
) >&2
- if [ "$(uname -s)" = "Darwin" ]; then
+ # darwin and Catalina+
+ if [ "$(uname -s)" = "Darwin" ] && [ "$macos_major" -gt 14 ]; then
(
- echo " --create-volume: Create an APFS volume for the store and create the /nix"
- echo " mountpoint for it using synthetic.conf."
- echo " (required on macOS >=10.15)"
- echo " See https://nixos.org/nix/manual/#sect-apfs-volume-installation"
+ echo " --darwin-use-unencrypted-nix-store-volume: Create an APFS volume for the Nix"
+ echo " store and mount it at /nix. This is the recommended way to create"
+ echo " /nix with a read-only / on macOS >=10.15."
+ echo " See: https://nixos.org/nix/manual/#sect-macos-installation"
echo ""
) >&2
fi
@@ -98,12 +99,12 @@ if [ "$(uname -s)" = "Darwin" ]; then
fi
info=$(diskutil info -plist / | xpath "/plist/dict/key[text()='Writable']/following-sibling::true[1]" 2> /dev/null)
- if ! [ -e $dest ] && [ -n "$info" ]; then
+ if ! [ -e $dest ] && [ -n "$info" ] && [ "$macos_major" -gt 14 ]; then
(
echo ""
echo "Installing on macOS >=10.15 requires relocating the store to an apfs volume."
- echo "Use sh <(curl https://nixos.org/nix/install) --create-volume or run the preparation steps manually."
- echo "See https://nixos.org/nix/manual/#sect-apfs-volume-installation"
+ echo "Use sh <(curl https://nixos.org/nix/install) --darwin-use-unencrypted-nix-store-volume or run the preparation steps manually."
+ echo "See https://nixos.org/nix/manual/#sect-macos-installation"
echo ""
) >&2
exit 1