Qubes DispVM technical discussion

For a better understanding on DispVMs, today and future. First interesting read…

1 Like

Wow, what a mess. I started writing wiki. You never realize how messy something is until you have to explain it to someone else…

  1. I think proper term for dvm is savefile but I’d like to just call it a “dispVM template” because people have a better idea what a template is - this is nothing like any savefile that most people are used to. Although “templateVM” and “dispVM template” could be confusing also.

  2. If /home/user/.qubes-dispvm-customized is present, does that mean that any file that is different from the underlying templateVM will be preserved? Or only files in certain directories? If the templateVM gets a package update that changes a file that has been customized by the user, which version will it keep?

  3. I just realized I’m making guesses on some things I’ve written because I can’t test them myself without disrupting my own dispVM template. I actually only know one way to update Tor Browser in a dispVM - the way I do it. launch torbrowser in dvm-template, use tb internal updater, then qvm-create-default-dvm. I need to know what happens in the following situation:

~ user creates new dispVM template.
~ first-boot-home-population will copy TBB to /home/user/.tb
~ and touch first-boot-home-population.done
~ the .done file is inherited by new dispVMs so TBB is not copied for each individual dispVM

~ now new version of TBB is released and tb-updater is updated in whonix-ws
~ but no changes will be made to dispVM template

~ now user runs qvm-create-default-dvm whonix-ws
~ since .qubes-dispvm-customized is not present, the existing TBB & .done file are discarded and a new dispVM template is created
~ repeat from the top and new dispVM template has new TBB


And this doesn’t work for users that have customized dispVM template, because the .done file persists and whonix-ws will not copy over the new TBB.

OK, fun and games!

Based on all this technical information and much confusion, I have a draft for wiki entries below. This allows for Qubes-Whonix users to either:

a) install a standard dispVM Whonix-WS template;
b) install an optional dispVM Whonix-WS template with hardcoded changes for the hardened Tor Browser;
c) steps to create a customized dispVM Whonix-WS; and
d) steps to maintain dispVM images so the Tor Browser is up-to-date, whether it is the standard or hardcoded version.

Correct my text where I’m wrong - which I surely will be. :slight_smile:

I’ve just tested this procedure for the hardcoded (hardened) Tor Browser and customized dispVM changes, and it works fine except customized changes are never maintained.

It doesn’t matter if I run the touch command before or after using the Tor Browser, any changes are not maintained. Can someone in Qubes 3.2 please try it and see if it works for you.

There is no reason it should work for entr0py in 3.1, and not work in 3.2.

Below, I have just focused on steps required i.e. ‘do this’, ‘then do this’, because most users simply don’t care about the technical reasons involved, they just want a working solution.

Initial creation of the dispVM (Whonix-WS) in Qubes 3.2

Note: existing dispVMs will be based on the Fedora-23 or Fedora-24 template

1) Delete any existing instances of your dispVM

Qubes VM Manager → View → Show/Hide Internal VMs

Right click on the template ending in “-dvm”

Select “Remove VM”

2) OPTIONAL STEP - For users defaulting to the hardened Tor Browser series only

Note: Hardcoding of the tb-updater version is required

Special note for hardened Tor Browser users: Using this method means the user will potentially be at risk for a day or two following a Tor Browser security update. The alpha updates always come later than the stable release.

A) Open Konsole in the Whonix-WS TemplateVM

Left click on Qubes 3.2 ‘Q’ icon → Select Template: whonix-ws → Select Konsole

B) Create a user configuration file

Whonix 13:

sudo nano /etc/torbrowser.d/50_user.configuration

Whonix 14:

sudo nano /etc/torbrowser.d/50_user.configuration


sudo nano /rw/config/torbrowser.d/50_user.conf

C) Set tbb version to hardened


D) Save file

Ctrl + X

E) Update the Whonix-WS TemplateVM

sudo apt-get update && sudo apt-get dist-upgrade

F) Run the Tor Browser Downloader in the Whonix-WS TemplateVM

Left click on Qubes 3.2 ‘Q’ icon → Select Template: whonix-ws → Run ‘Tor Browser Downloader’*

