Installing Asahi Linux with Full Disk Encryption on Apple Silicon Macs

This tutorial details the installation of Asahi Linux on an Apple Mac using the ALARM distribution, incorporating full disk encryption (LUKS). This is an advanced procedure and carries inherent risks. Carefully read the warnings and precautions below before proceeding. Incorrect partitioning or LUKS configuration can render your system unbootable and data permanently inaccessible. This guide assumes a working knowledge of Linux command-line operations, partitioning concepts, and macOS administration.

Critical Warning: Data Loss Potential! This procedure will modify existing partitions on the internal drive of your Mac. Before proceeding, create a full backup of your macOS system using Time Machine or another reliable backup method. Verify that your backup is functional before continuing. Proceed at your own risk. The user is responsible for any data loss or damage to the system resulting from following these instructions. Asahi Linux is still in active development; unexpected issues may arise.

1. Preparation and Prerequisites

Hardware Compatibility: Verify your Mac model is officially supported by Asahi Linux. Refer to https://asahilinux.org/compatibility for the latest list.
Asahi ALARM Installation: Install the initial Asahi ALARM distribution. This provides the necessary drivers and bootloader components. Instructions can be found at https://asahilinux.org/. Ensure this initial installation functions correctly before proceeding.
Software: You’re assumed to have a working macOS environment with administrative privileges. rsync, unzip, fdisk, blkid, cryptsetup, lvm2, mkinitcpio, and grub are essential packages. These are generally available through the macOS package manager (Homebrew or similar).
Download Base Image: Download the Asahi Linux base image from https://asahi-alarm.org/asahi-base.zip. Although there are pre-configured images with desktop environment available, this tutorial focuses on the minimal installation.

2. Partitioning Scheme and LUKS Considerations

This installation utilizes a specific partitioning scheme to accommodate LUKS encryption and the unique requirements of the Asahi Linux boot process. Understanding this scheme is crucial for success.

m1n1 Stage 1 (APFS): A small partition (approximately 2.5G) formatted as APFS. This houses the initial bootloader stage and is required for your Mac to boot and run m1n1. Do not modify or delete this partition.
EFI Partition: A separate partition (approximately 500MB) formatted as FAT32. This partition contains the second stage of the bootloader (m1n1 and u-boot) and essential EFI files. It must be separate from the root filesystem.
Boot Partition: A partition formatted as ext4, sized to approximately 500MB. This partition hosts initial kernel images and the GRUB bootloader. It must not be encrypted and therefore separate from the root filesystem.
Encrypted Root File System (LUKS): The majority of the drive space is dedicated to the encrypted root filesystem. This is a LUKS-encrypted partition, containing the core Linux system files.

The separation of the EFI and /boot partitions is vital for the Asahi Linux update process which consists of two stages:

m1n1 stage 1 (APFS)
m1n1 stage 2 (EFI)

Improper configuration in this regard can lead to unbootable systems. It is strongly recommended to let the Asahi ALARM installer handle the partitioning of the APFS and EFI partitions.

3. Installing ASAHI Alarm initially on the Internal Drive

It is recommended to first run the Asahi ALARM installer on the internal drive of your Mac. This will ensure that the system is properly configured, meets all requirements and that the bootloader is functional. Test the installation manually before proceeding by verifying that the system boots correctly.

Note: This step will also set up the initial resizing of your macOS installation. Choose a suitable partition size for the macOS installation and your Linux installation at this point.

Here is a summary of the steps. Always consult the official Asahi ALARM documentation for the most up-to-date instructions and troubleshooting information.

Install Asahi ALARM: Follow the official Asahi ALARM installation instructions.
Configure Bootloader: Configure the bootloader. Consult the official Asahi ALARM documentation for precise commands.
Reboot: Reboot the system.
Test Installation: Verify that the system boots correctly.

4. Creating the Bootable External Drive

This step creates a USB drive containing a minimal Asahi Linux environment for initial setup and partitioning of the actual OS, utilizing full disk encryption. The USB drive serves as a bootable installer and is later used to install the full operating system on the internal drive. This process is essential as it’s not possible to encrypt the internal drive directly with cryptsetup and configure the partition layout and bootloader (GRUB) while the system is running.

The instructions below assume that you have already installed the Asahi ALARM base image and are currently booted into Arch Linux.

Download the Asahi Linux Base Image: Download the Asahi Linux base image from https://asahi-alarm.org/asahi-base.zip. The base image is a zip file containing the root image and EFI files. Extract the zip file to a convenient location and note the root.img file.

   pacman -S unzip
   curl -o asahi-base.zip https://asahi-alarm.org/asahi-base.zip
   unzip asahi-base.zip

Format the USB Drive: Format a USB drive with a minimum capacity of 32GB. Create two partitions:
- Partition 1: A FAT32 partition, named efi, with a size of at least 512MB. This partition will serve as the EFI System Partition (ESP) and must be formatted as FAT32 to be recognized by the UEFI firmware.
- Partition 2: An ext4 partition, named rootfs, utilizing the remaining space on the USB drive. You do not need to perform any formatting during the copy process, as dd will handle the formatting of this partition when copying the root image.

Create the partitions using fdisk:

   sudo fdisk /dev/sdX  # Replace /dev/sdX with your USB drive identifier. Use `lsblk` to confirm.

Within fdisk:

* Type `g` to create a new GPT partition table (recommended for modern systems).
* Type `n` to create a new partition.
* Accept the defaults for the first sector.
* Set the partition size to `+512M`, which will create a 512MB partition.
* Type `t` to change the partition type.
* Type `1` to set the partition type to EFI System Partition (ESP).
* Type `n` to create a new partition.
* Accept the defaults for the first and last sector, which will be the remaining disk space.
* Type `w` to write the changes to the disk.

You should now see two partitions on the USB drive if you run lsblk or fdisk -l /dev/sdX.

Next, format the first partition as FAT32 and the second as ext4:

   sudo mkfs.vfat -F32 /dev/sdX1
   sudo mkfs.ext4 /dev/sdX2

Copy Root Image to USB: Copy the root.img (likely located in asahi-base/root.img) to the rootfs partition ( partition 2) of the USB drive. It is crucial to verify the device identifier using fdisk -l before proceeding to avoid potential data loss.

   mount /dev/sdX2 /mnt
   losetup -f --show asahi-base/root.img 
   mkdir /tmp/root-img
   mount /dev/loop0 /tmp/root-img/
   rsync -Aavx /tmp/root-img/ /mnt/

The rsync -Aavx /tmp/root-img/ /mnt/ command synchronizes the files from the /tmp/root-img/ directory to the mounted /mnt directory. Let’s break this down:

* `rsync`: This is a versatile file synchronization utility.
* `-A`:  This option enables archive mode, which preserves file attributes like timestamps and permissions. This is
  essential to maintain the integrity of the Asahi Linux root filesystem.
* `-a`: This option is shorthand for archive mode, combining several other options to ensure a complete and correct
  copy.
* `-v`: This option makes the command verbose, displaying the files being transferred.
* `x`: This option enables compression, speeding up the transfer over slower networks.

Copy EFI Files: Copy the EFI files from the Asahi base image to the efi partition of the USB drive.

   sudo mkdir -p /mnt/boot/efi
   sudo mount /dev/sdX1 /mnt/boot/efi
   sudo cp -r asahi-base/efi /mnt

This command copies the entire asahi-base/efi directory to the /mnt/boot/efi directory on the USB drive. The -r option ensures that all files and subdirectories within the asahi-base/efi directory are copied recursively.

Update GRUB and kernel images: Update the GRUB configuration to be able to boot from the USB drive.

   genfstab -U /mnt > /mnt/etc/fstab
   arch-chroot /mnt

This sequence first generates an /etc/fstab file, which describes how partitions are mounted, followed by a chroot into the Asahi Linux environment.

Inside the chroot environment, update the GRUB and kernel configuration to boot from the USB drive:

   mkinitcpio -P
   update-grub

mkinitcpio -P creates a new initramfs image, which is a minimal filesystem used during system boot. This ensures the system has the necessary drivers to access the root filesystem. update-grub then generates a new GRUB configuration file based on the current system state, making it ready to boot from the USB drive.

Exit and reboot the system.

5. Booting from the External USB Drive

This section details the process of booting a Asahi Linux from an external USB drive. This procedure assumes you have successfully created a bootable USB drive and are ready to initiate the boot process. It also provides troubleshooting steps for scenarios where the boot process encounters issues.

