Multiple Qubes-Whonix Templates

From Whonix
Jump to navigation Jump to search

Compartmentalization. Managing multiple Qubes-Whonix Templates.


Multiple Qubes-Whonix Templates provides much greater flexibility over a single template when choosing software packages. The additional cloned templates can be customized with software to meet specific requirements; something impossible to achieve with a single Template. [1]


  • Packages from a later release: Installing packages from a later release could end up breaking the system. For example, mixing packages from Debian with those of a later release like Debian can lead to an unstable system because of associated software dependencies required for full functionality. [2] [3] Prior to installing Debian packages from a later release, first read Kicksecure logo Install from Debian Testing The Web Archive Onion Version .
  • Custom software: Additional cloned templates makes it easy to install custom software used for a specific application. For example, users could Tunnel UDP over Tor by configuring whonix-workstation-17 to route all applications through a VPN tunnel. However, this method also increases the risk of identity correlation. To mitigate this risk, the App Qube based on this template should only be used for the particular application that must be routed through the tunnel-link. Before installing custom software it is recommended to first read Install Software: General Advice.
  • Untrusted packages: It is unwise to install untrusted packages in a template used for sensitive activities. With multiple cloned Templates, a single template can be designated as a less trusted domain for that purpose. [4] Read Trusting your prior to installing untrusted packages.

Cloning Templates[edit]

Info Note: Each Template's root filesystem runs independently from all other Templates. [5] Therefore, each individual Template must be updated separately. This is a Qubes default and unspecific to Qubes-Whonix.

Qube Manager[edit]

Cloning templates in Qubes-Whonix is easily accomplished via Qube Manager.

1. Naming convention advice.

Be careful with naming conventions for both Templates and App Qubes (based on those templates) so they are not confused with each other. This will minimize the chance of basing an App Qube on the wrong template.

When creating App Qubes based on cloned Templates, a purpose-based naming convention is sensible so there is no ambiguity regarding the intended function of an App Qube. For example, if an App Qube is created to tunnel UDP over Tor, appending tunnel-udp (the purpose) to the end of anon-whonix would lead to the name anon-whonix-tunnel-udp.

2. Template cloning.

To clone Qubes-Whonix Templates, follow the steps below in Qube Manager:

Qube ManagerVM to be ClonedClone qubeEnter name for Qube clone

Figure: Cloning Whonix qubes

When prompted, give the newly cloned VM a name that is not easily confused with other VMs. This minimizes the chances of basing an App Qube on the wrong template; there could be serious security concerns if a "trusted" App Qube was based on the wrong Template with untrusted packages.

Figure: Clone Renaming

3. Done.

Cloning has been completed.

4. UpdatesProxy Settings.

The user might wish to customize the UpdatesProxy Settings.

UpdatesProxy Settings[edit]

Info Reminder: The net qube setting of Templates should be set to None. [6]

warning A cloned Whonix Template will by default be upgraded through sys-whonix. [7] This is a known Qubes usability issue. [8]

If you would like to change the UpdatesProxy setting for any Template, apply the following steps.

Choose either Option A (stable) or Option B (testers only). In doubt, choose Option A.

Option A[edit]

Qubes old qrexec policy format.

1. In dom0, open /etc/qubes-rpc/policy/qubes.UpdatesProxy with root rights.

sudo nano /etc/qubes-rpc/policy/qubes.UpdatesProxy

2. Add at the top of that file.


name-of-template-vm $default allow,target=name-of-net-qube

Example line entry example:

Note: Replace sys-whonix-cloned with the actual name of the VM such as for example sys-whonix2.

whonix-workstation-17-clone-1 $default allow,target=sys-whonix-cloned

Full example:

If the user already completed adding above line entry, the following is not required. It's just for illustrative purposes. A complete file could look like this.