Note: If this option does not appear in the menu, add it to the menu with ‘Add more shortcuts…’ option

G) Check the Tor Browser signature

DO NOT install the Tor Browser unless the signature and subkey matches those below:

pub 4096R/0x4E2C6E8793298290 2014-12-15 [expires: 2020-08-24]
Key fingerprint = EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290
uid Tor Browser Developers (signing key) torbrowser@torproject.org
sub 4096R/0x2E1AC68ED40814E0 2014-12-15 [expires: 2017-08-25]
sub 4096R/0x7017ADCEF65C2036 2014-12-15 [expires: 2017-08-25]
sub 4096R/0xD1483FA6C3C07136 2016-08-24 [expires: 2018-08-24]

3) Create the dispVM based on the Whonix-WS TemplateVM

A) Open a terminal in dom0

Left click on Qubes 3.2 ‘Q’ icon → Select System Tools → Xfce Terminal

B) Create the disp-VM

Run the commands:

qvm-create-default-dvm whonix-ws


4) Confirm the netVM is set to sys-whonix

Qubes VM Manager → View → Show/Hide Internal dispVMs

Right click on “Whonix-WS-dvm”

Select “VM Settings”

NetVM should be using sys-whonix. Change it if that is not the case.

5) Check the disp-VM based on Whonix-WS works

Left click on Qubes 3.2 ‘Q’ icon → Select DisposableVM → xterm

Run the command:


6) Check Tor Browser version is correct

In the url tab, enter about:tor → press enter

Check the Tor Browser instance either shows “6.0.7” or “6.5.a5-hardened” and matches the version you just installed.

Customization of the dispVM (Whonix-WS) in Qubes 3.2

Note: This step is OPTIONAL and is only required if you wish to store bookmarks, changes to add-on settings, maintain updates to the Tor Browser using the browser’s internal updater, and other unique changes.

1) Launch Konsole (Terminal) in the dispVM

Two methods are available to do this:

Left click on Qubes 3.2 ‘Q’ icon → Select DisposableVM → xterm


Left click on the Qubes 3.2 ‘Q’ icon → Select System Tools → Xfce Terminal and run the command:

qvm-run -a whonix-ws-dvm xterm

2) Create a customized file path

Enter the command:

touch /home/user/.qubes-dispvm-customized

3) Make changes you wish to persist in the dispVM

Note: this usually relates to bookmarks, add-on updates, the privacy slider, javascript settings, search engine preferences, and minor Tor Browser updates you wish to persist

A) Run Tor Browser with the command:


B) Make changes as required and/or run the Tor Browser internal updater:

Select the green onion → “Check for Tor Browser update…”

4) Close the Tor Browser

5) Shutdown the dispVM

6) Recreate the whonix-ws dispVM

A) Open a terminal in dom0

Left click on Qubes 3.2 ‘Q’ icon → Select System Tools → Xfce Terminal

B) Re-create the disp-VM

Run the commands:

qvm-create-default-dvm whonix-ws


7) Check all of your changes are now persistent

Keeping your dispVM (Whonix-WS) image up to date

Important: If you DID NOT customize your dispVM to allow changes to be maintained, this means your dispVM private image WILL NOT CONSISTENTLY run the updated Tor Browser when subsequent releases become available. That is, your manual updates from within the dispVM will be lost after each session.

These steps must be followed after each major TBB release or minor update.

1) OPTIONAL STEP - Users who hardcoded their TBB version

Update your config file to show the latest hardened Tor Browser release. For example:

A) Open Konsole in the Whonix-WS TemplateVM

Left click on Qubes 3.2 ‘Q’ icon → Select Template: whonix-ws → Select Konsole

B) Edit the user configuration file

Whonix 13:

sudo nano /etc/torbrowser.d/50_user.configuration

Whonix 14:

sudo nano /etc/torbrowser.d/50_user.configuration


sudo nano /rw/config/torbrowser.d/50_user.conf

C) Set tbb version to the latest hardened version, for example:


D) Save file

Ctrl + X