Interrupt U-Boot: Upon reaching the U-Boot command prompt, press any key to interrupt the initial boot sequence. U-Boot typically displays a prompt indicating that it is awaiting user input. Pressing a key, such as the spacebar or ‘Enter’ will exit the U-Boot environment and return you to the command line.
Scan Boot Devices and List Them: Utilize the bootflow scan command to scan available boot devices. The bootflow command is a versatile tool for managing the boot process. Execute the following command to scan and list the detected devices:

   bootflow scan

The output of this command will display a list of detected devices. Carefully examine the list for your external USB drive. The output will include device names, UUIDs (Universally Unique Identifiers), and other relevant information. This command helps U-Boot identify potential bootable devices.

Select the External Boot Device: Based on the output of the bootflow scan command, select the correct external boot device. If the USB drive is not listed, it indicates a potential problem with the partitioning scheme of the USB drive. Verify the partitioning is correctly formatted (e.g., FAT32 or EXT4) and that the bootloader is properly installed on the appropriate partition. Incorrect partitioning will prevent U-Boot from recognizing the drive.
Initiate Boot: After selecting the correct device, use the bootflow boot command to initiate the boot process:

   bootflow select [<num|name>]
   bootflow boot

This command instructs U-Boot to boot the operating system from the selected device. The <num|name> placeholder represents the device number or name identified during the scan.

Troubleshooting: Initial RAMFS Issues: If the boot process becomes stuck in the initial RAM filesystem ( initramfs) environment, there may be an issue with the mounting of the root filesystem. This can often be resolved by manually mounting the root filesystem.
- Re-insert the Drive: Ensure the USB drive is securely connected to the target device. A loose connection can cause detection issues.
- Verify Device Identification: Use the blkid command to identify the USB drive based on its UUID:
```
  blkid
```
The output will list all block devices and their associated UUIDs. Locate the entry corresponding to your USB drive and note its UUID. For example:
```
  /dev/disk/by-uuid/a1b2c3d4-e5f6-7890-1234-567890abcdef
```
- Manually Mount the Root Filesystem: Use the mount command to create a mount point and then mount the root filesystem. Replace <uuid> with the actual UUID you obtained from the blkid command:
```
  mount /dev/disk/by-uuid/<uuid> /new_root
```
For example:
```
  mount /dev/disk/by-uuid/a1b2c3d4-e5f6-7890-1234-567890abcdef /new_root
```
- Exit the Emergency Shell: After successfully mounting the root filesystem, exit the emergency shell using the command:
```
  exit
```
- Resume Normal Boot: The normal boot process should now continue. This may take a few seconds as the system initializes the root filesystem. You should eventually see the login TTY prompt.

6. Partitioning the Internal Drive

This section details the critical step of partitioning your internal drive to prepare it for Asahi Linux installation. Precise partitioning is essential for optimal system performance and stability. Incorrect partitioning can lead to data loss, so meticulous attention to detail is paramount.

Identify the Internal Drive: Before commencing any partitioning operations, accurately identify the internal drive you intend to install Asahi Linux on. Use the fdisk -l command to list all detected drives and their partitions. Carefully examine the output to pinpoint the correct drive, typically identified as /dev/nvme0n1, /dev/sda, or similar. Verify the drive’s device identifier meticulously – double-check the size and model to eliminate any ambiguity. Proceeding with the wrong drive will irreparably damage your system.

   fdisk -l

Expected Output: The output will present a list of drives and partitions. The relevant device identifier will be listed alongside the drive’s name and size (e.g., /dev/nvme0n1).

Launch cfdisk: Once you’ve identified the correct drive, launch the cfdisk utility. cfdisk is a command-line partitioner that provides a more intuitive interface than fdisk for creating and managing partitions. Execute the following command, replacing /dev/nvme0n1 with the actual device identifier of your internal drive:

   cfdisk /dev/nvme0n1

