From ecc0bab4a7448a282b3c60595927bb5cfe4067e6 Mon Sep 17 00:00:00 2001 From: Hector Martin Date: Aug 19 2024 15:03:56 +0000 Subject: [PATCH 1/2] Add Troubleshooting page --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9598468..e7d4788 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -1,4 +1,5 @@ * xref:installation.adoc[Installation] +* xref:troubleshooting.adoc[Troubleshooting] * xref:deviations.adoc[Deviations] * xref:how-its-made.adoc[How it's made] * xref:talks.adoc[Conference talks] diff --git a/modules/ROOT/pages/faq.adoc b/modules/ROOT/pages/faq.adoc index 1544cb3..549e98f 100644 --- a/modules/ROOT/pages/faq.adoc +++ b/modules/ROOT/pages/faq.adoc @@ -59,11 +59,7 @@ Sometimes there are options other than running x86-64 software, such as native t === How do I access the GRUB menu? -Server and Minimal installs should show the GRUB menu by default. For desktop installs, you have to press Escape at the right time to enter the GRUB menu. - -When the system boots, you will see the display cycle through m1n1 (Asahi Linux or Fedora logos) and U-Boot (text screen with U-Boot logo on the top right). The U-Boot screen will show a brief countdown. Press Escape immediately after the countdown reaches 0 to enter the GRUB boot menu. - -From there, you can choose an older kernel version (e.g. to recover from a failed kernel install), or change the boot options (e.g. to reset your password or recover from other system issues). +See xref:troubleshooting.adoc#entering-grub[Entering the GRUB boot menu]. === How do I access protected content in browsers (Widevine DRM) [[widevine]] diff --git a/modules/ROOT/pages/index.adoc b/modules/ROOT/pages/index.adoc index 6473114..25e6354 100644 --- a/modules/ROOT/pages/index.adoc +++ b/modules/ROOT/pages/index.adoc @@ -19,6 +19,7 @@ This guide covers those areas where {variant-name} differs from a standard Fedor * xref:installation.adoc[OS installation] * xref:faq.adoc[FAQ] +* xref:troubleshooting.adoc[Troubleshooting steps] [[known-bugs]] == Known bugs diff --git a/modules/ROOT/pages/troubleshooting.adoc b/modules/ROOT/pages/troubleshooting.adoc new file mode 100644 index 0000000..b702282 --- /dev/null +++ b/modules/ROOT/pages/troubleshooting.adoc @@ -0,0 +1,213 @@ += Troubleshooting + +If your Mac is having trouble booting, here are some steps you can take to identify the problem and resolve it. + +First, identify what happens when you power on the computer and jump to the appropriate section: + +- The computer boots into macOS: <> +- The boot process fails in the U-Boot console screen with an error message mentioning a kernel or initramfs: <> +- The boot process gets stuck in the U-Boot console: <> +- The boot process gets stuck in the m1n1 console, ending with `Running proxy...`: <> +- The computer shows the Apple logo and then goes blank (laptops, iMacs) or there is no display output (desktops) but it does not reboot: <> +- The computer shows the Apple logo and a progress bar (laptops, iMacs) or no display output (desktops) and then reboots repeatedly, finally showing a recovery screen: <> +- The computer shows an exclamation point icon and a support URL (laptops, iMacs) or the power LED blinks in an SOS pattern (desktops): <> + +== Changing the startup operating system [[boot-picker]] + +You can select which OS boots, either temporarily or permanently, by using the system's built in Boot Picker. To do this, with the machine fully powered down: + +- Press and hold the power button +- Keep holding until the screen reads "Entering startup options" (laptops, iMacs) or the power LED dims slightly (desktops), then release. + +This will display the Boot Picker, where you can select the next operating system to boot. By default, the selection will be temporary. To make your choice permanent for all subsequent boots, click on the desired boot option while holding down the Option key on the keyboard. + +You can also choose the rightmost "Options" icon to enter recoveryOS, which you can use to perform recovery operations. You may be prompted for your macOS login credentials, depending on the security state of your machine. Once at the main recoveryOS options screen, you can open a Terminal window by pressing Shift-Command-T. + +== Entering the GRUB boot menu [[entering-grub]] + +If there is a problem during a kernel package upgrade or some other issue that prevents the kernel from booting properly, you may need to enter the GRUB menu to select a different kernel or alter boot options. + +Server and Minimal installs should show the GRUB menu by default. For desktop installs, you have to press Escape at the right time to enter the GRUB menu. When the system boots, you will see the display cycle through m1n1 (Asahi Linux or Fedora logos) and U-Boot (text screen with U-Boot logo on the top right). The U-Boot screen will show a brief countdown. Press Escape immediately *after* the countdown reaches 0 to enter the GRUB boot menu. + +From there, you can choose an older kernel version (e.g. to recover from a failed kernel install), or change the boot options (e.g. to reset your password or recover from other system issues). + +== Troubleshooting U-Boot issues [[uboot-troubleshoot]] + +U-Boot can have trouble with certain kinds of USB devices. If you are seeing strange behavior or logs from U-Boot, try disconnecting all USB devices (except a single keyboard, for desktop machines). + +If you are having trouble getting an external keyboard to work in the U-Boot or GRUB menus, you may want to try using another USB port (e.g. Type C with an adapter instead of Type A) or a different keyboard. As U-Boot can only support a single keyboard, make sure no other USB devices that emulate a keyboard are connected. This includes some USB mice as well as certain USB tokens, barcode readers, etc. (YubiKeys should already be excluded and ignored in U-Boot). + +== Troubleshooting m1n1 stage 2 issues [[stage2-troubleshoot]] + +If the m1n1 console is displayed and shows a `Running proxy...` message, this typically means that m1n1 stage 1 had trouble loading m1n1 stage 2. + +If this occurred after a system update, it is possible that the new updated stage 2 binary was not installed correctly. You can boot into macOS or recoveryOS (see the <> section) and perform the following steps to revert to the previous version of m1n1 stage 2 and U-Boot. + +. Open a Terminal +. Type `diskutil list | grep EFI` to see the available EFI partitions +. The EFI partition will be named something similar to `EFI - FEDOR`. Make note of the identifier on the right, e.g. `disk0sX`. +. Type `sudo diskutil mount disk0sX` with the identifier you obtained above to mount the partition. +. Navigate to the mountpoint with `cd "/Volumes/EFI - FEDOR"` (replacing `EFI - FEDOR` with your volume name). +. Navigate to the `m1n1` subdirectory: `cd m1n1`. +. List the files with `ls`. There should be a `boot.bin` file and a `boot.bin.old` file. +. Rename the current file to an inactive name: `mv boot.bin boot.bin.new`. +. Rename the old file to the active name: `mv boot.bin.old boot.bin`. + +If you are running under macOS, you may also perform the file management steps with Finder. After mounting the partition with `diskutil`, it will appear in the Finder sidebar. + +After reverting `m1n1.bin`, boot back into {variant-name} to test the reverted version of m1n1 stage 2 and U-Boot. + +Note that reverting the m1n1 stage 2 binary to the previous version is not guaranteed to work correctly, as sometimes there are incompatible device tree changes that accompany kernel version updates. You may find that some hardware does not work properly after the reversion. After a successful boot into Linux, you should run `sudo update-m1n1` to update to the current version, and reboot again. + +== Upgrading or repairing m1n1 stage 1 [[stage1-repair]] + +Sometimes, the system's Boot Policy for {variant-name} might become corrupted. This sometimes occurs after macOS upgrades (due to bugs in Apple's upgrade process). If this happens, attempting to boot that operating system will instead immediately reboot. If that OS is the default boot OS, the computer will reboot repeatedly until it triggers an OS recovery screen. If this happens, you need to restore m1n1 stage 1 and the associated Boot Policy. + +It is also possible for a system firmware upgrade to trigger an incompatibility in m1n1 stage 1, requiring an update. This can happen if you update to macOS Sonoma 14.5 or later, with a m1n1 stage 1 older than 1.4.13 (released May 2024), due to a bug in those older m1n1 versions. To resolve this, update m1n1 stage 1. + +The process for both of the above situations is the same. First, follow the steps in <> to boot into recoveryOS (preferred) or macOS, and open a Terminal. Ensure you are connected to the internet, and then run the {variant-name} installer again, using the instructions in the xref:installation.adoc[Installation] page (or the steps available on https://asahilinux.org[asahilinux.org]). Once the installer starts, one of the available options should be to `Repair an incomplete installation` (`p`) or `Upgrade m1n1 on an existing OS` (`m`). Choose the appropriate option and follow the instructions to upgrade or reinstall m1n1 stage 1. + +== Recovering an unbootable machine [[machine-recovery]] + +If your machine is stuck displaying an exclamation mark icon (laptops and iMacs) or SOS LED blink pattern (desktops), you may need to perform a DFU Revive or Restore. To determine if this is necessary, first try to boot using both the current paired recoveryOS and the System recoveryOS. + +To boot using the current recoveryOS: + +- Fully power down the machine +- Press and hold the power button +- Keep holding until the screen reads "Entering startup options" (laptops, iMacs) or the power LED dims slightly (desktops), then release. + +To boot using the System RecoveryOS: + +- Fully power down the machine +- Quickly press, release, and then press and hold the power button (the whole action should take less than half a second) +- Keep holding until the screen reads "Entering startup options" (laptops, iMacs) or the power LED dims slightly (desktops), then release. + +If either of those processes succeeds and shows the Boot Picker, you can choose an alternate OS to boot or select the "Options" icon to boot recoveryOS and troubleshoot the issue or reinstall another OS from that environment. + +== Performing a DFU revive or restore [[dfu]] + +If your machine fails to boot or enter Startup Options, you may have to perform a DFU Revive or Restore. + +A DFU Revive will restore and update System Firmware and Recovery (SFR), while leaving operating systems and data intact. This may be able to resolve some issues, but is not guaranteed to work (e.g. a DFU Revive cannot recover a missing System Recovery partition, but it *can* reinstall recoveryOS into an existing but blank System Recovery partition with the appropriate subvolume). + +A DFU Restore will completely wipe all data on the internal storage and restore the machine to factory condition. It is also the only way to downgrade System Firmware to a prior version. This process can recover from any kind of corruption or problem with the internal NVMe storage, and even corruption of the internal NOR Flash storage and several other firmware components. Note that if you perform a DFU Restore, you will lose all data stored on the machine, and it will be returned to its factory condition. + +To perform a DFU Revive or Restore, you will need either another Mac running macOS, or a Fedora Linux machine (any hardware) with an available USB port. You will also need an appropriate USB cable to connect both machines together. + +=== Performing a DFU revive or restore using another Mac running macOS + +Follow https://support.apple.com/en-us/108900[Apple's documentation] to learn how to perform a restore using another Mac, using the macOS Finder or Apple Configurator. + +If you have trouble putting the machine into DFU mode, you may also wish to refer to the instructions below. + +=== Performing a DFU revive or restore using a machine running Fedora Linux [[dfu-fedora]] + +You can also boot Fedora Linux on another machine (Intel compatible or Apple Silicon both work), and then use `idevicerestore` to perform the DFU Revive or Restore process. + +If you have a spare x86-64 (Intel/AMD) machine that does not currently have Fedora installed, you can follow the steps in the <> to temporarily live boot Fedora from a USB stick and set up the environment to be able to perform the DFU Revive/Restore. Once the system is up and running, return to this section to continue the process. + +You will need a compatible USB cable. If your host machine has Type A ports, use a Type A to Type C cable. If your host machine has Type C ports, use a Type C to Type C cable. You may also use a Type A to Type C cable together with a female Type A to male Type C adapter. Your cable must support data transfer (USB 2.0 480Mbps is sufficient, though USB 3 cables also work). Thunderboot 3 cables will not work, nor will charge-only cables. + +To perform a DFU Revive using a second Fedora machine, follow these steps: + +. Ensure you are connected to the Internet. + - On Fedora Workstation, click on the top right menu bar icon to select a WiFi network (if not using wired Ethernet). + +. Open a Terminal. + - On Fedora Workstation, click on the top left menu icon, type 'terminal' and hit Enter. + +. Ensure you have at least 40GB of available disk space in the current working directory. If not, change to another directory that does or add additional storage as needed. + - If you have followed the below steps to perform a live boot and configure your environment, this is already the case. + +. Run the command `sudo dnf install -y idevicerestore usbmuxd` to install `idevicerestore`. + - If the output indicates that `usbmuxd` was also installed as a dependency (and was not already installed), run `sudo udevadm control --reload` to reload the udev rules. Fedora Workstation live images should already have `usbmuxd` installed. + +. Run the command `sudo dmesg -w` to show the live kernel log. + +. Connect the USB cable between your host machine and the target machine to be restored. The cable must be connected to a specific USB port on the target machine: + - For laptops, use the *leftmost* (rearmost) Type C port on the *left* side. + - For iMacs, facing the rear of the machine, use the *rightmost* Type C port (closest to the power connector). + - For Mac Mini machines, facing the rear of the machine, use the *leftmost* Type C port. + - For Mac Studio machines, facing the rear of the machine, use the *rightmost* Type C port. + - For Mac Pro desktop machines, facing the top of the machine, use the Type C port *farthest* from the power button. + - For Mac Pro rackmount machines, facing the front of the machine, use the Type C port *closest* to the power button. + ++ +If you are using a Type A to Type C cable, connect the Type C end to the target machine. The Type A end may be directly connected to the host machine, or to a Type C port via a Type A to Type C adapter. USB hubs may also be used on the host machine side (but not the target machine side). + +. Enter DFU mode. The process is different for desktops and laptops (you can pick one of two options for laptops; try both if you have trouble getting it to work). + - For desktops: + .. Start with the machine fully powered down. + .. Unplug the machine from the mains power and wait 30 seconds. + .. Press and hold down the power button. + .. While holding down the power button, connect mains power to the machine. + .. Continue holding down the power button and watch the kernel log. Look for a USB device log that mentions `Product: Apple Mobile Device (DFU Mode)`. + .. Once you see the log, release the power button. + - For laptops (method 1): + .. Start with laptop fully powered down. + .. Press and release the power button quickly. + .. *Immediately* press and hold the following keys: Left control, left option, right shift, and the power button. + .. Count down 10 seconds, then release everything except the power button. + .. Continue holding down the power button and watch the kernel log. Look for a USB device log that mentions `Product: Apple Mobile Device (DFU Mode)`. + .. Once you see the log, release the power button. + - For laptops (method 2): + .. Start with laptop powered *up* (make sure something is visible on the display). + .. Press and hold the following keys: Left control, left option, right shift, and the power button. + .. Wait until the screen turns off, then count down 5 additional seconds, then release everything except the power button. + .. Continue holding down the power button and watch the kernel log. Look for a USB device log that mentions `Product: Apple Mobile Device (DFU Mode)`. + .. Once you see the log, release the power button. + ++ +If you don't see the DFU device in the log, or the Product mentions "Recovery Mode" instead, something went wrong. Retry the steps again. +The display of the target machine will remain blank in DFU mode. + +. On your host machine, press Ctrl-C to stop the dmesg command. + +. Run the following command: `systemd-inhibit sudo -s TMPDIR=$PWD idevicerestore -l`. + +. When prompted, type '1' to select the latest available macOS/firmware version. + +During the Restore process, the target machine will display an Apple logo and a progress bar, while the host machine running `idevicerestore` will print out progress log information. Note that this process involves connecting to Apple's CDN and servers to download system firmware components and authenticate them for your specific machine. + +After the process completes successfully, the machine will reboot into the Recovery Assistant. Follow the prompts to select a macOS volume to recover, and enter your macOS authentication credentials. After this process succeeds, your machine will boot into the Boot Picker. From here, you can choose which OS to boot next. + +It is likely that any existing {variant-name} installations will become unbootable as a result of the Revive process. If attempting to boot a Linux install triggers a reboot or a Recovery screen, follow the steps in the <> section to reinstall m1n1 stage 1 and make the OS bootable again. + +If the DFU Revive fails, you will have to perform a DFU Restore. To do so, follow the above steps again, but add the `-e` option to the `idevicerestore` command: + +`systemd-inhibit sudo -s TMPDIR=$PWD idevicerestore -l -e` + +CAUTION: This will **irreversibly** wipe all data on the target machine. + +After a DFU Restore, your machine will be reset to its factory condition and boot into the macOS first-time setup wizard. + +=== Live booting Fedora Linux on an x86 (Intel/AMD) compatible machine to perform a DFU restore [[fedora-live-dfu]] + +You can use a USB disk to live-boot Fedora Workstation on any x86-64 machine and perform the DFU restore from that environment, without having to install to local disk. You will need a USB disk with at least **64GB** of capacity. + +NOTE: All existing data on the USB disk will be erased. + +To set up the USB disk, we recommend using xref:release-docs-home::preparing-boot-media.adoc#fedora_media_writer[Fedora Media Writer]. Follow the steps on that page to download it and write the image to your USB disk, and then boot it on your target machine. + +Once the system is booted, follow the following steps to open up a terminal: + +. On 'Welcome to Fedora' screen, click 'Not Now'. +. Click on the top right menu bar icon and connect to a WiFi network (if not using wired Ethernet). +. Click on the top left menu icon, type 'terminal' and hit enter. + +To perform the DFU Restore process, `idevicerestore` needs a large amount of temporary disk space. Since the live image runs from RAM, it does not have enough temporary space available. To create and use a temporary partition in the remaining free space on the USB disk, run the following commands one by one: + +``` +device=$(grep /run/initramfs/live /proc/mounts | awk '{ print $1 }' | sed 's/[0-9]*$//') +echo "size=40G" | sudo sfdisk -a $device +sudo partprobe $device +part=$(ls ${device}[0-9] | tail -n 1) +sudo mkfs.ext4 $part +sudo mkdir -p /mnt/tmp +sudo mount $part /mnt/tmp +sudo chmod 777 /mnt/tmp +cd /mnt/tmp +``` + +Next, continue with the steps in the <> section (you have already performed steps 1-3 and do not need to do them again). From 9c9c549af01270ea22c977318f43173be310d656 Mon Sep 17 00:00:00 2001 From: Hector Martin Date: Aug 19 2024 15:03:56 +0000 Subject: [PATCH 2/2] FAQ: Add safety section --- diff --git a/modules/ROOT/pages/faq.adoc b/modules/ROOT/pages/faq.adoc index 549e98f..c99931d 100644 --- a/modules/ROOT/pages/faq.adoc +++ b/modules/ROOT/pages/faq.adoc @@ -39,6 +39,20 @@ The Asahi Linux project website maintains a https://asahilinux.org/fedora/[landi For more detailed information on specific driver and kernel support, visit the https://github.com/AsahiLinux/docs/wiki[Asahi Linux wiki] and browse the Feature Support pages (linked at the top of the sidebar). +=== Is {variant-name} safe to install and use? + +We strive to make sure that our platform support packages and the installation process are completely safe and cannot cause any damage to your computer. In general, it is safe to install and use {variant-name} on any supported machine (the installer will refuse to work on unsupported machines). As with all Free Software, please be aware that {variant-name} is offered with no warranty. + +As a Linux distribution, {variant-name} gives users much more control over their computers than the stock macOS system does. This also means that there are fewer safeguards against dangerous operations. In general, Apple Silicon systems are very resilient against permanent hardware damage, so it is very unlikely that anything you do will cause any physcal, unrecoverable harm to your machine. However, these machines are less resilient against becoming unbootable than typical x86 machines, and this can happen if important boot partitions on disk are corrupted or destroyed. You should be careful if you are using partitioning or disk formatting tools on the internal NVMe storage device: + +- Never change, move, or format the first partition on disk (`/dev/nvme0n1p1`, identified as type `Apple Silicon boot` and label `iBootSystemContainer`). +- Never change, move, or format the last partition on disk (`/dev/nvme0n1pX` for the largest value of X, identified as type `Apple Silicon recovery` and label `RecoveryOSContainer`) +- If you make partitioning changes, ensure that the partition table remains sorted by disk offset. This can be achieved by using `sudo sfdisk -r /dev/nvme0n1`. + +If you do end up with trouble booting your machine after making changes to the disk, please see the xref:troubleshooting.adoc section for recovery and restore steps. Note that in the worst case this may involve a full factory reset and loss of all data (on both macOS and Linux partitions), so users are advised to have up-to-date backups before doing any disk management operations. + +In addition, you should avoid making any changes to the existing macOS container partition (usually `/dev/nvme0n1p2`, identified as type `Apple APFS` and typically label `Container` on stock systems). Changes to this partition may make macOS unbootable, which will make it difficult to perform system firmware upgrades or recover, upgrade, or reinstall any Linux installations. At this time, {variant-name} users are expected to have and maintain a working macOS installation, as the installation and bootloader upgrade process relies on the macOS admin user credentials to provision the bootloader. This requirement may be relaxed in the future, once we support system user management and firmware upgrades directly from Linux. + === Can I install to external storage? We currently do not have a supported process to install to external storage. The Apple Silicon platform in general cannot boot from external storage at all, so some components must always be installed to internal storage. It is possible to manually move the root filesystem to external storage, but there are limitations (e.g. sleep mode is not currently supported as it causes external disks to re-enumerate) and therefore this is left as an exercise for the advanced user.