Dev/Qubes
Donate
Kicksecure Qubes OS related development documentation.
Kicksecure Template[edit]
Building the Template[edit]
Kicksecure has a Qubes OS template available that can be built and installed using qubes-builderv2. This allows Kicksecure to be installed into Qubes OS without the need for distribution morphing.
WARNING: The Kicksecure Qubes OS template is still in development and may be unstable or prone to issues. Use at your own risk.
Qubes Template Build Fedora Version Number[edit]
- Qubes upstream requirement: Only Fedora can be used to build Qubes Templates.
- Multiple versions exist: There might be various Fedora Template versions.
- Current version at time of writing: The Qubes Fedora Template version used at the time of writing this wiki page was:
40 - Check for newer versions: There might be a newer Qubes Fedora Template version by the time you are reading this. Please check if there is already a newer Fedora Template version.
- No special requirements for Qubes Kicksecure: The Qubes Kicksecure Template does not have any special Qubes Fedora Template version requirements.
- Follow Qubes upstream recommendations: The same Qubes Fedora Template version that Qubes upstream uses and/or recommends to build Debian can be used to build the Qubes Kicksecure Template.
- Wiki editors notice: The version number can be updated by editing Template:version-fedora-build-qubes-template.
Setting up qubes-builderv2[edit]
It is recommended to use a Fedora-based App Qube for building the Kicksecure template. This is because upstream Qubes uses Fedora-based App Qubes to build Qubes Templates.
Determine which Fedora template is used for the default-dvm DVM template. For the purposes of this document, we will assume it is fedora-40-xfce.
Installing dependencies[edit]
1. Launch a terminal in the fedora-40-xfce template.
2. Install all dependencies for qubes-builderv2 into the template. The dependencies are listed at:
- https://github.com/QubesOS/qubes-builderv2/blob/main/dependencies-fedora.txt
- https://github.com/QubesOS/qubes-builderv2/blob/main/dependencies-fedora-qubes-executor.txt
All packages from both lists must be installed.
3. Ensure git is installed by running the following command:
sudo dnf install git
4. Shut down the template once you have completed installing all dependencies.
Prepare App Qube[edit]
WARNING: It is not recommended to reuse an existing App Qube for running the template build. You will be transferring the built template to dom0 and installing it when you are complete. If the App Qube used for running the builder is compromised, the template may become compromised as well.
1. Create a new App Qube for running qubes-builderv2.
You can name this qube anything you want; we will call it work-qubesos in this document. Ensure the Template is set to fedora-40-xfce.
2. Increase qubes-builderv2 disk space.
Using Qube Manager, set the private disk space for work-qubesos to something reasonably large. 32 GB should work.
3. Clone the default-dvm Template and name it qubes-builder-dvm.
This DVM Template will be used for fetching and building code.
4. Increase qubes-builder-dvm disk space.
Once the Template is cloned, adjust its settings with Qubes Manager and increase the private storage space to at least 30 GB (more is preferable).
5. Once that's done, start a terminal in the qubes-builder-dvm Template, then set it aside for use later.
dom0 Setup[edit]
1. Open a dom0 terminal and run:
sudo nano /etc/qubes/policy.d/50-qubesbuilder.policy
2. Paste.
Type the contents of https://github.com/QubesOS/qubes-builderv2/blob/main/rpc/policy/50-qubesbuilder.policy into this file. (Note: If you have chosen names other than work-qubesos or qubes-builder-dvm for your qubes, you must adjust this configuration file to specify the correct VM names.)
3. Save.
Save your changes with Ctrl+S and exit with Ctrl+X.
qubes-builder-dvm setup[edit]
Inside qubes-builder-dvm Template
1. Create folders.
sudo mkdir -p /rw/bind-dirs/builder /rw/config/qubes-bind-dirs.d
2. Open bind-dires configuration file.
sudo nano /rw/config/qubes-bind-dirs.d/builder.conf
3. Paste.
binds+=('/builder')
4. Save.
5. Open rc.local file.
sudo nano /rw/config/rc.local
6. Paste.
mount /builder -o dev,suid,remount
7. Save.
8. Shut down the Template.
dom0 Setup Continued[edit]
1. In a dom0 terminal, run:
qvm-prefs work-qubesos default_dispvm qubes-builder-dvm
Once this is done, all configuration should be complete, and you are now ready to install and use qubes-builderv2.
Installing qubes-builderv2[edit]
1. Ensure that fedora-40-xfce, qubes-builder-dvm, and work-qubesos are all shut down. This ensures that all changes made to the templates apply to any new AppVMs and DispVMs launched during the build process.
2. Start work-qubesos and open a terminal in it. Install and verify the authenticity of the Qubes Security Pack by following the instructions at https://www.qubes-os.org/security/pack/. This is necessary to verify the authenticity of the qubes-builderv2 source code.
3. Clone the qubes-builderv2 repository using:
git clone https://github.com/QubesOS/qubes-builderv2.git
4. Enter the cloned repository:
cd qubes-builderv2
5. Verify the authenticity of the head commit's tag:
git tag -v $(git describe)
The output of this command should indicate that the tag's signature is good and should NOT display any warnings. If warnings are displayed, you may have installed the Qubes Security Pack improperly (for example, by forgetting to install the Qubes Master Signing Key or failing to mark it as trusted). If you are told that a tag does not exist, the head commit hasn't been tagged by a Qubes OS developer, and you should use:
6. Back up one commit if a tag does not exist:
git checkout HEAD^
Then try to verify the repository's authenticity again. If the signature comes back bad, the repository is corrupted (or compromised) and should be discarded immediately.
Template Build[edit]
1. Create a new file named builder.yml under the qubes-builderv2 directory, and fill it with the following contents:
include: - example-configs/kicksecure.yml qubes-release: r4.2 use-qubes-repo: version: 4.2
2. To build the template, run:
sudo ./qb package fetch prep build && sudo ./qb -t kicksecure-17 template fetch prep build
This will download the code needed to build the template and then build the template. If all goes well, the built template will be placed in folder:
qubes-builderv2/artifacts/templates/rpm
Template Installation[edit]
To install the manually built Template.
1. Copy the template RPM file to dom0:
Note: Substitute the real name of the RPM file (this name includes a timestamp and will thus be different for each build).
qvm-run --pass-io work-qubesos 'cat /home/user/qubes-builderv2/artifacts/templates/rpm/qubes-template-kicksecure...rpm' > qubes-template-kicksecure...rpm
2. Install the template with:
sudo qvm-template install --nogpgcheck ./qubes-template-kicksecure...rpm
WARNING: This action can execute arbitrary code as root on dom0! Only do this if you fully trust the App Qube used to build this template!
3. You should now see a kicksecure-17 template available in the application menu, under the "Templates" section.
Related[edit]
See Also[edit]
- Kicksecure for Qubes - User Documentation
- Qubes feature request: build Kicksecure Qubes Template #9573
- qubes-builder-v2 pull request: Add Kicksecure template support #170
A secure by default operating system with the latest security research in place.
At
Kicksecure we value freedom and trust, supporting Open Source and Freedom Software
2012-
2025 ENCRYPTED SUPPORT LLC
We believe security software like Kicksecure needs to remain Open Source and independent. Would you help sustain and grow the project? Learn more about our 12 year success story and maybe DONATE!