## Note that policy parsing stops at the first match, ## so adding anything below "$anyvm $anyvm action" line will have no effect ## Please use a single # to start your custom comments # Upgrade all Templates through sys-whonix. #$type:TemplateVM $default allow,target=sys-whonix # Upgrade whonix-gateway-17-clone-1 through sys-whonix-cloned. whonix-gateway-17-clone-1 $default allow,target=sys-whonix-cloned # Upgrade whonix-workstation-17-clone-1 through sys-whonix-cloned. whonix-workstation-17-clone-1 $default allow,target=sys-whonix-cloned # Upgrade Whonix Templates through sys-whonix. $tag:whonix-updatevm $default allow,target=sys-whonix # Deny Whonix Templates using UpdatesProxy of any other VM. $tag:whonix-updatevm $anyvm deny # Default rule for all Templates - direct the connection to sys-net # Note: 'TemplateVM' not only 'Template' is correct. The 'VM' cannot be omitted. $type:TemplateVM $default allow,target=sys-net $anyvm $anyvm deny

4. Save the file.

<Ctrl-X> --> press Y --> <Enter>

5. Done.

The procedure is now complete.

Option B[edit]

Qubes new qrexec policy format.

1. Disable Qubes old-style UpdatesProxy qrexec configuration file.

In dom0, move the Qubes old-style configuration file /etc/qubes-rpc/policy/qubes.UpdatesProxy out of the way. [9]

If there is an error that this file no longer exists that is OK too. The only purpose of this step is to make sure /etc/qubes-rpc/policy/qubes.UpdatesProxy no longer exists.

sudo mv /etc/qubes-rpc/policy/qubes.UpdatesProxy ~/

2. In dom0, open /etc/qubes/policy.d/30-user.policy with root rights.

sudo nano /etc/qubes/policy.d/30-user.policy

3. Learn the syntax.

Syntax: [10]

qubes.UpdatesProxy      *   name-of-template-vm    @default    allow target=name-of-net-qube

4. See this example.

Example line entry example:

qubes.UpdatesProxy * whonix-workstation-17-clone-1 @default allow target=sys-whonix-cloned

Full example:

If the user already completed adding above line entry, the following is not required. It's just for illustrative purposes. A complete file could look like this.

qubes.UpdatesProxy * whonix-gateway-17-clone-1 @default allow target=sys-whonix-cloned qubes.UpdatesProxy * whonix-workstation-17-clone-1 @default allow target=sys-whonix-cloned

5. Add new entry to the file.

Based on the syntax and examples above.

Note: Replace sys-whonix-cloned with the actual name of the VM such as for example sys-whonix2.

6. Save the file.

<Ctrl-X> --> press Y --> <Enter>

7. Done.

The procedure is now complete.

See Also[edit]


  1. Optionally, the default template can be cloned and used as the default template for App Qubes. Having a “known-good” backup template available at all times is best practice.
  2. Using packages from different repositories can lead to Kicksecure logo Dependency Hell The Web Archive Onion Version .
  3. This problem can be avoided by cloning additional Whonix templates and preferring packages from a single repository in each Template.
  4. It is strongly encouraged to only install signed packages from a trusted source.
  5. This applies to all Templates, even if they were cloned.
  6. Since Templates in Qubes R4 and above are supposed to be upgraded through qrexec based Qubes updates proxy.
  7. Because /etc/qubes-rpc/policy/ contains: $tag:whonix-updatevm $default allow,target=sys-whonix Quote:

    Note that policy parsing stops at the first match, [...]

  8. Qubes dom0 configuration folder /etc/qubes-rpc/policy is legacy. It was replaced with the new-style qrexec config folder /etc/qubes/policy.d/ which is used here in the documentation. This is [[unspecific|unspecific to Whonix.
  9. This works because as per Qubes default, Qubes parses configuration file /etc/qubes/policy.d/30-user.policy before /etc/qubes/policy.d/90-default.policy. See also Qubes dom0 file /etc/qubes/policy.d/90-default.policy. cat /etc/qubes/policy.d/90-default.policy /etc/qubes/policy.d/90-default.policy comes with the following comment on top.
    ## Do not modify this file, create a new policy file with a lower number in the
    ## filename instead. For example `30-user.policy`.

We believe security software like Whonix 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!