Delete Existing Asahi Linux Partition: Within cfdisk, locate and carefully delete the existing root partition that belongs to the Asahi Linux installation. It is absolutely crucial to delete only the root partition specifically designated for Asahi Linux. Do not delete the EFI partition, any macOS partitions, or any other partitions on the drive. Incorrectly deleting partitions can render your system unbootable.
Create New Partitions: Following the deletion of the existing Asahi Linux partitions, create the necessary new partitions according to the recommended partitioning scheme. Specifically, you’ll need to establish a new boot partition and a root partition. To utilize the remaining available space for the root partition, utilize the 100%FREE option when specifying the root partition’s size. This will automatically allocate all remaining space to the root partition.
Fix Partition Order in the GPT Table: After creating the new partitions, it’s vital to maintain the correct order within the GPT (GUID Partition Table) to ensure proper functionality. The GPT dictates the order in which partitions are accessed, and deviating from the established order can lead to boot issues. Because most Linux disk management tools append partitions to the end of the GPT, it can lead to an incorrect order. To correct this, utilize the expert mode within fdisk. Especially some Apple tools have issues with a non-standard partition order.
- Launch fdisk: fdisk /dev/nvme0n1
- Enter Expert Mode: Type x and press Enter.
- Fix Partition Order: Type f and press Enter. This option allows you to adjust the partition order within the GPT.
- Return to Main Menu: Type r and press Enter.
- Exit: Type w and press Enter. This writes the changes to the GPT partition table. Be extremely cautious when using the w command, as it permanently alters the partition layout.
Format Partitions: Finally, format the newly created partitions with the appropriate filesystems. This step prepares the partitions for data storage and file system operations.
- Format the Root Partition:
```
mkfs.ext4 /dev/nvme0n1p3
```
  Purpose: mkfs.ext4 creates an ext4 filesystem on the designated partition.
- Format the LUKS Encrypted Partition:
```
cryptsetup luksFormat /dev/nvme0n1p4
```
  Purpose: cryptsetup luksFormat formats the LUKS encrypted partition, setting up the necessary structure for encrypted storage. You will be prompted to enter a passphrase for the LUKS volume. Choose a strong and memorable passphrase and securely store it.

7. Installing Asahi Linux on the Encrypted Drive

This section details the process of installing Asahi Linux onto your encrypted NVMe drive. It assumes you have successfully prepared the drive, created the LUKS container, and downloaded the necessary Asahi Linux images. Accuracy and meticulous execution are critical during this stage.

Unlock the LUKS Container: To access the decrypted volume, unlock the LUKS container using cryptsetup. This command establishes the necessary cryptographic keys for secure access. It opens the LUKS container residing at /dev/nvme0n1p4 and assigns it the device name cryptlvm. This allows subsequent operations to access the decrypted volume.

   cryptsetup open /dev/nvme0n1p4 cryptlvm

Mount Partitions: Mounting the required partitions is a critical step. This section mounts the newly formatted partitions within the unlocked LUKS container as outlined in the partitioning scheme. The following commands map the decrypted volume (/dev/mapper/cryptlvm) to the mount point /mnt. The nvme0n1p2 partition is mounted to /mnt/boot, which is essential for the system’s bootloader and kernel. The nvme0n1p3 partition, formatted as FAT32, is mounted to /mnt/boot/efi, which is required for Apple Silicon boot support.

   mount /dev/mapper/cryptlvm /mnt
   mount /dev/nvme0n1p2 /mnt/boot
   mount /dev/nvme0n1p3 /mnt/boot/efi

Copy Root Filesystem: This step transfers the root filesystem image to the mounted partition, preserving file permissions and timestamps for a consistent system setup.

   losetup -f --show root.img
   rsync -avxHAXF /dev/loop0/ /mnt/
   umount /dev/loop0

Let’s examine each command in detail:

* `losetup -f --show root.img` associates the `root.img` file with a loop device. The `-f` option forces the
  allocation of a free loop device, and `--show` displays the assigned device name.
* `rsync -avxHAXF /dev/loop0/ /mnt/` copies the contents of the loop device to the `/mnt` directory. The `-a` option
  specifies archive mode, which preserves permissions, ownership, timestamps, and symbolic links. The `-v` option
  increases verbosity, `-x` prevents copying across filesystems, `-H` preserves hard links, and `-A` preserves
  ACLs (Access Control Lists), and `-F` removes duplicate symbolic links.
* `umount /dev/loop0` unmounts the loop device, freeing the resources.

