• Documentation for all arguments and commands of kuhbs

kuhbs Arguments and Commands

First Steps


Creating a New Custom kuhb’s

A good way to get started with creating your own kuhbs is by copying one of the example kuhbs from the kuhbs-examples/ directory to the kuhbs/ direcotry and go through all the files. Then run kuhbs create my-kuhb.

If something goes wrong, debug and adjust the config and then remove and re-create the kuhb:

kuhbs remove mykuhb && kuhbs create mykuhb

Creating and Using the kuhbs kuhb’s

kuhbs comes with four default kuhb’s which take over the functions of the Qubes OS default VMs sys-net, sys-firewall and sys-usb:

  • kuhbs-net-nic: manages the PCI network cards
  • kuhbs-net-gateway: apt-cacher-ng and VPN
  • kuhbs-net-firewall: nftables firewall (WIP)
  • kuhbs-usb: manages the PCI usb devices

The setup of the kuhbs kuhb’s requires reassignment of the usb and network card PCI devices as well as setting a new Qubes update VM and default network VM in its policies. For this, the scripts that configure these kuhb’s require the Qubes OS default VMs sys-net, sys-firewall and sys-usb to be present. The removal hook scripts for the kuhbs kuhb’s also have scripts to switch the PCI devices back to the default Qubes OS VMs. Do not remove the VMs sys-net, sys-firewall and sys-usb even after installing kuhbs - if something breaks, you can easily switch back to restore network connectivity.

Note: From experience, USB is a bit buggy at times - qvm-pci attach sys-usb dom0:00_14.0 --verbose --persistent -o no-strict-reset=True sometimes works and somes does not. There is a qubes bug report for that. Most of the time it works…

You can modify the setup of the kuhbs kuhb’s in their configuration directories kuhbs/ in the root of this git repository. Before creating the kuhbs kuhb’s you have to define the PCI devices for your network and usb card in:

  • kuhbs/kuhbs/net/nic/ndp/hooks/create-post.sh
  • kuhbs/kuhbs/net/nic/ndp/hooks/remove.sh
  • kuhbs/kuhbs/usb/ndp/hooks/create-post.sh
  • kuhbs/kuhbs/usb/ndp/hooks/remove.sh

You can show the PCI device IDs using the qvm-pci command. The same goes for the respective scripts for the kuhbs-usb kuhb.

By default, kuhbs-net-gateway is designed to run a wireguard VPN to tunnel your traffic through a VPN provider, like mullvad. You have to configure this before creating the kuhb kuhbs-net-gateway. For this, place wireguard .conf files in kuhbs/kuhbs/net/gateway/tpl/templates/wireguard/configs/, for example:

ls kuhbs/kuhbs/net/gateway/tpl/templates/wireguard/configs/
mullvad.conf  protonvpn.conf  funky-vpn.conf

During startup of the Named DisposableVM ndp-kuhbs-net-gateway, the script kuhbs/kuhbs/net/gateway/tpl/templates/wireguard/wireguard-config-select.sh will be executed which will randomly select one of the .conf files from the directory above.

When everything is configured you can create the kuhbs kuhb’s with the following commands:

kuhbs create kuhbs/net/nic
kuhbs create kuhbs/net/gateway
kuhbs create kuhbs/net/firewall
kuhbs create kuhbs/usb

If something goes wrong, debug and adjust the config and then remove and re-create the kuhb:

kuhbs remove kuhbs/usb && kuhbs create kuhbs/usb

Understanding the kuhbs Output

kuhbs has a log function that prints text like this in color (which I am unable to represent in html using prism.js - there is a video of kuhbs in action on the main page)

kuhbs                         INFO   creating kuh of type tpl
tpl-checks-firefox            INFO   creating TemplateVM by cloning TemplateVM debian-12-minimal
+ qvm-clone debian-12-minimal tpl-checks-firefox

The syntax of the log lines is:

logging kuh, kuhb or kuhbs itself | log level | log message

In the following example, first kuhbs “itself” is logging something and then the kuh (VM) tpl-checks-firefox:

kuhbs                         INFO   creating kuh of type tpl
tpl-checks-firefox            INFO   creating TemplateVM by cloning TemplateVM debian-12-minimal

All lines that begin with a + are commands that are executed in dom0. kuhbs wants you to know and understand which commands are executed in dom0 and will always print those using BASH’s set -x, which prints commands to the screen before executing them.

+ qvm-clone debian-12-minimal tpl-checks-firefox

kuhbs create will in most cases execute scripts on at least the TemplateVM for custimizing it. These scripts produce output like this:

tpl-checks-firefox            INFO   combining the scripts in /home/user/kuhbs/kuhbs/checks/firefox/tpl/scripts/*.sh into a single script /tmp/tmp.2GNtUXXv2Lkuhbs-script
tpl-checks-firefox            INFO   executing script /tmp/tmp.2GNtUXXv2Lkuhbs-script
+ qvm-copy-to-vm tpl-checks-firefox /home/user/kuhbs/scripts/kuhbs-run-script.sh /tmp/tmp.2GNtUXXv2Lkuhbs-script
+ qvm-run --quiet --user root tpl-checks-firefox '/usr/bin/xterm -fs 12 -fa DejaVuSansMono -bg black -fg white +sb -si -title script_/tmp/tmp.2GNtUXXv2Lkuhbs-script -e /home/user/QubesIncoming/dom0/kuhbs-run-script.sh /tmp/.kuhbs-script-exit-status-6l5fyyD7Q9hj5Vcp /home/user/QubesIncoming/dom0/tmp.2GNtUXXv2Lkuhbs-script'

This output describes that the scripts in /home/user/kuhbs/kuhbs/checks/firefox/tpl/scripts/ are all combined into one script using cat *.sh > tempscript.sh. Then tempscript.sh is copied to the kuh and executed in a graphical terminal.


Automatically Setting Up All kuhb’s

The script in scripts/setup-all-my-kuhbs.sh serves as an example on creating all of your kuhb’s in the correct sequence, or even in parallel. Using the apt-cacher-ng installed in the kuhb kuhbs-net-gateway, this should not take all to long depending on your setup. The idea is to spawn several graphical xterm terminals in dom0 that each run one instance of kuhbs create <kuhb>.

kuhbs supports multiple kuhbs create commands to run in parallel, as it does with kuhbs upgrade as well (use kuhbs upgrade-all). kuhbs backup backups the VMs one after another.