2) Update the Whonix-WS TemplateVM

Run Konsole in the Whonix-WS TemplateVM

Run the command:

sudo apt-get update && sudo apt-get dist-upgrade

3) Re-create the dispVM based on the updated Whonix-WS TemplateVM

A) Open a terminal in dom0

Left click on Qubes 3.2 ‘Q’ icon → Select System Tools → Xfce Terminal

B) Re-create the disp-VM

Run the commands:

qvm-create-default-dvm whonix-ws


4) Confirm the netVM is still set to sys-whonix

Qubes VM Manager → View → Show/Hide Internal dispVMs

Right click on “Whonix-WS-dvm” → Select “VM Settings”

NetVM should be using sys-whonix. Change it if that is not the case.

5) Check the disp-VM based on Whonix-WS works

Left click on Qubes 3.2 ‘Q’ icon → Select DisposableVM → xterm

Run the command:


6) Check the Tor Browser version is correct

In the url tab, enter:


Check the Tor Browser instance matches the updated version you just installed.

I don’t think it is useful to set tbb_version="6.5a5-hardened" and then apt-get upgrade tb-updater.

  • Doesn’t work if there is no upgrade of the tb-updater package. (Unless inventing bigger hacks such as apt-get --reinstall.) So you’d still needlessly wait for me to upload the upgraded the tb-updater package.
  • Would be simpler to disable tb-updater automatically downloading the hardcoded version during apt-get upgrade of tb-updater. tb_install_follow=false
  • Then just update-torbrowser and select “6.5a5-hardened” interactively during download verification screen. I left in the ability to manually use update-torbrowser inside TemplateVMs exactly for such reasons.

In TemplateVM or DispVM TemplateVM it probably is best not to touch /rw. In that case rather use /etc. This is because the purpose of /rw is to overwrite settings from within TemplateBasedVMs.

@torjunkie These instructions are a good basis for being added to the wiki. Could you just add them to some final or temporary wiki page instead of posting them in the forums? Then I could just make small modifications as explained above. I’d split them into smaller changes and accompany them with an explanatory wiki edit message that you then could read in the wiki history of that page. I guess that would be more time efficient. (Just write the markup once for the wiki rather than once for the forums and later again for the wiki.)

