Last year I published qubes-ansible project. This enables maintaining your Qubes OS system via Ansible. But, to do the same, you will have to take a few steps as Ansible is not in the default Qubes.

Qubes uses Salt to maintain the system. It also has helpful documentation to explain the idea. In this post and with a few more in the future, I am planning to write a series with basic examples of the same, so that you can maintain your Qubes laptop with the Salt itself.

Working in dom0

You can either directly the required files in dom0, or write them in your standard development VM, and then copy them over to dom0. The choice is yours.

I am directly writing them into dom0 using vim as my editor.

The outcome

I want to create the following:

• A new template called fancy-template based on debian-10
• Install a few packages into it.
• Create a new apt repo for VS Code in it.
• Install VS Code in it.
• Create an AppVM called fancy using the template with 3000MB RAM.

Creating .top and .sls files

The .top file will help us to link between any machine (VMs or dom0) and some state files (.sls).

To find the currently enabled top files use the following command:

qubesctl top.enabled

Now, we will create our own top file.

Create the following file as /srv/salt/learnqubes.top

base:
  dom0:
    - fancy-template

Here we are saying for the dom0 machine (VM) use the state file named fancy-template. The state files contain state and configuration of the machines (VMs).

Creating the first state file

Copy paste the following in /srv/salt/fancy-template.sls file.

create-fancy-template:
  qvm.vm:
    - name: fancy-template
    - clone:
      - source: debian-10
      - label: blue
    - tags:
      - add:
        - playground

create-fancy-vm:
  qvm.vm:
    - name: fancy
    - present:
      - template: fancy-template
      - label: red
      - mem: 3000
    - prefs:
      - template: fancy-template

First, we are using a unique name for that step, where we are asking for a qvm.vm (VM), saying that the name is fancy-template, and it is a clone of debian-10. We are also mentioning the label color and adding a tag to the template.

In the next step, we are creating the AppVM named fancy, from the template, red as the label, and 3000MB RAM.

Enabling the .top first

# qubesctl top.enable learnqubes

This command will enable our top file. You can recheck the list of enabled .top files after this.

Applying the state to dom0

# qubesctl --show-output state.highstate

This command will make sure that all the states from all of the enabled top files will be applied to dom0. After this command finished, you should be able to see our new template and the AppVM.

Enabling vscode repo and installing the packages

We will first write a new state file for the steps, write the following to /srv/salt/add-my-fancy-system.sls file.

install-packages:
  pkg.installed:
    - pkgs:
      - htop
      - sl
      - git
  - refresh: True

install-python-apt-for-repo-config:
  pkg.installed:
    - pkgs:
      - python-apt
   
configure-apt-test-apt-repo:
  pkgrepo.managed:
    - name: "deb [arch=amd64] https://packages.microsoft.com/repos/vscode stable main"
    - file: /etc/apt/sources.list.d/vscode.list
    - key_url: "salt://microsoft.asc"
    - clean_file: True # squash file to ensure there are no duplicates
    - require:
      - pkg: install-python-apt-for-repo-config

install-vscode:
  pkg.installed:
    - pkgs:
      - code

You can read all the details about pkg module, and here we are installing a few packages first. While installing the initial packages, we also make sure to refresh the database (think about apt update). To create the apt repository, we used pkgrepo salt module. You will find one interesting thing in that section, and we are mentioning a GPG public key for the repository.

We actually have to download it in a VM and move it to the dom0 in the same /srv/salt directory.

# qvm-run --pass-io devvm ‘cat /home/user/microsoft.asc’ > /srv/salt/microsoft.asc

Remember to replace devvm with the right AppVM in your system.

We will also update the top file so that it knows to use the make-my-fancy-system.sls file for our fancy-template.

The following is the updated top file.

base:
  dom0:
    - fancy-template

  fancy-template:
    - make-my-fancy-system

Then, we can ask Qubes to apply the state to only the fancy-template VM.

# qubesctl --show-output --skip-dom0 --targets fancy-template state.highstate

This command should create the right state in the fancy-template. Remember to shut down the template and the AppVM (if they are running), and then start the fancy AppVM again. You will find it has all the packages, including VS Code.