caret _
writeup — How to mount a secondary drive using LUKS on NixOS
2025-07-19  •  nixos · linux · luks  •  ~3 min

LUKS is nice, but I wanted more encryption for my secondary drive. This would already assume the root system is decrypted before starting this process, so because of that I decided to just use a key file. I'm not typing a second password in everytime!

Setting up the drive

Assuming you have a secondary drive under the device name /dev/nvme0n1, we will mount it under /SSD automatically on boot using a LUKS keyfile. This method is nice because it doesn't require the user to type in the password or have TPM functional (although, apparently LUKS supports TPM, maybe I'll try that some other time).

Step 1: Partition the drive

First, partition the drive using your partitioner of choice. I like cfdisk:

$ sudo cfdisk /dev/nvme0n1

Create a single partition that uses the entire disk. You can set the partition type to 'Linux filesystem' (the default).

Step 2: Setup LUKS encryption

Initialize the partition with LUKS encryption:

$ sudo cryptsetup luksFormat /dev/nvme0n1p1

This will prompt you for a recovery passphrase. Don't forget this passphrase - it's your backup method if the key file fails.

Open the encrypted partition to make it usable:

$ sudo cryptsetup luksOpen /dev/nvme0n1p1 ssd

Step 3: Create the key file

Create a directory for storing secrets and generate a random key file:

$ sudo mkdir -p /etc/nixos/secrets
$ sudo dd if=/dev/urandom of=/etc/nixos/secrets/ssd-key bs=1024 count=4
$ sudo chmod 400 /etc/nixos/secrets/ssd-key
$ sudo chown root:root /etc/nixos/secrets/ssd-key

This key file is what the system will use for automatic decryption during boot.

Add the key file to your LUKS device:

$ sudo cryptsetup luksAddKey /dev/nvme0n1p1 /etc/nixos/secrets/ssd-key

Step 4: Format and test

Format the decrypted partition with your preferred filesystem:

$ sudo mkfs.ext4 -L ssd-data /dev/mapper/ssd

Test mounting it manually:

$ sudo mkdir -p /SSD
$ sudo mount /dev/mapper/ssd /SSD
$ ls -la /SSD
$ sudo umount /SSD

Close the LUKS device to test the key file:

$ sudo cryptsetup luksClose ssd

Now test unlocking with the key file:

$ sudo cryptsetup luksOpen /dev/nvme0n1p1 ssd --key-file /etc/nixos/secrets/ssd-key
$ sudo mount /dev/mapper/ssd /SSD
$ ls -la /SSD  # Should show lost+found directory
$ sudo umount /SSD
$ sudo cryptsetup luksClose ssd

If all of that works, you're ready to configure NixOS for automatic mounting.

Adding to NixOS Configuration

Now we need to configure NixOS to automatically unlock and mount this drive on boot.

Step 1: Find your LUKS UUID

First, get the UUID of your LUKS partition:

$ sudo blkid /dev/nvme0n1p1

Look for the line with TYPE="crypto_LUKS" and note the UUID value.

Step 2: Update your NixOS configuration

Add the following to your /etc/nixos/configuration.nix:

{ config, pkgs, ... }:

{
  # Mount after booting
  environment.etc."crypttab".text = ''
    ssd /dev/disk/by-uuid/YOUR-LUKS-UUID-HERE /etc/nixos/secrets/ssd-key luks,nofail
  '';

  # Mount the encrypted drive at /SSD
  fileSystems."/SSD" = {
    device = "/dev/mapper/ssd";
    fsType = "ext4";
    options = [ "defaults" "user" "rw" "nofail" ];
  };

  # Create the mount point directory
  systemd.tmpfiles.rules = [
    "d /SSD 0755 root root -"
  ];

  # Rest of your configuration...
}

Step 3: Rebuild and test

Apply the configuration:

$ sudo nixos-rebuild switch

If there are no errors, reboot to test:

$ sudo reboot

After reboot, check that your drive is automatically mounted:

$ df -h | grep SSD
$ ls -la /SSD

Troubleshooting

Drive not mounting automatically

  • Check that the UUID in your config matches: sudo blkid /dev/nvme0n1p1
  • Verify key file permissions: ls -la /etc/nixos/secrets/ssd-key
  • Check system logs: sudo journalctl -b | grep -i luks

Permission issues

Make sure the mount point has correct permissions:

$ sudo chown $USER:users /SSD
$ sudo chmod 755 /SSD

Recovery

If you need to access the drive manually (e.g., the key file is lost):

$ sudo cryptsetup luksOpen /dev/nvme0n1p1 ssd  # Will prompt for passphrase
$ sudo mount /dev/mapper/ssd /SSD

Security Notes

  • The key file is stored on your root filesystem, so this setup only protects against casual access or drive theft (assuming your root drive is also encrypted)
  • For maximum security, you could store the key file on a separate USB drive
  • Always keep a backup of your LUKS header: sudo cryptsetup luksHeaderBackup /dev/nvme0n1p1 --header-backup-file ~/luks-backup.img
  • Remember your recovery passphrase - it's your fallback if the key file fails

This setup gives you the convenience of automatic mounting while maintaining encryption for your secondary drive data.

← Back
Comments
×