Suggestions for Qubes Architecture Diagram

I like the graphics in the system documentation very much - they help a lot in teaching how today a structurally secure operating system can / should be built.

In the main architecture graphic, I added a Template VM in order to show this important concept right at the beginning of my lecture:

Also, in the graphic showing the interconnections between different qubes, I changed the connection of sys-whonix to the outside world. In the standard configuration, sys-whonix is not directly connected to the external network but instead to sys-firewall, such that the only external connection is from sys-net:

Perhaps you could consider if these changes make sense?

Anyhow, I think that the current documentation is great, and this holds true especially if you compare it with a large part of the Windows or Ubuntu documentation!

1 Like

Hi @GWeck! Welcome to the forum!

I wish I had that lecture in my operating systems class :slight_smile:

Well spotted. I wonder if this is intentional or not. Perhaps it’s just a mistake and should be corrected. On the other hand it might be there to reduce the mental load (even if not technically correct).

Just a quick suggestion on your change: perhaps you can switch the order of the green boxes to reduce the wiring complexity: (from top to bottom) network hardware, sys-net, sys-firewall and lastly sys-whonix.

I also quite like them. I even think these should be broken down into maybe three diagrams from a very basic view to a more complex and accurate view for educational purposes.

Thank you, @GWeck. These changes make sense to me, but we would want to have the devs incorporate the changes into the original source files. I believe @fepitre is the one handling these.

(@GWeck I moved this discussion to a new thread. Feel free to adjust its title)

@adw The changes I made were just quick fixes in the downloaded pictures, which I could not really edit. Surely any changes have to be made by the diagram creators.

@deeplow That sequence of the green boxes would surely simplify the graphic. A good sequence of diagrams for teaching, in my opinion, is the following (in

(The last two are nearly identical; I Prefer the first of them.)


… and, as a look into the future:

The reaction of my students to these diagrams and the resulting discussions are generally very positive.

1 Like

I couldn’t find all the sources for the diagrams but some of them are in the latest version on this fork by @fepitre and you can edit them with (foss):

That sounds great! Here’s some extra feedback:

For this one, it makes more sense to me to view it upside-down: VMs on top; hardware on the bottom, following the typical logic of high-level being on top and low-level being bellow.

I think from the second to the third the colors and positions of the VMs could match. Not that it makes a lot of difference, but the mapping may make things even more apparent.

If we think any of these changes we’re discussing are valuable, maybe we could open a github issue and related pull requests addressing them?

@deeplow it should be easy now to create new ones too. I’ve also provided updated with sources the qubes-components one (your third image):


1 Like

I can manage to recreate or if someone is doing it, the bottom part because like others, I did not found the sources. Then, we can discuss with @marmarek what to put as update and new part into the documentation. Maybe it is worth to merge my branch into QubesOS master one?

1 Like

Hi @fepitre!

Thanks a lot!

I’ll try to recreate this one it in a few ours and open a PR

1 Like

@fepitre here you go:

I tried to keep it as close as possible to the original (didn’t implement any of those changes discussed here – that will be done afterwards)

Some minor tweaks to the original:

  • replaced wifi card with ethernet jack (more recognizable)
  • Fixed typo: there were two appVMs name “AppVM 2”
  • replaced logo on the left of AppVM 1 (couldn’t recognize) with Thunderbird logo
  • centered text on sys-* qubes and AdminVM, GUI VM

Shall we also a github issue to address the whonix error described by @GWeck?

To address the sys-wohonix problem, the four green boxes at the right side might be ordered as follows:

Thanks @GWeck I’ve done just that, but had to recreate the whole file since it didn’t seem to be available in its original form.

The current version looks like this:

I also fixed the AppVM 3 numbering and opened an issue to track these changes to the docs:

Just noticed yet another problem on the diagram that needs fixing: AppVM 3 has Firefox as the browser, but it should be TorBrowser…

Shouldn’t the sys-net VM have a red color? It handles the untrusted networking. There is a reason IOMMU is used here to isolate the networking.

If the devs find it should then I’ll change it. Btw, parallel discussion happenning on the related github issue .

1 Like

Yes, sys-net should also be red.


Ok. Following up the conversation on the github issue.

Current diagram looks pretty good. One question I wanted to ask here is that we are going from red sys-net to green sys-firewall. Is it okay to consider sys-firewall green.

Yes, sys-firewall is green by default in Qubes. Basically, sys-firewall is responsible for enforcing your firewall rules. It’s not exposed and untrusted the way sys-net is.

Publishing here the final version that is now live on the website. Thank you all for the feedback and @GWeck for the ideas and for starting the discussion.