Add new glossary terms.

[0brand]

Referring to a Proxy or AppVM can be referring to a Standalone or TemplatebasedVM. Adding TemplateBased{ProxyVM,AppVM} is less ambiguous. Adding terms for anon-whonix and sys-whonix will help avoid confusion when referring to those VMs in documentation etc.

[andrewdavidwong]

Referring to a Proxy or AppVM can be referring to a Standalone or TemplatebasedVM. Adding TemplateBased{ProxyVM,AppVM} is less ambiguous.

Interesting. This is the first time I've seen the terms "TemplateBasedAppVM" and "TemplateBasedProxyVM." They make sense as terms, but I'm somewhat loathe to set the precedent of coining new terms in the glossary without prior use simply because they make sense. (We wouldn't want to coin the Cartesian product of all of our logically compatible terms just because they make sense.)

In practice, it's reasonable to assume that "AppVM" and "ProxyVM" denote TemplateBasedVMs unless otherwise specified.

Adding terms for anon-whonix and sys-whonix will help avoid confusion when referring to those VMs in documentation etc.

Those are names of particular VMs, not terms for types of VMs. The fact that they're created by default with those names makes it easy to confuse the two, but we must be careful not to. Notice that we don't have entries for sys-net or sys-firewall, which are even more common. Every user is free to rename these VMs at any time.

[adrelanos]

TemplateBasedAppVM and TemplateBasedProxyVM are being used in Whonix wiki.

• https://www.whonix.org/w/index.php?search=TemplateBasedAppVM
• https://www.whonix.org/w/index.php?search=TemplateBasedProxyVM

Remove Whonix-Gateway TemplateBasedProxyVMs explicitly only means TemplateBasedProxyVMs. Standalone ProxyVMs wouldn't be required to be removed.

Similar for TemplateBasedAppVMs. It's Remove Whonix-Workstation TemplateBasedAppVMs. It's not Remove all Whonix-Workstation AppVMs standalone or template based.

Perhaps we'll just add a space in between such as...

• TemplateBased ProxyVMs
• TemplateBased AppVMs

...?

The reason for this pull request, I think is, to avoid inventing multiple notations / terms for the very same thing, having these spread without any "official best notation" to reference and thereby avoiding any confusion from that.

[0brand]

Adding terms for anon-whonix and sys-whonix will help avoid confusion when referring to those VMs in documentation etc.

Those are names of particular VMs, not terms for types of VMs. The fact that they're created by default with those names makes it easy to confuse the two, but we must be careful not to. Notice that we don't have entries for sys-net or sys-firewall, which are even more common. Every user is free to rename these VMs at any time.

Yes, I see what you mean. Maybe mention anon-whonix and domain (personal or untrusted) in TemplateBasedAppVM definition, sys-whonix along sys-firewall in TemplateBasedProxyVM definition. Meaning just as examples of commonly referred-to VMs.

[woju]

To add confusion, terminology changed with R4.0. With R<=3.x, there were NetVMs and ProxyVMs which were distinct from AppVMs. Now sys-net, sys-firewall, sys-whonix (and any VPN qubes) are AppVMs with appropriate property set (provides_network). Same with HVMs, this is also a property (virt_mode).

TemplateVM, AppVM, StandaloneVM, DisposableVM and previously (< R4.0): NetVM, ProxyVM, HVM, TemplateHVM, are technical terms, because they are identifiers of qube type as understood by qubesd, qubes-manager and assorted tools. IOW "TemplateBasedSomethingVM" is confusing, since you cannot chose it when you create a qube. I think we have to be very precise with that.

Unfortunately the CamelCaseVM terminology was used liberally in the past, and it is not clear, what is a concept and what is actually configured. The fact that types changed in R4.0 is also confusing.

Instead of multiplying terms, can we just retain the actual types and maybe NetVM (there is actually a property netvm) and ProxyVM (since it is widely used), with clear distinction, what applies to which (supported) Qubes release?

[woju]

This is tautology. There are no AppVMs that are not based on TemplateVMs, and in R4.0 anything that is based on TemplateVM is AppVM.

[andrewdavidwong]

This is tautology. There are no AppVMs that are not based on TemplateVMs,

Not according to the current official definition: "Application Virtual Machine. A VM that is intended for running software applications. Typically a TemplateBasedVM, but may be a StandaloneVM. Never a TemplateVM."

and in R4.0 anything that is based on TemplateVM is AppVM.

That's conflating AppVMs with TemplateBasedVMs. As the definition above shows, "AppVM" originally meant "VM for running applications" (hence the "App" part), regardless of whether it's standalone or based on a template. If this conflation was enforced in code beginning with 4.0, then that was a mistake.

[woju]

Same. Even in R3.x all ProxyVMs were based on TemplateVMs, and there are no ProxyVMs in R4.0.

[woju]

@andrewdavidwong:

(We wouldn't want to coin the Cartesian product of all of our logically compatible terms just because they make sense.)

The funny thing is, that was the case in <R4.0 with HVMs. Now we have properties: virt_mode and provides_network, and qube can be either TemplateVM, StandaloneVM, or "something based on template", which is now AppVM (or "TemplateBasedThing", as the proposal has it). That was multipled by hvm and for non-hvm they AppVM was multiplied by network position. Thank God no-one wanted to make network-oriented vms from StandaloneVMs or HVMs, or DispVMs.

I'm not at all surprised people feel need for "TemplateBased". But now this is just called AppVM. And DispVMs have AppVMs as template, which is another reason I'd avoid this term.

[andrewdavidwong]

"something based on template", which is now AppVM

I'm not at all surprised people feel need for "TemplateBased". But now this is just called AppVM.

This is bad, because it conflates two distinct, important concepts:

• The VMs in which users should run their programs and store their data (AppVMs) versus those they should not (TemplateVMs; to a lesser extent, NetVMs, ProxyVMs, etc.)
• VMs that provide (part of) a filesystem to another VM (TemplateVMs) versus those that do not (TemplateBasedVMs)

Since it's important for security that users do not run programs in the wrong places in Qubes, the fact that "App" stands for "Application" is actually important. Conflating this with the concept of being based on a template implies that it's okay to treat every TemplateBasedVM like an AppVM and vice versa (i.e., run whatever programs you want there).

It also leads to strange results. For example, it follows that all NetVMs are AppVMs in 4.0.

there are no ProxyVMs in R4.0.

Is there no sys-firewall in 4.0? Is it not a FirewallVM, which is a type of ProxyVM?

[woju]

It also leads to strange results. For example, it follows that all NetVMs are AppVMs in 4.0.

That's correct. Let me explain the implementation and reasons for it below.

* The VMs in which users should run their programs and store their data (AppVMs) versus those they should not (TemplateVMs; to a lesser extent, NetVMs, ProxyVMs, etc.)

It is perfectly fine to run applications in sys-net, sys-firewall, sys-usb as long as it is the correct place to run this "something". For sys-net that would be low-level network software like nmap. For sys-firewall that may be VPN (although VPN might also be run in another "ProxyVM" qube). sys-usb is a good example, because in R3.x it is unknown, what it should be: NetVM, ProxyVM or AppVM, because the answer depended on whether user intended to plug network adapters (USB modems) and if so, what is the network topology around the physical machine (for examples see https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html). So we settled for ProxyVM there "just in case", though this is probably unneeded for some people.

R4.0 sys-whonix is also AppVM. From toolstack POV whonix/tor is just another network app, kind of VPN if you prefer.

dom0% qvm-ls | fgrep sys-whonix
sys-whonix  Running  AppVM  black  whonix-gw  sys-firewall

As part of R4.0 the VM types were reduced, because that Cartesian product was both baroque and constraining.

1. The HVM axis was flattened to a property (now called virt_mode because there is also PVH, which is later addition), because there is not much difference from the distro/template and in fact it is possible to have major templates (fedora/debian) bootable in either mode. The previous type system allowed HVMs to based on HVM templates only, and there is no reason for that (in R4.0 it is possible to boot template in PV(H) and qubes based on in in HVM virt_mode or vice-versa).
2. The network subsystem was also flattened. The problem with networking in Qubes OS is it's asymmetry: uplink is different than downlink. The qube might have either zero or one uplink and arbitrary number of downlinks. In R4 this is decided by two properties: netvm which choses uplink (may be None, which covers zero uplinks) and provides_network which is boolean choice whether it should be an option as a netvm choice for other VMs. But in R3.x this was three types:

• NetVM, which has zero uplinks and can be chosen as netvm
• ProxyVM which has one uplink and can be choses as netvm
• AppVM which has one uplink and cannot be chosen as netvm.

They all were PV domains based on template, which was problematic for unikernel-based firewalls which might require HVM virt_mode. Again, there was no difference from template POV and as you may notice, that would all be perfectly served by ProxyVM, whose netvm property may also be nulled, with the side effect that any qube would appear as a choice for netvm in Qubes Manager drop-down menu.
So AppVM in R4.0 is technically R3 ProxyVM with additional option to prevent it from being chosen as someone's netvm.

It is not possible to change qube type (only viable solution is to clone a VM to another type, which may be tricky). As mentioned, sys-usb is a unknown thing, which might require changing it's place in network topology. So that was a limitation.

The comprehensive list of all R4.0 VM types is here: https://github.com/QubesOS/qubes-core-admin/blob/af7d54d3883505401ecf0a26567ae699877520e5/setup.py#L62-L66 and they are documented: https://dev.qubes-os.org/projects/core-admin/en/latest/qubes-vm/index.html#particular-vm-classes. All other CamelCaseVMs are not VM types, in that you cannot choose it as VM type in Qubes Manager when creating a VM.

One paragraph about DispVMs. DispVMs are also "based on templates", like AppVMs they also have template property, but unlike AppVM, in which template points to TemplateVM, DispVM's template points to AppVM. This is important for "features", which have operation "check_with_template" (see "CheckWithTemplate" in Admin API). That operation runs recursively on template property, so that means "first check me (DispVM), then my AppVM, then my AppVM's TemplateVM, then give up". Any VM can also have dispvm_template property, which points to AppVM, which will be template for any DispVM spawned.

there are no ProxyVMs in R4.0.

Is there no sys-firewall in 4.0? Is it not a FirewallVM, which is a type of ProxyVM?

sys-firewall is an AppVM with the property provides_network set true. If you'd like to create qube for VPN, you choose "AppVM" in the UI (which is the default), or "StandaloneVM" if you prefer. Then proceed to flip provides_network to True. That's what I meant by "there are no ProxyVMs in R4". In R3.x you actually had to pick ProxyVM, otherwise it either couldn't be connected to upstream network or couldn't be choses as network provider for its intended downstream. If you chose wrong, you had to start over with new qube. There was no property you could edit to correct the mistake.

To reiterate, AppVM is a VM type/class. FirewallVM, ProxyVM, NetVM are ideas, which have historical foundations:

• ProxyVM and NetVM were VM types in <= R3.2.
• netvm and firewallvm (all lower-case) were default VM names for what is now called sys-net and sys-firewall. They sometimes were written capitalized, though there was never a FirewallVM class.

I'd like to make this distinction to avoid questions of "how do I choose FirewallVM in QubesManager".

This double terminology is something we have to suffer at least until R3.2 EOL, which IIRC is end of March 2019.

I understand TemplateBasedVMs as an invented term that lowers the learning curve in R3, but makes it hard to transition to R4. Especially when one tries to understand DispVM. Are they TemplateBased or not? If so, they surely must be based on TemplateVMs? Well, yes and no. Transitively yes, directly no. Their template is AppVM, which is also TemplateBased, now truly on TemplateVM.

I hope I made that sufficiently understandable. If there is something not clear, please do ask. If you'd like to cut and edit for some explainer in qubes-doc, feel free.

[marmarek]

The problem with AppVM VM class is that its name is about function ("place where you run applications"), while technically its real meaning is "VM based on TemplateVM". In many cases this is the same, but not all the cases (as you pointed out). StandaloneVM is also "a place where you run applications". TemplateBasedVM would be slightly better, but then DispVM (which we should really name DisposableVM, see #2671) would be more confusing, because it would be a VM with a template being TemplateBasedVM... But I agree the AppVM name as it is now in R4.0 (and also in R3.x to some extend) is inaccurate.

NetVM/ProxyVM case @woju described accurately - this is something technically gone in R4.0 (where it's just a provides_network property). If we keep those terms, they will be purely artificial, and may lead to confusion (like "I've created ProxyVM, but qvm-ls list it as AppVM!"). If we want to still use such terms in documentation, we should clearly describe that those are just abstract, short terms for "VM with provides_network property set to true". In this spirit, I don't think adding TemplateBased{Proxy,Net}VM makes sense. Rather than that, I'd add that R3.x had limitation that ProxyVM/NetVM need to be based on a template, but this limitation is gone in R4.0.

[0brand]

NetVM/ProxyVM case @woju described accurately - this is something technically gone in R4.0 (where it's just a provides_network property). If we keep those terms, they will be purely artificial, and may lead to confusion (like "I've created ProxyVM, but qvm-ls list it as AppVM!")

Keeping those terms may lead to confusion. However, removing them will likely lead confusions. They might not be the "proper" technical terminology but its what users are comfortable using i.e. easily understood by less experienced users and more experienced alike. This almost seem like trying to fix something thats not broken IMHO.

[andrewdavidwong]

Either way, it will need to be explained. Either the explanation is that NetVMs and ProxyVMs (as previously defined) no longer exist in 4.0, or the explanation is that the definitions of the terms "NetVM" and "ProxyVM" have changed in 4.0. It's not obvious to me which option will be less confusing to people than the other.

Either way, this is a major user-facing change that should have been announced concurrently with the 4.0 release, IMHO.

Edit: Ok, to be fair, it looks like we explained it here, though the explanation could have been clearer and wasn't repeated in the 4.0 announcement.

[andrewdavidwong]

After thinking about it a bit more, it would probably be simpler just to keep one definition for each term (the old definition), and say that NetVMs and ProxyVMs no longer exist in 4.0. Otherwise, we'll have to make clarifications like, "ProxyVM... No, I mean ProxyVM in the old 3.x sense." Term reuse leads to trouble.

[andrewdavidwong]

Closing this for now due to the prolonged lack of activity. If you believe this is a mistake, or if anyone would like this PR to remain open, please leave a comment, and we'll be happy to reopen this. Thank you.