( Created some temporary page in case needed. https://www.whonix.org/wiki/Qubes/temp )

( Btw since you appreciate learning Whonix internals, one tip. Try running update-torbrowser from command line. Although that output needs to be improved for Whonix 14, it for example explains a bit about the folder into which Tor Browser will be stored. )

The code on how DispVM home is created and how the (non-)existence of the /home/user/.qubes-dispvm-customized status file influences things was recently changed. These changes already ended up in Qubes R3.2 testing repository. So it is probably worth only concentrating on that [before it will be totally changed for good in Qubes 4.0]. (If you are on Qubes R3.2 stable can you please tell if you also already go these changes?)

init - /usr/lib/qubes/init/setup-dvm-home.sh

function initialize_home - /usr/lib/qubes/init/functions:
qubes-core-agent-linux/functions at master · marmarek/qubes-core-agent-linux · GitHub

I have all Qubes git repositories on my disk in folder ~/Qubes. (And scripts to keep them all up to date.) If I want for example to learn about qubes-dispvm-customized, I am using the following “ultimate” grep command (that I can also use in VM template build VMs).

grep --exclude-dir=mnt --exclude-dir=qubes-src/linux-template-builder/mnt --exclude=changelog.upstream --exclude-dir=.git --exclude-dir=chroot-debian --exclude-dir=chroot-jessie -l -r qubes-dispvm-customized

My conclusion is, that dom0 has no knowledge about DispVM template status file /home/user/.qubes-dispvm-customized.

When you have killed and deleted disp1, disp2 (if existing) in Qubes VM Manager (QVMM) and then deleted whonix-ws-dvm (qvm-remove whonix-ws-dvm or using QVMM)… I.e. from a somewhat fresh/clean/resetted state. When you run qvm-create-default-dvm whonix-ws (same for all templates), then “DVM boot complete” indicates that the DVM template was booted (without you seeing that).

Since seeing is believing, you can run in another terminal window "sudo xl console whonix-ws-dvm` during DVM creation (qvm-create-default-dvm). (Run this command several times if it does not work at first, since qvm-create-default-dvm may not be at that stage yet.)

qubesdb-read /qubes-vm-type inside DVM template outputs AppVM.

That is why during that time tb-updater-first-boot.service will copy /var/cache/tb-binary/* to /home/user. (Resulting in the /home/user/.tb/tor-browser DispVM “template”.)

The confusion comes from Qubes calling it on one hand DVM template and on the other hand starting that DVM template like an TemplateBased AppVM.

Start whonix-ws-dvm. (qvm-start whonix-ws-dvm && qvm-run whonix-ws-dvm konsole)

  • create some random file in root image /etc/zzzzzzzzzz
  • create some random file in private image /home/user/zzzzzzzzzz

Shut down the VM (sudo poweroff). Start whonix-ws-dvm again. Learn, that:

  • the random file in root image /etc/zzzzzzzzzz is lost
  • the random file in private image /home/user/zzzzzzzzzz still exists

So DVM “template” really is started like an TemplateBased AppVM.

Shut the DVM “template” down for more experiments.

Now start whonix-ws TemplateVM. Create a file /etc/zzz_create_in_whonix-ws_TemplateVM as well as /home/user/zzz_create_in_whonix-ws_TemplateVM. Shut down whonix-ws- TemplateVM.

Start a DVM “template” konsole. See that /etc/zzz_create_in_whonix-ws_TemplateVM exists. Start DispVM (/usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red). And run into some Qubes issue:

1 Like

So my progress on “best way to keep Tor Browser updated in [customized] DispVM / hardened Tor Browser in DispVM” is blocked for a while now so I can provide debug information.

Since DispVM “template” is actually started like an AppVM… Please try the following. Start a whonix-ws-dvm (DVM “template”) konsole and run update-torbrowser there. Once you installed the version of your choice, it should end up in home folder. Then shut whonix-ws-dvm down. From then, you should have up to date Tor Browser also in [customized] DispVM.

I guess all of this will become a lot easier in Qubes 4.0 when the double layered DispVM implementation is replaced by the much (from user point of view) simpler implementation.

So after studying your posts, it sounds like .qubes-dispvm-customized function is to preserve a dispVM template’s private storage area when qvm-create-default-dvm is run on top of an existing dispVM template - making it function like a template-basedVM in terms of file persistence. Otherwise, the dispVM template is completely reset when a new dispVM template is created.

Given that, I think the steps that I outlined above, represent the simplest way for users to get new TBB in non-customized dispVM templates. Of course, I will also add optional instructions for customized templates (and users who wish to use TB internal updater).

Please review this explanation for accuracy:

  1. user creates new dispVM template to replace a non-customized DVM template.

  2. first-boot-home-population copies TBB to /home/user/.tb because qubes categorizes dispVM templates as appVMs.

  3. first-boot-home-population.done is created and preserved in the dispVM template because /var/cache/tb-updater is defined as a bind-dir in /usr/lib/qubes-bind-dirs.d

  4. first-boot-home-population.done is visible to new dispVMs (disp1,disp2,…) and so first-boot-home-population is not executed when each dispVM is launched.

  5. now new version of TBB is released and tb-updater is updated in whonix-ws template

  6. when the dvm template is auto-refreshed by the template change, new TBB in /var/cache/tb-binary is copied to the dvm-template. But no changes are made to /home/user/.tb

  7. now user runs qvm-create-default-dvm whonix-ws

  8. since .qubes-dispvm-customized is not present, the entire dispVM template is discarded and the process begins again from Step #1.

@torjunkie If you haven’t written up text for this entry already, I started last night on some prose and instructions also. I will incorporate your suggestions and post to the main wiki page: Qubes Disposables. In my version, I’d like to add hardened TBB instructions to a footnote, once you and Patrick sort out the best method for switching over whonix-ws template. The instructions are complicated enough already without giving high visibility to the alpha TBBs.

1 Like

Without testing, this sounds right except the TB installation will only persist if .qubes-dispvm-customized is present. Because next time user boots whonix-ws to run apt-get update, the TB installation will be overwritten by whatever is in /var/cache/tb-binary in whonix-ws - when a new dispVM is launched. If no changes were ever made to whonix-ws after this procedure, then .qubes-dispvm-customized would not be needed because qvm-create-default-dvm would never be run by dom0. And TB installation would have no reason to be ever overwritten. ???

Hi entr0py & Patrick

Good information! I’ll have to wrap my head around it all, as I thought this disp-VM issue was going to be an ‘easy win’. Famous last words. :dizzy_face:

entr0py - as you have suggested, please feel free to write your stuff up and insert into the section Patrick has created. Borrow anything you like, if it is useful.

Agree that hardened stuff is better left as a footnote until the basic browser + remembered (customized) changes can be bedded down.

Patrick - I’ll look at your notes and technical analysis and see if the customized stuff can be worked out at my end. I’m not a technical genius like yourself.


1 Like

Any thoughts on the (previously existing) quote Tor Browser Essentials

Don’t start Tor Browser in the whonix-ws TemplateVM or whonix-ws-dvm DisposableVM-TemplateVM. It is not expected to be done that way and wrong. […]

I am in process of of working through the wiki edits by @entr0py . For now only stylistic changes. Feel free to discuss these. For example I don’t like the two new lines so much. If you think that a more visible separate was useful we could add ----- (which results in and is the same as <hr>. (As I did for some tunnel documentation.)

Under the Qubes TemplateVM model [1], any changes made to a TemplateBasedVM’s root filesystem are lost upon reboot. This can be advantageous from a security viewpoint since malicious code installed to the root filesystem is discarded prior to the next session.

(On TemplateBasedVM) I somewhat disagree with the latter sentence. This would work indeed against off-the-shelf malware that targets general Linux and installs itself lets say as a rootkit in /etc somehow. It would not work against off-the-shelf malware with “Qubes support” let alone for tailored malware.

Also Qubes doesn’t declare that as security feature. What an security feature is, that if one TemplateBasedVM is compromised (considered a permanent compromise until that TemplateBasedVM gets purged), is that it cannot spread to the TemplateVM or other TemplateBasedVMs.

Therefore I removed that sentence.

1 Like

Quote Qubes Disposables

Qubes does not have a built-in snapshot capability like VirtualBox that
can completely revert all changes back to a particular VM state.

True. Added a footnote:

Apart from [https://www.qubes-os.org/doc/dom0-tools/qvm-revert-template-changes/ qvm-revert-template-changes] which can only revert back prior the previous (not last) shutdown of the TemplateVM.

And another footnote:

1 Like

The conservative view would be to recommend that as a best practice. However, we are already relying on Tor Browser not to generate any unique identifiers every time we use it. So logically, it should be safe to run in a template for customization purposes. But it really needs to be stressed that customization is a dangerous exercise. For example, I found by accident that a seemingly innocuous change:
NoScript -> Options -> Notifications -> check 'Show message about blocked scripts'
will alter reported screen size when JS is enabled.

1 Like

Agreed! Please add!

I haven’t forgotten to answer your questions in.

Good question. Next question. :slight_smile:

My advice now is “check your Tor Browser version and make it work”:

Qubes Disposables

So far so good! Great work!

I am done editing on top of your changes and suggestions for now. Made lots of nitpick edits and also real enhancements.

Now, having it documented so far, using hardened Tor Browser in [customized] DispVM is not that hard? In case of issues just use update-torbrowser in DisposableVM-Template. Please feel free to add it. Then use Qubes Disposables.

As for adding instructions for hardened Tor Browser version vs complexity, I think there is an acceptable solution. Use the expand button. See example Whonix mediawiki markup using expand buttons.

I guess this is as far as we can reasonable get with Qubes R3.2 without going into a lot more effort and gymnastics.

Let’s post this sometime soon on qubes-devel? And afterwards also on Whonix blog and qubes-user?