Configure fstab: An fstab file is crucial for defining how the system’s filesystems are mounted at boot. Generating this file ensures proper system initialization. genfstab generates an fstab file for the given filesystem. The -U option tells genfstab to use UUIDs instead of device names for increased reliability.

   genfstab -U /mnt >> /mnt/etc/fstab

Chroot into the new root: Execute the arch-chroot utility, changing the root directory to /mnt, effectively placing you inside the Asahi Linux system for further configuration.

   arch-chroot /mnt

System and Bootloader Configuration: Within the chrooted environment, these steps finalize the core system settings like GRUB configuration and kernel images. The lvm2 package is required for the LVM2 volume manager and provides the necessary kernel modules for system decryption at boot.

   pacman -S lvm2

The GRUB bootloader configuration must be updated to reflect the new system configuration. This primarily involves the cryptdevice setup for the root partition. The update-grub command updates the GRUB configuration on the /boot partition. Additionally, the kernel image must be updated to include the lvm2 module. This is achieved by editing the /etc/mkinitcpio.conf file and adding the encrypt and lvm2 module to the HOOKS variable.

Edit the /etc/default/grub file and add the following line to the GRUB_CMDLINE_LINUX_DEFAULT variable:

   GRUB_CMDLINE_LINUX_DEFAULT="cryptdevice=UUID=a1b2c3d4-e5f6-7890-1234-567890abcdef:cryptlvm root=/dev/mapper/cryptgroup-root"

Edit the /etc/mkinitcpio.conf file and add the encrypt and lvm2 module:

   HOOKS=(base asahi udev autodetect microcode modconf kms keyboard keymap consolefont block encrypt lvm2 filesystems fsck)

Rebuild the GRUB configuration and install the new kernel modules.

   update-grub
   mkinitcpio -P

Exit Arch-Chroot and Reboot: The new system is now ready to boot. Exit the chrooted environment and reboot the system. You will be prompted to enter the password to unlock the LUKS container.

8. Post-Installation Tasks and Notes

Following the installation of the Asahi ALARM distribution, several post-installation tasks are necessary to optimize the system and ensure a stable and fully functional environment. This section outlines these critical steps, intended for intermediate to advanced Linux users comfortable with command-line operations.

Network Connectivity: The Asahi ALARM distribution utilizes Network Manager for network configuration. To establish an internet connection, execute the following command, replacing <SSID> with the name of your Wi-Fi network:

   nmcli device wifi connect <SSID> --ask

This command will prompt you for the password for the specified Wi-Fi network. Network Manager will automatically configure the connection. You can verify the connection status with nmcli device show <interface_name>, where <interface_name> is the name of the active Wi-Fi interface (e.g., wlan0).

User Account Management: The installation process automatically enables both the root account and a standard user account named alarm. While the root account is initially available, it is strongly recommended against using it for day-to-day system administration. For security reasons and to prevent accidental system damage, immediately lock the root account with passwd root and then, if desired, remove the alarm user and create a custom user account. To install sudo, which allows users to execute commands with root privileges without needing to type the root password, run:

   pacman -S sudo

This adds the sudo package to the system, granting your user account administrative privileges. After installing sudo, you’ll need to add your user account to the sudo group. This is typically done by adding your user to the wheel group (the equivalent of sudo on Arch Linux). The method to do this varies depending on the desktop environment. Most commonly it’s done with:

   gpasswd -a $USER wheel

This adds your current user to the wheel group. You’ll need to log out and log back in for the changes to take effect.

Built-in Audio Configuration: The base Asahi ALARM image does not include user-space audio tools by default. To enable and configure audio support, install the asahi-audio package:

   pacman -S asahi-audio

The asahi-audio package provides essential tools for interacting with the Mac’s audio hardware, managing speaker volume, and configuring the microphone. After installation, you can use the asahi-audio command-line tools or integrate with standard desktop audio settings for complete control.

General System Configuration for Arch Linux: The Asahi ALARM distribution is based on Arch Linux. Therefore, familiarity with Arch Linux best practices and configuration is highly beneficial. Refer to the comprehensive Arch Linux Wiki for detailed information on system configuration, package management, and troubleshooting. Specifically, explore sections related to systemd, pacman, and the general principles of Arch Linux administration. Understanding these concepts will greatly facilitate ongoing system maintenance and customization.