Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update information on creating templates for new OS

Browse Source
This commit is contained in:
unman 2019-08-02 01:13:45 +00:00
parent a540afdbb6
commit 06d5009993
No known key found for this signature in database
GPG Key ID: BB52274595B71262
1 changed files with 54 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

96
external/building-guides/building-non-fedora-template.md vendored
View File

@ -8,42 +8,47 @@ redirect_from:
- /wiki/BuildingNonFedoraTemplate/ - /wiki/BuildingNonFedoraTemplate/
--- ---
Building a TemplateVM for ArchLinux (or another non Fedora OS) Building a TemplateVM for a new OS
============================================================== ==============================================================
If you don't like using Fedora because of specific administration, package management or other building needs, you could build a TemplateVM for your distribution of choice. If you don't like using one of the existing templates because of specific administration, package management or other building needs, you can build a TemplateVM for your distribution of choice.
This article shows how to build a template for a different OS, taking ArchLinux as an example. This article shows how to go about building a template for a different OS.
Qubes builder scripts Qubes builder scripts
===================== =====================
You can start creating Qubes builder scripts for your new OS. Just note that it will probably make your testing process harder than trying to build the package directly in an HVM on which you already installed this new OS. One way to start is by creating Qubes builder scripts for your new OS.
Note that this will probably make your testing process harder than trying to build the package directly in an HVM on which you have already installed the new OS.
chroot initialization chroot initialization
--------------------- ---------------------
You need to customize some scripts that will be used to build all the Qubes tools. You need to customize some scripts that will be used to build all the Qubes tools.
Create a new directory to hold the files for the new os.
The scripts you will be interested in will be inside the `qubes-src/linux-template-builder` folder: You can start from the Fedora scripts in `builder-rpm/template-scripts`, and see how they have been changed for Debian and Archlinux.
The scripts you need are in :
~~~ ~~~
scripts_fedora builder-archlinux/scripts
scripts_archlinux builder-debian/template-debian
scripts_yourOSname builder-rpm/template-scripts
~~~ ~~~
### 00\_prepare.sh ### 00\_prepare.sh
The goal of the first script `00_prepare.sh` is to download and verify the signature of the installation CD and tools. You can use the `$CACHEDIR` directory variable to store files that could be reused (such as downloaded scripts or iso files). The goal of the first script `00_prepare.sh` is to download and verify the signature of the installation CD and tools, or the native tools for building an OS.
You can use the `$CACHEDIR` directory variable to store files that could be reused (such as downloaded scripts or iso files).
### 01\_install\_core.sh ### 01\_install\_core.sh
The goal of this script is to install a base environment of your target OS inside the `$INSTALLDIR` directory variable. Generally you need to bootstrap/install your package manager inside the `$INSTALLDIR` directory and install the base packages. The goal of this script is to install a base environment of your target OS inside the `$INSTALLDIR` directory variable.
Generally you need to bootstrap/install your package manager inside the `$INSTALLDIR` directory and install the base packages.
### Testing the installation process ### Testing the installation process
Edit the file `builder.conf` to change the variable `$DISTS_VM` to your OS name (`DISTS_VM=your_os_name`). The try to create (make) the template to check that at least these first two scripts are working correctly: Edit the file `builder.conf` to change the variable `$DISTS_VM` to your OS name (`DISTS_VM=your_os_name`).
Then try to create (make) the template to check that at least these first two scripts are working correctly:
~~~ ~~~
make linux-template-builder make linux-template-builder
@ -52,7 +57,8 @@ make linux-template-builder
Qubes builder Makefiles Qubes builder Makefiles
----------------------- -----------------------
Now you need to create Makefiles specific to your OS. You will find the required scripts directly inside the `qubes-builder` folder: Now you need to create Makefiles specific to your OS.
You will find the required scripts to adapt in the `builder-*` folders:
~~~ ~~~
prepare-chroot-yourOSname prepare-chroot-yourOSname
@ -61,30 +67,34 @@ Makefile.yourOSname
### prepare-chroot-yourOSname ### prepare-chroot-yourOSname
The goal of this file is to prepare a development environment of your target OS inside a chroot. You will reuse the `00_prepare.sh` and `01_install_core.sh` scripts. Additionally, the following things will be necessary to put in this Makefile: The goal of this file is to prepare a development environment of your target OS inside a chroot.
You will reuse the `00_prepare.sh` and `01_install_core.sh` scripts.
Additionally, the following things have to be done in this Makefile:
- the `$1` variable will contain the installation directory (`$INSTALLDIR` should contain the same value as `$1` when you run `00_prepare.sh` or `01_install_core.sh`) - the `$1` variable will contain the installation directory (`$INSTALLDIR` should contain the same value as `$1` when you run `00_prepare.sh` or `01_install_core.sh`)
- after your base system is installed, you should install development tools and libraries (gcc, make, ...) - after your base system is installed, you should install development tools and libraries (gcc, make, ...)
- create a user called 'user' inside your chroot, and give him enough rights to run the command sudo without any password - create a user called 'user' inside your chroot, and give them enough rights to run the command sudo without any password
- register all the repositories that are be necessary and synchronize the package database - register all the repositories that will be necessary and synchronize the package database
- register a custom repository that will be used to store Qubes packages - register a custom repository that will be used to store Qubes packages
### Makefile.yourOSname ### Makefile.yourOSname
This file will be used to define the action required when installing a custom package. The most important one are: This file will be used to define the action required when installing a custom package.
The most important one are:
- `dist-prepare-chroot`: that's where you will call `prepare-chroot-yourOSname` if the chroot has not been initialized. - `dist-prepare-chroot`: that's where you will call `prepare-chroot-yourOSname` if the chroot has not been initialized.
- `dist-package`: that's where you will chroot the development environment and run the command used to build a package. - `dist-package`: that's where you will chroot the development environment and run the command used to build a package.
- `dist-build-dep`: that's where you will create the custom repository for your target OS based on already compiled packages. - `dist-build-dep`: that's where you will create the custom repository for your target OS based on already compiled packages.
These additional target need to exist once you created your first packages: These additional targets need to exist once you have created your first packages:
- `dist-copy-out`: that's where you will retrieve the package you just built and put it with all the other packages you prepared. - `dist-copy-out`: that's where you will retrieve the package you just built and put it with all the other packages you prepared.
- `update-repo`: that's where you will retrieve the package that have been built and add it to the custom repository. - `update-repo`: that's where you will retrieve the package that has been built and add it to the custom repository.
### Testing the development chroot ### Testing the development chroot
You will be able to test these scripts when making the first Qubes packages. Don't forget that the first things that run when running `make somcomponent-vm` will be these two scripts, and that you will need to debug it at this point. You will be able to test these scripts when making the first Qubes packages.
Don't forget that the first things that run when running `make somecomponent-vm` will be these two scripts, and that you will need to debug it at this point.
Qubes packages Qubes packages
-------------- --------------
@ -99,12 +109,13 @@ Qubes packages
Additional Installation scripts Additional Installation scripts
------------------------------- -------------------------------
Again you need to work on scripts inside the `qubes-src/linux-template-builder` folder: Again you need to create new scripts based on the existing scripts in these folders:
~~~ ~~~
scripts_fedora builder-archlinux/scripts
scripts_archlinux builder-debian/template-debian
scripts_yourOSname builder-rpm/template-scripts
~~~ ~~~
### 02\_install\_groups.sh ### 02\_install\_groups.sh
@ -113,39 +124,40 @@ The goal of this script is to install all the packages that you want to use in y
### 04\_install\_qubes.sh ### 04\_install\_qubes.sh
The goal of this script is to install in your template all the packages you built previously. Also you need to edit the fstab file of your template to mount Qubes virtual hard drives. The goal of this script is to install in your template all the packages you built previously.
Also you need to edit the fstab file of your template to mount Qubes virtual hard drives.
### 09\_cleanup.sh ### 09\_cleanup.sh
This script is use to finalize and to remove unnecessary things from your template, such as cached packages, unused development packages ... This script is used to finalize and to remove unnecessary things from your template, such as cached packages, unused development packages ...
Starting with an HVM Starting with an HVM
==================== ====================
If no Qubes packages are available for your selected OS. You could start to install an HVM with your OS. Your goals will be: If no Qubes packages are available for your selected OS you could start by installing your OS in an HVM.
Your goals will be:
- to identify how to install the OS using command lines - to identify how to install the OS using command lines
- to create required Qubes packages - to create required Qubes packages
- to identify potential issue making all Qubes agents and scripts working correctly. - to identify potential issues, making sure all Qubes agents and scripts work correctly.
As soon as you manage to make `qrexec` and `qubes-gui-agent` working, it should be sufficient to start preparing a template VM. As soon as you manage to get `qrexec` and `qubes-gui-agent` working, you will be ready to start preparing a template VM.
### Xen libraries ### Xen libraries
Several Xen libraries are required for Qubes to work correctly. In fact, you need to make `xenstore` commands working before anything else. For this, Qubes git can be used as several patches have been selected by Qubes developers that could impact the activity inside a VM. Start be retrieving a recent git and identify how you can build a package from it: `git clone https://github.com/QubesOS/qubes-vmm-xen.git`. Several Xen libraries are required for Qubes to work correctly.
In fact, you need to make `xenstore` commands working before anything else.
For this, Qubes git can be used as several patches have been selected by Qubes developers that could impact the activity inside a VM.
Start by retrieving a recent git and identify how you can build a package from it: `git clone https://github.com/QubesOS/qubes-vmm-xen.git`.
Find the .spec file in the git repository (this is the file being used to build rpm packages), and try to adapt it to your OS in order to build a package similar to the target 'vmm-xen'. For example, a PKGBUILD has been created for [ArchLinux](/doc/templates/archlinux/) and can be found in the vmm-xen repository. Find the .spec file in the git repository (this is the file used to build rpm packages), and try to adapt it to your OS in order to build a package similar to the target 'vmm-xen'.
For example, a PKGBUILD has been created for [ArchLinux](/doc/templates/archlinux/) which can be found in the vmm-xen repository.
Don't be afraid with the complexity of the PKGBUILD, most of the code is almost a copy/paste of required sources and patches found in the .spec file provided in the git repository. Don't be afraid of the complexity of the PKGBUILD: most of the code is almost a copy/paste of required sources and patches found in the .spec file provided in the git repository.
Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. Add the following line to your fstab (you can create this line in your package install script): `xen /proc/xen xenfs defaults 0 0`. Note once the package has been successfully compiled and installed, you need to setup XEN filesystem.
Add the following line to your fstab (you can create this line in your package install script):
`xen /proc/xen xenfs defaults 0 0`.
Now install the package you built and mount `/proc/xen`. Verify that xenstore-read works by running: `xenstore-read name`. That should give you the current name. Now install the package you built and mount `/proc/xen`.
Verify that xenstore-read works by running: `xenstore-read name`. That should give you the current qube name.
### ArchLinux example PKGBUILDs
Qubes OS core agent (qrexec...) - [https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD)
Qubes OS kernel modules - [https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD)
Qubes OS GUI agent - [https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD)