Git-Mirrors/Qubes-Community-Content
1
0
Fork 0
mirror of https://github.com/Qubes-Community/Contents.git synced 2024-12-22 21:59:26 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #202 from techge/techge-building-archlinux

Browse Source 
Update arch building guide to be more concise
This commit is contained in:
Ivan 2022-08-18 16:34:43 +00:00 committed by GitHub
commit 75e446267e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 195 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

318
docs/building/building-archlinux-template.md
View File

@ -9,69 +9,82 @@ This is a community guide, not an official guide. So please, first read the belo
Only if the above guides don't work for you, then try this one. Only if the above guides don't work for you, then try this one.
Arch Linux is a [rolling](https://en.wikipedia.org/wiki/Rolling_release) distribution, making it fragile. In fact, with always the latest versions, the ArchLinux packages meet first the new problems. So it's better to first try to build templates or packages for Fedora or Debian. Arch Linux is a [rolling](https://en.wikipedia.org/wiki/Rolling_release)
distribution, making it fragile. In fact, with always the latest versions, the
ArchLinux packages meet first the new problems. So it's better to first try to
build templates or packages for Fedora or Debian.
Also read: Also read:
- the *Debugging the build process* below section - the *Debugging the build process* below section
- the [ArchLinux known issues](https://github.com/QubesOS/qubes-issues/labels/C%3A%20Arch%20Linux) with Qubes-OS - the [ArchLinux known issues](https://github.com/QubesOS/qubes-issues/labels/C%3A%20Arch%20Linux) with Qubes-OS
## Guide status These instructions are known to work for QubesOS 4.1.
> **These instructions are for Qubes 4.0.4 and 4.1.**
- 4.0.4 :
- 4.1-beta1 : validated (2021-07-31) by the commit author of this line.
- 4.1rc3 : validated (2022-01-11) by the commit author of this line.
- 4.1 : validated (2022-04-11) by the commit author of this line.
## Steps ## Steps
### 1. Create a qubes-builder AppVM ### 1. Create a qubes-builder AppVM
Create an AppVM, based on the last Fedora TemplateVM, named for example *qubes-builder* or *build-archlinux*.
> **The StandaloneVM type cannot build the Arch Linux (minimal or not) template currently, as its Makefiles and Scripts only fully accomodate for the AppVM type's set of filesystem permissions.** Create an AppVM, based on the last Fedora TemplateVM, named for example
*qubes-builder* or *build-archlinux* (see below).
![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png) ![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png)
* Allow at least 15GB of space in the Qube's private storage, then run the following commands: > **The StandaloneVM type cannot build the Arch Linux (minimal or not) template
```console > currently, as its Makefiles and Scripts only fully accomodate for the AppVM
$ qvm-prefs build-archlinux2 vcpus $(nproc) > type's set of filesystem permissions!**
$ qvm-prefs build-archlinux2 memory 4000
$ qvm-prefs build-archlinux2 maxmem 4000 In the qubes settings set at least 15GB of space in the Qube's private storage
``` and create the AppVM by clicking OK.
> **`nproc` specified the number of CPU logical cores it detected, meaning memory usage will increase for compilations that utilize the additional logical cores. For building the 'archlinux-minimal' template, 4000MB should be plenty.**
![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png) ![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png)
> **"System storage max. size" is allocated from the TemplateVM chosen.** Then run the following commands in dom0 to set the VCPUs and memory for the
AppVM:
___
### 2. Create a GitHub account
<details><summary>Details</summary>
**This is a community effort in expanding the Qubes OS project. If you can help this effort out, do so for yourself and others.**
> **This is an optional step.**
![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png)
</details>
___
### 3. Downloading and verifying the integrity of the "Qubes Automated Build System"
#### Open a terminal in the `build-archlinux2` AppVM
* Set terminal size to 30 lines and 100 columns; ensures text from **qubes-builder**'s setup script isn't cut-off.
```console ```console
$ resize -s 30 100 qvm-prefs build-archlinux2 vcpus $(nproc)
qvm-prefs build-archlinux2 memory 4000
qvm-prefs build-archlinux2 maxmem 4000
``` ```
* Install initial dependencies without user confirmation.
> **`nproc` specified the number of CPU logical cores it detected, meaning
> memory usage will increase for compilations that utilize the additional
> logical cores. For building the 'archlinux-minimal' template, 4000MB should be
> plenty.**
### 2. Downloading and verifying the integrity of the "Qubes Automated Build System"
> **Open a terminal in the qubes-builder AppVM that you just created. All
following commands are supposed to typed there, unless stated otherwise.**
Set terminal size to 30 lines and 100 columns; ensures text from **qubes-builder**'s setup script isn't cut-off.
```console ```console
# sudo dnf install -y git make resize -s 30 100
``` ```
* Import and verify the Qubes master key; [to understand the purpose of GPG (a frontend for PGP)](https://www.qubes-os.org/security/verifying-signatures/).
Install initial dependencies without user confirmation.
```console ```console
$ gpg2 --import /usr/share/qubes/qubes-master-key.asc sudo dnf install -y git make
$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
``` ```
Import and verify the Qubes master key (have a look
[here](https://www.qubes-os.org/security/verifying-signatures/) to understand
the purpose of the verification).
```console
gpg2 --import /usr/share/qubes/qubes-master-key.asc
gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
``` ```
In the interactive gnupg shell that opens following the last command, you type
in `fpr` and hit enter to show the fingerprint. Afterwards you type `trust` and
`5` to set the trust level to 'ultimately'. Afterwards you need to confirm your
selection with 'y' and save and exit via `quit`. It should look something like
this:
```console
gpg> fpr gpg> fpr
pub rsa4096/DDFA1A3E36879494 2010-04-01 Qubes Master Signing Key pub rsa4096/DDFA1A3E36879494 2010-04-01 Qubes Master Signing Key
Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494 Primary key fingerprint: 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
@ -93,114 +106,138 @@ Please decide how far you trust this user to correctly verify other users' keys
m = back to the main menu m = back to the main menu
Your decision? 5 Your decision? 5
``` Do you really want to set this key to ultimate trust? (y/N) y
* Download then import the Qubes developers' keys:
```console pub rsa4096/DDFA1A3E36879494
$ curl -O https://keys.qubes-os.org/keys/qubes-developers-keys.asc created: 2010-04-01 expires: never usage: SC
$ gpg2 --import qubes-developers-keys.asc trust: ultimate validity: unknown
``` [ unknown] (1). Qubes Master Signing Key
> **`$HOME` is always defined; see the POSIX 2017 standard for more information: https://pubs.opengroup.org/onlinepubs/9699919799/** Please note that the shown key validity is not necessarily correct
unless you restart the program.
gpg> quit
```
Download then import the Qubes developers' keys:
* Download the latest stable `qubes-builder` repository:
```console ```console
$ git clone https://github.com/QubesOS/qubes-builder.git $HOME/qubes-builder/ curl -O https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg2 --import qubes-developers-keys.asc
``` ```
* Verify the integrity of the `qubes-builder` repository:
Download the latest stable `qubes-builder` repository:
```console ```console
$ cd $HOME/qubes-builder/ git clone https://github.com/QubesOS/qubes-builder.git $HOME/qubes-builder/
$ git tag -v $(git describe)
``` ```
Verify the integrity of the `qubes-builder` repository:
```console
cd $HOME/qubes-builder/
git tag -v $(git describe)
``` ```
The output should contain something like this
```console
gpg: Good signature from "Marek Marczykowski-Górecki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" [full] gpg: Good signature from "Marek Marczykowski-Górecki (Qubes OS signing key) <marmarek@invisiblethingslab.com>" [full]
``` ```
* Install the remaining dependencies:
The verifcation succeeded if you see a good signature as seen above.
Now install the remaining dependencies:
```console ```console
$ make install-deps make install-deps
``` ```
___ ### 3. Configure the `builder.conf` file
### 4. Configure the `builder.conf` file
> **The manual way is copying an example config like `$HOME/qubes-builder/example-configs/qubes-os-r4.0.conf` to `$HOME/qubes-builder/builder.conf`, then editing that copied file.**
<details><summary>{Preferred if you start} Setup script method</summary> > **The manual way is copying an example config like
> `$HOME/qubes-builder/example-configs/qubes-os-r4.0.conf` to
> `$HOME/qubes-builder/builder.conf`, then editing that copied file.**
<details><summary>Setup script method (easier to begin with)</summary>
Run the `setup` script located in `$HOME/qubes-builder/`:
* Run the `setup` script located in `$HOME/qubes-builder/`:
```console ```console
$ ./setup ./setup
``` ```
Install the missing dependencies, by pressing **y**.
![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png) ![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png)
* Install the missing ***dialog*** dependency if asked. Import the 'Qubes-Master-Signing-key.asc' by selecting **Yes**. The setup script
* Press **y** downloads and confirms this key to that of the key on Qubes OS website.
![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png) ![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png)
* **Add Key 0x36879494** asks to import 'Qubes-Master-Signing-key.asc'. The 'setup' script downloads and confirms this key to that of the key on Qubes OS website. Confirm again with **Yes**.
* Select **Yes**, press Enter/Return
![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png) ![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png)
* **Add Key 0x42CFA724**; again, 'setup' will confirm this key to the fingerprint) Choose which Qubes release to build templates for, e.g. **4.1** (use space key to select) and
* Select **Yes**, press Enter/Return hit enter to accept selection.
![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png) ![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png)
* **Choose Which Qubes Release To Use To Build Packages**; what Qubes release to build templates for Choose source repos to use to build packages. Select **QubesOS/qubes-** to get the
* Select the **Qubes Release** for the currently installed version default stable repo.
* Press Space to select the highlighted version.
* Select **OK**, press Enter/Return
![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png) ![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png)
* **Choose Source Repos To Use To Build Packages** Select **Yes** for fast git cloning.
* Select **QubesOS/qubes- Stable - Default Repo**
* Select **OK**, press Enter/Return > **'No' is for reusing the same building environment on a StandaloneVM (not an
> AppVM, as we have used here); a "shallow clone" (depth equal one) is [a bad
> choice for reusable
> environments](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/).**
![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png) ![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png)
* **Git Clone Faster?** Do **not select** any pre-built package repository to build the template
* Select **Yes**, press Enter/Return yourself.
> **'No' is for reusing the same building environment on a StandaloneVM (not an AppVM); a "shallow clone" (depth equal one) is [a bad choice for reusable environments](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/).**
![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png) ![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png)
* **Choose Pre-Build Packages Repositories** Select **Yes** to only build the template.
* Select ***nothing***, press Enter/Return
![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png) ![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png)
* **Build Template Only?** Template distribution selection offers choices of distributions to build.
* Select **Yes**, press Enter/Return Deselect everything (navigating to entry and hitting space) and select
**archlinux-minimal** and confirm by hitting enter.
> **Using 'archlinux' may introduce more failed compiles based on additional
> Qubes components you may not even need. You can install them later manually
> instead.**
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png) ![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
* **Template Distribution Selection** offers choices of distributions to build The builder plugins selection offers choices of builder plugins to compile.
* Deselect ***everything*** Deselect everything (navigating to entry and hitting space) and select
* Select **archlinux-minimal** **builder-archlinux** and confirm by hitting enter.
> **Using 'archlinux' introduces more failed compiles, in the form of Qubes component packages you might not use. \
You want to use Arch Linux, so it's assumed you'll figure out your desired Qubes component selection.**
![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png) ![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png)
* **Builder Plugins Selection** will give choices of builder plugins to compile Select **Yes** to fetch additional source files needed for the chosen builder
* Deselect ***everything*** plugins.
* Select **builder-archlinux**
* Select **OK**, press Enter/Return
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png) ![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png)
* Screen **Get sources** asks to fetch additional source files needed for the chosen builder plugins Press Enter/Return while **OK** is selected to exit.
* Select **Yes**, press Enter/Return
![arch-template-15](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png) ![arch-template-15](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png)
* Press Enter/Return while **OK** is selected. Go directly to [step 4 below](#4-make-all-the-required-qubes-components) to
proceed with the build process.
</details> </details>
<details><summary>Manually creating `builder.conf`</summary> <details><summary>Manually creating `builder.conf` (for experienced users)</summary>
```console ```console
ls -l $HOME/qubes-builder/example-configs ls -l $HOME/qubes-builder/example-configs
@ -224,60 +261,77 @@ fi
</details> </details>
___ ### 4. Make all the required Qubes components
### 5. Make all the require Qubes components
* Required before proceeding: At first the following components need to be build:
```console ```console
$ make remount make remount
$ make install-deps make install-deps
$ make get-sources make get-sources
```
* {Preferred} Building all Qubes components (this can take a long time):
```console
$ make qubes-vm
```
* {Debugging/development} Individual 'make' commands for Qubes components:
```console
$ make vmm-xen-vm
$ make core-vchan-xen-vm
$ make core-qubesdb-vm
$ make core-qrexec-vm
$ make linux-utils-vm
$ make core-agent-linux-vm
$ make gui-common-vm
$ make gui-agent-linux-vm
$ make app-linux-split-gpg-vm
$ make app-linux-usb-proxy-vm
$ make meta-packages-vm
``` ```
___ > **These commands above should get executed every time you restart the
### 6. Build the actual Arch Linux template > qubes-builder AppVM, because these change are lost after a reboot of the VM!**
Now build all Qubes components (this can take a long time) via
```console ```console
$ make template make qubes-vm
``` ```
___ <details><summary>Debugging: commands to 'make' every Qubes component manually</summary>
### 7. Transfer the template into Dom0
* You need to ensure the rpm template is in the `noarch` directory: If `make qubes-vm` fails, you can try to pinpoint the problem by building the
components one by one manually.
```console ```console
$ ls $HOME/qubes-builder/qubes-src/linux-template-builder/rpm/noarch make vmm-xen-vm
make core-vchan-xen-vm
make core-qubesdb-vm
make core-qrexec-vm
make linux-utils-vm
make core-agent-linux-vm
make gui-common-vm
make gui-agent-linux-vm
make app-linux-split-gpg-vm
make app-linux-usb-proxy-vm
make meta-packages-vm
```
</details>
### 5. Build the actual Arch Linux template
```console
make template
```
### 6. Transfer the template into Dom0
You need to ensure the rpm template is in the `noarch` directory:
```console
ls $HOME/qubes-builder/qubes-src/linux-template-builder/rpm/noarch
qubes-template-archlinux-*.*.*-*.noarch.rpm qubes-template-archlinux-*.*.*-*.noarch.rpm
``` ```
* Transfer the qubes-template-archlinux rpm into Dom0
> **File transfering to Dom0 is considered unsafe. \
You accept full responsibility if Dom0 is compromised due to this file transfer.**
Follow the [copying-to-dom0](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0) official guide. Transfer the qubes-template-archlinux rpm into Dom0
* Install the rpm file in dom0. > **File transfering to Dom0 is considered unsafe. You accept full
> responsibility if Dom0 is compromised due to this file transfer.**
Read [How to install software in dom0](https://www.qubes-os.org/doc/how-to-install-software-in-dom0/), then install the rpm with `sudo dnf install <rpm_file>`. Follow the
[copying-to-dom0](https://www.qubes-os.org/doc/how-to-copy-from-dom0/#copying-to-dom0)
official guide. Afterwards, read [how to install software in
dom0](https://www.qubes-os.org/doc/how-to-install-software-in-dom0/) and install
the rpm with `sudo dnf install <rpm_file>`.
* If the build process went smoothly, the 'archlinux' and/or 'archlinux-minimal' template will be listed in Qubes Manager. If the build process went smoothly, the 'archlinux-minimal' template will be listed in Qubes Manager.
___ ___
## Debugging the build process ## Debugging the build process
Arch Linux is a [rolling](https://en.wikipedia.org/wiki/Rolling_release) distro, making it a fragile template for Qubes. Arch Linux is a [rolling](https://en.wikipedia.org/wiki/Rolling_release) distro, making it a fragile template for Qubes.
It's important to understand how to debug Qubes templates, fix, then do a pull request. It's important to understand how to debug Qubes templates, fix, then do a pull request.