From 2d936e664b7afd58f7926bc8cc95b10f56702617 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Go=C5=82a=C5=9B?= Date: Fri, 4 Apr 2025 17:33:16 +0200 Subject: [PATCH 1/5] install_aem: Remove lack of UEFI support disclaimer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filip Gołaś --- docs/user-docs/install_aem.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/user-docs/install_aem.md b/docs/user-docs/install_aem.md index 841f227..6d18870 100644 --- a/docs/user-docs/install_aem.md +++ b/docs/user-docs/install_aem.md @@ -5,11 +5,6 @@ This document shows how to install Anti Evil Maid from packages produced by If you wish to build the components yourself, please refer to documentation for developers instead. -## Disclaimer - -As of now, only legacy boot is supported. These instructions -WON'T WORK under UEFI. You have been warned. - ## Installation To install, you have to first add a new repository and import a public part of From 539988c50ce17047045f7725edb49f097bc471e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Go=C5=82a=C5=9B?= Date: Fri, 4 Apr 2025 17:43:15 +0200 Subject: [PATCH 2/5] install_aem: Update instructions for Legacy & UEFI support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filip Gołaś --- docs/user-docs/install_aem.md | 75 ++++++++++++++++++++++++++++++----- 1 file changed, 64 insertions(+), 11 deletions(-) diff --git a/docs/user-docs/install_aem.md b/docs/user-docs/install_aem.md index 6d18870..7d038a2 100644 --- a/docs/user-docs/install_aem.md +++ b/docs/user-docs/install_aem.md @@ -42,11 +42,13 @@ potentially in newer versions, those must be temporarily disabled during invocation of `qubes-dom0-update`, as shown in the following commands. If any of the packages that are part of AEM are updated in standard repos, you will have to choose between using new versions or having working AEM, at least until -new AEM release is published or the code gets merged upstream. If you decide to +new AEM release is published, or the code gets merged upstream. If you decide to restore AEM after an update broke it, you will have to repeat the installation of overwritten package with `--action=reinstall` added to `qubes-dom0-update`, if it wasn’t present before. +#### Qubes repository dependencies + Start by installing prerequisite packages. Those are not part of newly added repository, but `qubes-dom0-current-testing`: @@ -60,18 +62,35 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing \ tpm-tools ``` +#### AEM repository dependencies + Next set of new packages comes from AEM repository, to avoid conflicts other repositories are disabled for this call: ```bash sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem \ - grub2-tools-extra \ + grub2-tools-extra +``` + +##### AMD systems dependencies + +This package is only needed on AMD systems: + +```bash +sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem \ secure-kernel-loader ``` -This is followed by reinstalling additional packages. A reinstall is required +#### AEM repository dependencies to reinstall + +This is followed by reinstalling additional packages. A reinstallation is required because currently installed version is equal (or it may be higher in the future) -than those provided by AEM. +than those provided by AEM. A couple of GRUB packages differ slightly +depending on whether you use a legacy or UEFI BIOS: + +##### Legacy Systems + +If your system has a legacy BIOS, reinstall these packages: ```bash sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall \ @@ -88,18 +107,45 @@ sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall \ grub2-tools-minimal ``` -### Updating GRUB +###### Updating GRUB on legacy systems + +Booting on legacy systems requires manual installation of GRUB2 to the MBR +of disk where Qubes OS is stored. In the example below it is `/dev/sda`, +yours may be different. -Booting on legacy systems (AEM currently doesn’t support UEFI) requires manual -installation of GRUB2 to the MBR of disk where Qubes OS is stored. In the -example below it is `/dev/sda`, yours may be different. Remember that GRUB2 -must be installed on disk and not on partition, so don’t use `sda1`, `nvme0n1p1` -etc. +To check on which partition is your OS installed run: + +```bash +df --output=source / +``` + +Remember that GRUB2 must be installed on disk and +not on partition, so don’t use `sda1`, `nvme0n1p1` etc. This step should be +skipped on UEFI systems. ```bash sudo grub2-install /dev/sda ``` +##### UEFI Systems + +If your system has an UEFI BIOS, install these packages instead: + +```bash +sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall \ + python3-xen \ + xen \ + xen-hypervisor \ + xen-libs \ + xen-licenses \ + xen-runtime \ + grub2-common \ + grub2-efi-x64 \ + grub2-efi-x64-modules \ + grub2-tools \ + grub2-tools-minimal +``` + ### Installing main AEM package Finally, `anti-evil-maid` package may be installed: @@ -134,7 +180,14 @@ again. Now all that's left is proper installation of AEM. There are different options, refer to `anti-evil-maid-install -h` for examples. In the simplest case, AEM is installed on boot partition (not disk, i.e. `sda1` instead of `sda` etc.) of -Qubes OS. This can be done with a simple command: +Qubes OS. Run this command to find out where your boot partition is installed: + +```bash +df --output=source /boot +``` + +Assuming that your boot partition is installed on `/dev/sda1`, the +installation can be done with a simple command: ```bash sudo anti-evil-maid-install /dev/sda1 From 95eb81f49b7cf5727e68ca8fd400a0e95ae03e99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Go=C5=82a=C5=9B?= Date: Fri, 9 May 2025 17:00:33 +0200 Subject: [PATCH 3/5] install_aem.md: Add how to find out root disk with LVM+LUKS MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filip Gołaś --- docs/user-docs/install_aem.md | 53 ++++++++++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/user-docs/install_aem.md b/docs/user-docs/install_aem.md index 7d038a2..8d1d791 100644 --- a/docs/user-docs/install_aem.md +++ b/docs/user-docs/install_aem.md @@ -113,12 +113,63 @@ Booting on legacy systems requires manual installation of GRUB2 to the MBR of disk where Qubes OS is stored. In the example below it is `/dev/sda`, yours may be different. -To check on which partition is your OS installed run: +To check on which partition is your OS installed, if the disk is not encrypted, +run: ```bash df --output=source / ``` +If your disk is encrypted, then the command above will print a filename +like `/dev/mapper/...`. This is an LVM Logical Volume and finding out the +physical disk on which the root partition resides takes a couple steps. +If you are sure where the root partition is located, you can skip the steps to +find it out. + +1. Get the Logical Volume (LV) file: + + ```bash + df --output=source / + ``` + + Example LV file: `/dev/mapper/qubes_dom0-root` + +1. Map the Logical Volume (LV) to a Volume Group (VG): + + ```bash + sudo lvs /dev/mapper/qubes_dom0-root --noheadings -o vg_name + ``` + + Example VG name: `qubes_dom0` + +1. Map the Volume Group to a Physical Volume (PV): + + ```bash + sudo vgs --noheadings -o pv_name qubes_dom0 + ``` + + Example PV file: `/dev/mapper/luks-12345678-1234-1234-1234-123456789abc` (GUID) + +1. Find the PV name in `lsblk` output and check on which device it is +located. + + ```bash + lsblk -o NAME + ``` + + Example output: + + ```text + sda + ├─sda1 + ├─sda2 + └─sda3 + └─luks-12345678-1234-1234-1234-123456789abc + ``` + + The drive on which the root partition is located in this example is + therefore `/dev/sda`. + Remember that GRUB2 must be installed on disk and not on partition, so don’t use `sda1`, `nvme0n1p1` etc. This step should be skipped on UEFI systems. From 7b45019057df402ba572ea222644dfab055b7cbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Go=C5=82a=C5=9B?= Date: Thu, 22 May 2025 07:38:58 +0200 Subject: [PATCH 4/5] install_aem.md: Installing dependencies: Describe using different --action MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Filip Gołaś --- docs/user-docs/install_aem.md | 46 +++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/user-docs/install_aem.md b/docs/user-docs/install_aem.md index 8d1d791..a76b2b1 100644 --- a/docs/user-docs/install_aem.md +++ b/docs/user-docs/install_aem.md @@ -107,6 +107,29 @@ sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall \ grub2-tools-minimal ``` +Depending on the set of currently installed packages and their versions +the commands required to install the dependencies vary. + +`--action=reinstall` will make sure that the existing packages will be replaced +with the custom versions provided by the AEM repo. That will only happen if +the version number of the installed package matches exactly the version in the +repository. + +If any package returns `No match for argument`, then it might need to be +installed, not reinstalled. To make sure that missing packages are installed +re-run the exact command with `--action=install` instead. +`--action=install` won't install packages if the are already installed, even +if the repository contains packages with higher version number. + +If a package was skipped during both `--action=reinstall` and `--action=install` +it might need to be updated instead using `--action=update`. This will happen +if the version number in the repository is higher than the currently installed +one. `reinstall` won't work because the versions don't match and `install` won't +work because the package is already installed. + +Make sure that all of the packages listed above are installed int the system +and come from the AEM repository. + ###### Updating GRUB on legacy systems Booting on legacy systems requires manual installation of GRUB2 to the MBR @@ -197,6 +220,29 @@ sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall \ grub2-tools-minimal ``` +Depending on the set of currently installed packages and their versions +the commands required to install the dependencies vary. + +`--action=reinstall` will make sure that the existing packages will be replaced +with the custom versions provided by the AEM repo. That will only happen if +the version number of the installed package matches exactly the version in the +repository. + +If any package returns `No match for argument`, then it might need to be +installed, not reinstalled. To make sure that missing packages are installed +re-run the exact command with `--action=install` instead. +`--action=install` won't install packages if the are already installed, even +if the repository contains packages with higher version number. + +If a package was skipped during both `--action=reinstall` and `--action=install` +it might need to be updated instead using `--action=update`. This will happen +if the version number in the repository is higher than the currently installed +one. `reinstall` won't work because the versions don't match and `install` won't +work because the package is already installed. + +Make sure that all of the packages listed above are installed int the system +and come from the AEM repository. + ### Installing main AEM package Finally, `anti-evil-maid` package may be installed: From b324773f4ca6756d594e6ddd2a20e6153d4284e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Filip=20Go=C5=82a=C5=9B?= Date: Fri, 6 Jun 2025 12:17:24 +0200 Subject: [PATCH 5/5] user-docs/install_aem.md: Remove unencrypted drive instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Instructions for reinstalling grub2 on Legacy systems. AEM without encryption is pretty much useless anyway. Signed-off-by: Filip Gołaś --- docs/user-docs/install_aem.md | 21 +++++---------------- 1 file changed, 5 insertions(+), 16 deletions(-) diff --git a/docs/user-docs/install_aem.md b/docs/user-docs/install_aem.md index a76b2b1..9585518 100644 --- a/docs/user-docs/install_aem.md +++ b/docs/user-docs/install_aem.md @@ -127,27 +127,16 @@ if the version number in the repository is higher than the currently installed one. `reinstall` won't work because the versions don't match and `install` won't work because the package is already installed. -Make sure that all of the packages listed above are installed int the system +Make sure that all of the packages listed above are installed in the system and come from the AEM repository. ###### Updating GRUB on legacy systems Booting on legacy systems requires manual installation of GRUB2 to the MBR -of disk where Qubes OS is stored. In the example below it is `/dev/sda`, -yours may be different. +of disk where Qubes OS is stored. If you are sure where the root partition +is located, you can skip the following steps explaining how to find it out. -To check on which partition is your OS installed, if the disk is not encrypted, -run: - -```bash -df --output=source / -``` - -If your disk is encrypted, then the command above will print a filename -like `/dev/mapper/...`. This is an LVM Logical Volume and finding out the -physical disk on which the root partition resides takes a couple steps. -If you are sure where the root partition is located, you can skip the steps to -find it out. +To check on which drive is your OS installed, run: 1. Get the Logical Volume (LV) file: @@ -240,7 +229,7 @@ if the version number in the repository is higher than the currently installed one. `reinstall` won't work because the versions don't match and `install` won't work because the package is already installed. -Make sure that all of the packages listed above are installed int the system +Make sure that all of the packages listed above are installed in the system and come from the AEM repository. ### Installing main AEM package