Proposal to differentiate admin server from admin client

[RandyTheOtter]

Qubes OS jargon is missing a good distinction between a qube that serves
administrative facilities and a qube that wants to access them.
It is proposed to use "admin qube" and "admin client qube" to refer to them,
respectively.

A pull request containing proposed (and some distantly related...) changes
have been published to the documentation repository. More specifically, commit
https://github.com/QubesOS/qubes-doc/pull/1728/commits/d889ac6ae4373547cdb1c228cdfa98adc8a73085 .

Pull request itself:
https://github.com/QubesOS/qubes-doc/pull/1728

As the idea have been first described and discussed on the forum I'll leave the
details out, for the reader to examine on their own. A decent place to start
is: https://forum.qubes-os.org/t/terminology-admin-qube-adminvm/42462/7

In summary, "admin qube", in light of deprecated but still referred to term
"AdminVM" is mildly ambiguous about referring to class (klass) vs role.
"Admin client qube" is meant to clarify the ambiguity by being dissimilar from
"AdminVM", opposing "admin qube" in meaning, and pointing to the distinguishing
feature of an admin service consumer in the name.

Opposition is concerned by the confusion that introduction of the new term
might cause.

Please share your thoughts regarding this.

p.s.
Personally, I'm neutral - as much as I believe that the proposed arrangement is
superior, I also trust unman's judgement. As long as we end up with a way
to clarify the glossary it's all good.

[unman]

Thanks Randy, that is a good summary.

For those not following the Forum I provide the opposition. I
introduced the term "admin qube" in the glossary in place of the outdated
AdminVM, in line with every other effort to use "qube" as a standard
user term.

I believe that "admin qube" is clear to users - it is a qube used for
administration. (It is descriptive - a qube can be an admin qube and
provide other services: it could also be sys-net, sys-firewall or any
other pre-existing qube, or it can be a qube dedicated to the task.)

I think that "admin client qube" is unclear: most users would
understand this to be a qube that is a client of an admin qube, if they
understand it at all. But the proposed use would have it refer to a qube
used for administration. How would you refer to clients of that qube?
admin client client qube?

AdminVM remains as the name of a klass, as DispVM, TemplateVM etc. It
should be deprecated in normal use and replaced by "admin qube".
Currently the only qube of Klass AdminVM is dom0, but MANY qubes can
serve as admin qubes.

There is a separate issue whether we want to keep the separate terms "admin
qube" and "management qube". (The latter is often used in connection
with salt and ansible: I personally find the distinction useful.)

[Simon Gaiser]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

'RandyTheOtter' via qubes-devel, 2026-07-15 02:42 +02:00:

Hmm, without reading the full discussion there I would have more or less
said the same as rustybird in [1]. With the addition that "AdminVM", or
adapted to the "qube" terminology "admin qube", was/is intended as a
non-Xen-specific term for the almighty [2] dom0/host/... compartment.

But as the forum discussion shows, other developers might not agree.
Frederic used it differently in the linked post, although possibly
ad-hoc without intending to create the confusion. If I understand
unman's posts correctly they are actively in favor of using "admin qube"
as in "qubes calling the Admin API".

As has been already written in the discussion by others, I think the
main usage so far has been management VM/qube. And yes the this term
partially collides with the management_dispvm property used by
Salt/Ansible. Although the usage is actually not that different, since
there too the disposable has admin access to the managed qube. But in
this case it's about running code in-side the qube, not Admin API
access.

I see how "admin qubes/VM", might be a natural choice for the
"management by" case. But I dislike the discrepancy with the previous
use as "dom0/host qube" in general and in particular the VM class.

Regarding naming "qube that uses Admin API" I would also like to point
out that this can be used [3] very differently. It can mean effectively
full control over a set of VMs, or it might be a much more limited
access. So it would be good to clarify what cases you mean here
(possibly all).

[1]: https://forum.qubes-os.org/t/terminology-admin-qube-adminvm/42462/4
[2]: Yes, I'm aware that in the future it might be technically not
almighty, but I'm intentionally ignoring that here.
[3]: or you should be able to use it (currently there's some limitation
on what policies you can express)

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEE3E8ezGzG3N1CTQ//kO9xfO/xly8FAmpXXOYACgkQkO9xfO/x
ly8hdw//SoSog4slqiU/qkNmnTIFWo6iK9fww5HaVyW1tSSo5xuqyAzEgmig2Ztx
JBO1+fZxpybkCUvK+Ar8xCr6y8q2TdFhxZRUXhXF9Mtf8/IwY8UGBLfS34BRoEjg
m3qxwi1PgOebBxL+8eT7tRcA8FO54CWugyNn+3GxNo51sO3EzJN5jTM98ou6b3rH
mjBQy1M0CZzKnmgECiUU/2sHwXLqZHCxtozJjGS3dGlre5wUA4sLlb4RxleBcylp
DPLD1CzcycLRlc9JhnUCtFRjbXrSk24FEduqcrEwkuzyZ4KVG5cd/Edbqc1s7lFD
VzZJ8tYdyOpJbV2SnbFTMkByDnYzLQq8rKPTykFXasRLmYhrGBSC24vKbnrmohg9
cyNOn/IdREaoGPbDS1jjenzI/XJ6H8hhZsLcwRWq+ZdHl6tJf85GLwEaJwC/K45G
llRqOnXzujV3nWK6AHkJhiqlM9KVi1AVzbWDtSkJdJgqRn3RHOMQSrJHy35I0y1y
yy0V2kMNQWRFURXRsc0quTxlA1jNgR5jxH5rMnkXLpPCKVs8pfVJq5th1CrZ+C2G
cVKQTYINtmAHJqReoxKMYlG0gFXzYSaQG30NKdVrprAOv32ejwjbfEef+6ezm4xa
OIed64tIoBpZdGjuXvWgrqABPbj7Ic86jbSKCNXULs8MQxktg3Y=
=WWFB
-----END PGP SIGNATURE-----

[Simon Gaiser]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

'unman' via qubes-devel, 2026-07-15 12:06 +02:00:

Sorry, I sent my other mail before seeing your's. As I wrote there, the
original use is/was meant differently. Namely "the qube that has full
administrative control over the system", which under Xen is dom0. If
moving to the usage you propose, I think we need a new term for the old
usage.

In your proposed usage, would a qube that uses the Admin API for limited
access (for example read-only access or backup.execute) be a "admin
qube"?

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEE3E8ezGzG3N1CTQ//kO9xfO/xly8FAmpXYJcACgkQkO9xfO/x
ly9+zg/+JJeTklRFGcrmPgX4NNgwUaYzNrJPS9Gm7/kC1Iew1Yu1nGmBkOola9aW
tKacV9IguBfLwOLcghadK/ICSyaNAaR2X2VJT4Ohj8s6MV12Zkw2f2yF0WVZLjMQ
xoI9oom5gJ/HUnR8qkRrleNuD4tt8k6UwOyVPbKA1Xcg6eKMln/KaPYQUrhjbWS0
yYMPX2ANKlCLSsMuG6v8yyy4uzP+9kj3CJ/EpCJE7e3gCWqqyEneuluAg5kFSBJd
d8v27xWojNPwap/xUNbpD+uUApvCjA5fdc77MXvV+0GElvjoAUSql0GqIlzydc1g
hn6XDgGHc1rbrjA2JCxmlyHxLQdpU2L1Z6f1BzAcaW5VM/SKHgazPfuM57R1qJaF
3aixbCS920/TzwVGITNgTvIhvbUV3IqbmXml1w2eGVe8fXQ4Px0n7v8ZDcz1X7w5
G6QZ2WqGnrxM8LqFKrx7jEeDBWnn2D2nwyglo7uZUJ0+v6E4wwOUqYrihtQszf0m
7mNYY64mBtuBv3ruhOkaVfeZuUsAx4S6OHcn+SBFyXB2q1NCVcYjrtPYN4EO12kq
cIYSrs0yfd22euRXBlwe2FuR3fzgeZEZEqndrb8m64g1Oa3WQVDUsaSdDmr8t2U1
gSnJ0vrEg+XcjyYTu2IkbEURbMbj411CUrrjco0jfeXD/LBOgaU=
=aSGy
-----END PGP SIGNATURE-----

[unman]

On Wed, Jul 15, 2026 at 12:28:23PM +0200, Simon Gaiser wrote:
> Sorry, I sent my other mail before seeing your's. As I wrote there, the
> original use is/was meant differently. Namely "the qube that has full
> administrative control over the system", which under Xen is dom0. If
> moving to the usage you propose, I think we need a new term for the old
> usage.

Perhaps we do. But this is user facing documentation, and there is no
requirement that an admin qube (or whatever term is used) has FULL
administrative control over EVERYTHING. It may have limited control over
some set of qubes. This was clearly set out in the introductory post
back in 2017 - "the main concept behind the Admin API is to let
select VMs preform various select administrative functions over the
Qubes OS system." The post was aimed at "admins", and it seems natural
to me to describe the qubes they use to administer the system as "admin
qubes".

>
> In your proposed usage, would a qube that uses the Admin API for limited
> access (for example read-only access or backup.execute) be a "admin
> qube"?

Yes.

The fact is that in posts and discussions AdminVM was being used to
cover cases not including dom0, as you have noted. We already see sys-gui
where administration can be done. Our policy has been to remove use of
"VM" and replace it with "qube". Thus in the documentation and user facing
discussion we should use "admin qube".

I have no issue with retaining AdminVM as a class name, @adminvm in
policies, AdminVM in code &c. We already see a divide between user and
technical documentation. We're concerned here with helping users
best understand what can be done. Admin qube seems a natural fit to me.

As I said, I find the distinction between admin qube and management qube
useful in explaining qubes and in setting up systems. I'd prefer to park
THAT discussion.

[Simon Gaiser]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

unman, 2026-07-15 13:27 +02:00:

> On Wed, Jul 15, 2026 at 12:28:23PM +0200, Simon Gaiser wrote:
>> Sorry, I sent my other mail before seeing your's. As I wrote there, the
>> original use is/was meant differently. Namely "the qube that has full
>> administrative control over the system", which under Xen is dom0. If
>> moving to the usage you propose, I think we need a new term for the old
>> usage.
>
> Perhaps we do. But this is user facing documentation, and there is no
> requirement that an admin qube (or whatever term is used) has FULL
> administrative control over EVERYTHING. It may have limited control over
> some set of qubes. This was clearly set out in the introductory post
> back in 2017 - "the main concept behind the Admin API is to let
> select VMs preform various select administrative functions over the
> Qubes OS system." The post was aimed at "admins", and it seems natural
> to me to describe the qubes they use to administer the system as "admin
> qubes".

We are talking about [3], right? It seems you misunderstood my point
above. I'm not talking about a special name for a qube with Admin API
access that happens to allow everything. I'm talking about a
non-Xen-specific term for the VM/domain/compartment that inherently has
full access [4]. Under Xen that's dom0, under KVM that would be the host
kernel+userspace (so the place where the Admin API calls are actually
executed).

That blog post used AdminVM for this meaning. And management/GUI VM for
the example cases of qubes that call the Admin API (which is what you
would like admin qube to mean).

While "user facing" documentation certainly can skip some details or
simplify things, I think we should avoid contradictory terms. Since
effectively VM == qube, I think having AdminVM (the class) and @adminvm
(the policy keyword) meaning something quite different is problematic.

If we would just introduce a new term without that existing usage, I
would agree that "admin qube" is a natural choice.

[3]: https://www.qubes-os.org/news/2017/06/27/qubes-admin-api/
[4]: Again, I'm ignoring that this might be not quite true in the
future in some locked down configurations.

>> In your proposed usage, would a qube that uses the Admin API for limited
>> access (for example read-only access or backup.execute) be a "admin
>> qube"?
>
> Yes.
>
> The fact is that in posts and discussions AdminVM was being used to
> cover cases not including dom0, as you have noted. We already see sys-gui
> where administration can be done. Our policy has been to remove use of
> "VM" and replace it with "qube". Thus in the documentation and user facing
> discussion we should use "admin qube".
>
> I have no issue with retaining AdminVM as a class name, @adminvm in
> policies, AdminVM in code &c. We already see a divide between user and
> technical documentation. We're concerned here with helping users
> best understand what can be done. Admin qube seems a natural fit to me.
>
> As I said, I find the distinction between admin qube and management qube
> useful in explaining qubes and in setting up systems. I'd prefer to park
> THAT discussion.

With "management qube" you mean here exclusively the disposable qubes
used for Ansible/Salt, right? Unlike the usage mentioned above.

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEE3E8ezGzG3N1CTQ//kO9xfO/xly8FAmpXhRoACgkQkO9xfO/x
ly96SxAAiC4wj98di3Hskd95aIZ4+kbUsuQQlumFKMJZDi0IRbjn9nPOn6480JGt
y/z3CrnfzjobEIjGm03ePGFsCl51fzSaOwmVbsv9ff6/8lNGMw7x9Qifo1/XcybW
jaItN1XEtXIZCY7vWzNst2vlZaoSNjfTNmPNx4yLlHRN2wL7BjtuDEDH4BBdLoOw
NJN5iMHFkFj6eYtUWGF/1jnQH8WPdwO7Oo3ezbzviWIudS+COZULd5BvI3wrxCcH
W1ngt+bSC9GuAfi+T08ujj02toCbLQ72M83tWOltgP4mxUn6+wahsWw7v5WDYz3s
TV1mNWuixCbucikZ6QNpjT1qxg1sU9fLsN4oIxK2jjctEW7cP4HaiD8jPu21feMX
TnG8VfFpovqab0FY9DEJLfRCnE0cLz3NGBGSrJmfHuo2bCniX+SxWLbN+XTHH5qg
q0jM5X/veeLblPmm9XQS6fU1EPrVMKWosmnm4sC+6eyqsWSEiQuG+k4suR39zfpo
aARcTHe4Sc0MjOK/L11VUbsVuMcQqhiyI7H3P8GYZwib0NptwUf4d3sWRNgQfEle
Zm2rYXUhITtF7b5tQh2AoZ4MK1t3TgiVJ8KOc1rHOfYZyTcWPXc0MUZ/+k3fRQ/Y
K/VweQZI3nBke0zTmUJKp70LDFlrt+3K91rzNC1AUa7cblaMpZ4=
=TIvc
-----END PGP SIGNATURE-----

[unman]

On Wed, Jul 15, 2026 at 03:05:09PM +0200, Simon Gaiser wrote:
<snip>

> We are talking about [3], right? It seems you misunderstood my point
> above. I'm not talking about a special name for a qube with Admin API
> access that happens to allow everything. I'm talking about a
> non-Xen-specific term for the VM/domain/compartment that inherently has
> full access [4]. Under Xen that's dom0, under KVM that would be the host
> kernel+userspace (so the place where the Admin API calls are actually
> executed).
>
> That blog post used AdminVM for this meaning. And management/GUI VM for
> the example cases of qubes that call the Admin API (which is what you
> would like admin qube to mean).
>
> While "user facing" documentation certainly can skip some details or
> simplify things, I think we should avoid contradictory terms. Since
> effectively VM == qube, I think having AdminVM (the class) and @adminvm
> (the policy keyword) meaning something quite different is problematic.

I dont think I did misunderstand your point, and I understand what was
in the blog post. What I am talking about is how the terms have developed
and what we should do with them now.
Unlike you, I am unconcerned by what you describe as "contradictory
terms". It takes a few seconds to explain what is an "admin qube", and
perhaps a klass called AdminVM, and a term @adminvm used in policies. If
you want to say these are contradictory terms, fine, but in use they
are not contradictory. That is, users can just rub along with them as
they are.

Very often in Qubes, we seem to be concerned with HOW things are done,
the plumbing, when users are concerned with the outcome. I find admin
qube a natural term to use, and the people I work with seem to be able
to use it also without confusion.

> If we would just introduce a new term without that existing usage, I
> would agree that "admin qube" is a natural choice.

Agreed.

> With "management qube" you mean here exclusively the disposable qubes
> used for Ansible/Salt, right? Unlike the usage mentioned above.

No.I mean the qubes used for management with salt or ansible.
As I say, I find the distinction useful when talking to end users, and it doesnt
seem to cause confusion. (These are NOT exclusive terms)

unman

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

I think I'm with unman on this one. I have an impression the term "admin
qube" is already quite often confused as a qube that can do
administrative actions via Admin API. So, adjusting this term may even
reduce confusion. But yes, it would in practice be the first instance
where we break with direct translation VM -> qube, because I suppose
AdminVM would (at least at the code level) still mean dom0. In practice,
the adjustment isn't that big, because non-dom0 admin qubes are still
rare, so dom0 is both AdminVM and (the only) admin qube in most systems.
Now we can "simply" clarify the distinction.

Even in our glossary, "admin qube" is defined[1] as:

A type of qube used for administering Qubes OS. In the default
install, the only admin qube is dom0.

Which already suggests there may be more of them.

Eventually dom0 could gain some new term, maybe something like "host qube"
(borrowing from KVM, and already used in few places like qubes builder)?

There is also one case where I have a vague idea for @adminvm policy
term to reference "admin qube" - specifically for remote qube. A policy
like "admin.something * some-local-admin-qube some-remote-qube allow
target=@adminvm" could mean redirecting to a _remote_ admin qube that
can manage that qube. This idea is very vague for now (together with
anything related to managing remote qubes), and maybe completely wrong,
but kinda related to evolution of the term AdminVM/Admin qube.

Anyway, (kinda) changing meaning of an existing term is a risky thing
to do. Personally, I think this one may clarify things in the long run,
but maybe others have better ideas?

[1] https://doc.qubes-os.org/en/latest/user/reference/glossary.html#term-admin-qube

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmpXn84ACgkQ24/THMrX
1yzFggf/aSG/EDHEglv+2l1czWevFxnwzFes4TUHFL3CBecUT1iMXQeYrLRiCP0J
et4zzl+pwtf/RGqCy9y3vB3xkPDhkKEtgm05/V+vzqbND0zZOxDQHclU/Aw0/Yu4
OSThSudvCDAHDNAvib56CzFonv0kT2Z+ArxAyDZx50eD5EOvLRgmlH1RbLaav1od
8QVdtJG5dSZpHXPHbdZNjCbG4CtHfb9ODXZiHuz2bJyyHKudsNiN4AI8UEOlB/PY
4p0e4mfpn8fzyNOdZ7AjnxIwgbrX3tDe+BlEdk5RkgmH3mASb8YSkAYeZdW3dyxG
b+4YLObHYQdGMDZVAHPSGrSVBTmlwQ==
=zj3C
-----END PGP SIGNATURE-----

[Simon Gaiser]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

Marek Marczykowski-Górecki, 2026-07-15 16:57 +02:00:

> On Wed, Jul 15, 2026 at 03:10:35PM +0100, 'unman' via qubes-devel wrote:
>> On Wed, Jul 15, 2026 at 03:05:09PM +0200, Simon Gaiser wrote:
>> <snip>
>>> We are talking about [3], right? It seems you misunderstood my point
>>> above. I'm not talking about a special name for a qube with Admin API
>>> access that happens to allow everything. I'm talking about a
>>> non-Xen-specific term for the VM/domain/compartment that inherently has
>>> full access [4]. Under Xen that's dom0, under KVM that would be the host
>>> kernel+userspace (so the place where the Admin API calls are actually
>>> executed).
>>>
>>> That blog post used AdminVM for this meaning. And management/GUI VM for
>>> the example cases of qubes that call the Admin API (which is what you
>>> would like admin qube to mean).
>>>
>>> While "user facing" documentation certainly can skip some details or
>>> simplify things, I think we should avoid contradictory terms. Since
>>> effectively VM == qube, I think having AdminVM (the class) and @adminvm
>>> (the policy keyword) meaning something quite different is problematic.
>
>> I dont think I did misunderstand your point, and I understand what was
>> in the blog post.

In the snip-ed quote you wrote

[...] there is no requirement that an admin qube (or whatever term

is used) has FULL administrative control over EVERYTHING.

but for the "dom0(-equivalent)" usage of the term, this doesn't make
sense. That's what I was responding to here.

>> What I am talking about is how the terms have developed
>> and what we should do with them now.
>> Unlike you, I am unconcerned by what you describe as "contradictory
>> terms". It takes a few seconds to explain what is an "admin qube", and
>> perhaps a klass called AdminVM, and a term @adminvm used in policies. If
>> you want to say these are contradictory terms, fine, but in use they
>> are not contradictory. That is, users can just rub along with them as
>> they are.

So if we have a policy like:

admin.vm.List * test-mon @anyvm allow target=@adminvm

You would need so say something like: "This allows the test-mon admin
qube to call the admin.vm.List qubes-rpc for any qubes and redirects it
to the admin qube, since Admin API calls are executed by it." Where the
first "admin qube" means "a qube that uses the Admin API" and the second
"admin qube" means "dom0(-equivalent)".

>> Very often in Qubes, we seem to be concerned with HOW things are done,
>> the plumbing, when users are concerned with the outcome. I find admin
>> qube a natural term to use, and the people I work with seem to be able
>> to use it also without confusion.

Yes, I think the terminology should also work to describe the
"plumbing". There is no clear user/dev split. Depending on what a users
wants to do and what experience they have, they will quickly come into
contact with the "plumbing". (And people messing with the Admin API are
certainly in the advanced user category.)

Similarly when writing QSBs the technical details are also relevant, so
there too we need terminology that also works when describing the
"plumbing".

>>> If we would just introduce a new term without that existing usage, I
>>> would agree that "admin qube" is a natural choice.
>
>> Agreed.
>
> I think I'm with unman on this one. I have an impression the term "admin
> qube" is already quite often confused as a qube that can do
> administrative actions via Admin API. So, adjusting this term may even
> reduce confusion.

Ok, we can of course actively drop the previous meaning. But that's a
bit different than my impression of unman's first email in this thread,
that didn't even mentioned the dom0(-equivalent) meaning that was the
original use of "AdminVM" (and since that was before "VM" -> " qube",
implicitly also "admin qube").

> But yes, it would in practice be the first instance where we break
> with direct translation VM -> qube, because I suppose AdminVM would
> (at least at the code level) still mean dom0.

I'm in general fine with intentionally changing the meaning, it's this
part that I dislike.

I think then we should seriously consider to also change the "AdminVM"
class and the "@adminvm" keyword (with some compatibility alias where
needed).

> In practice, the adjustment isn't that big, because non-dom0 admin
> qubes are still rare, so dom0 is both AdminVM and (the only) admin
> qube in most systems. Now we can "simply" clarify the distinction.
>
> Even in our glossary, "admin qube" is defined[1] as:
>
> A type of qube used for administering Qubes OS. In the default
> install, the only admin qube is dom0.
>
> Which already suggests there may be more of them.

Yes, as I acknowledged in my initial mail we also have got the "Admin
API user" meaning used in some cases, by now. So the problem is already
there anyway.

> Eventually dom0 could gain some new term, maybe something like "host qube"
> (borrowing from KVM, and already used in few places like qubes builder)?
>
> There is also one case where I have a vague idea for @adminvm policy
> term to reference "admin qube" - specifically for remote qube. A policy
> like "admin.something * some-local-admin-qube some-remote-qube allow
> target=@adminvm" could mean redirecting to a _remote_ admin qube that
> can manage that qube. This idea is very vague for now (together with
> anything related to managing remote qubes), and maybe completely wrong,
> but kinda related to evolution of the term AdminVM/Admin qube.

But in that case the call gets logically redirected to the remote dom0
("host qube" or on whatever we settle on). Sure internally it is
relayed/proxied, but not sure "@adminvm" is a good description assuming
we drop the dom0 meaning of "admin qube". "@hostqube" that automatically
means the remote one for remote VMs or an explicit "@remotehostqube" (or
"@remote:hostqube", ...) sounds more fitting. But yeah, since this is,
at this point, speculative, a bit hard to say what exactly will fit the
implementation later.

> Anyway, (kinda) changing meaning of an existing term is a risky thing
> to do. Personally, I think this one may clarify things in the long run,
> but maybe others have better ideas?

I might not have expressed this clearly before, so to be clear: I'm not
per-se objecting to change the meaning, but my concerns is that we then
properly need to consider the previous use and ideally clean up things.

> [1] https://doc.qubes-os.org/en/latest/user/reference/glossary.html#term-admin-qube

-----BEGIN PGP SIGNATURE-----

iQIzBAEBCgAdFiEE3E8ezGzG3N1CTQ//kO9xfO/xly8FAmpXr08ACgkQkO9xfO/x
ly9VehAApszaQfbIFthJg05LYIssOyf45Y+oeCCk9XOtCUfMzFOK9KnMaGZqekN6
kFR2wtG3109Sg3W+oDkPDr5tvsK1/GJmBXFB2IohdEjiYe+yPRyoihwdkCSdOSCD
CSDBnbrIPUwTexTLAIxoW3q6cSILTtQhJGqdcyTeUUT8k8+Bn4pshnDunGhfSfCZ
HsiODOMAaNPjop5NrPWbFksAdqNacIpw0nSRxZDQ9RiRaNhsffuSUqDocDSQCiqx
3e+eyNOMkVcII1HwelOI/rB3oEJff5Qg0JqeqgyX3xfz3zhyxXZLk6OPilGW8utv
cEu4+Osh/fp/lvQkYrhLwXIgJRIxnCPIhIfrg36GDJY3o9RdW2RkeUuw4N12m7zA
AU/LNnn65+TEfdNExsByMGuOrL2R/qKYtSadaNmmfE2jnxx6rZPc3zv0JXFINVGE
8bO9thJsYle24sVeIgrkyb4eRZdy/+qMX/IELpg39Qnx1taaeGzTjnrQ6KO2v/mh
EST8hhVHeKBQFJk7fr50x9n9dDEu4L/uocQsIFkHYvuoHnaeNvOkr0ff2ZxGStrM
6FHwnIuy6HfnvbY0Keqak6HLa3X0ButwX7ZtODHAjb3q39kiLqccRQy7vCmzU7up
+/TlKjYDWoxKz4nps+K4nvUDIIn/8oggHGNq7no+886gb6OcoAY=
=UgTq
-----END PGP SIGNATURE-----

[Ben Grande]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Now that you put it in a phrase, I find the repetition of just "admin
qube" quite confusing. I have to admit that it also took me some time to
discover that AdminVM was just "dom0", because I read elsewhere multiple
times people referring to it wrong, most likely also unknowingly.

This is why I think the distinction is important, if we don't have a
concise term to use to distinguish between the "super qube/host qube"
from the less privileged but with some ACLs allowing the qube to call
"root/super user" RPCs, this mess will continue.

I'm also in favor of that, with a migration period, this might not be a
breaking change if we support multiple terms such as "AdminVM" and
HostVM" (which not be a VM..., so maybe "Host") at the same time. Better
described below.

> > In practice, the adjustment isn't that big, because non-dom0 admin
> > qubes are still rare, so dom0 is both AdminVM and (the only) admin
> > qube in most systems. Now we can "simply" clarify the distinction.
> >
> > Even in our glossary, "admin qube" is defined[1] as:
> >
> > A type of qube used for administering Qubes OS. In the default
> > install, the only admin qube is dom0.
> >
> > Which already suggests there may be more of them.
>
> Yes, as I acknowledged in my initial mail we also have got the "Admin
> API user" meaning used in some cases, by now. So the problem is already
> there anyway.
>
> > Eventually dom0 could gain some new term, maybe something like "host qube"
> > (borrowing from KVM, and already used in few places like qubes builder)?

That would require internals supporting all terminologies, simultaneously
for a certain period, to ease the migration and not be a sudden breaking
change:

- - a Qrexec policy, with support both terms for some time, @adminvm and
@host, @type:AdminVM and @type:Host;
- - updating server and client to support AdminVM and Host.

On one hand, I think that clear things up. On the other hand, I don't
think the glossary PR should be blocked until we get the internals
right, because them for all this time, we will have no better and
official way of distinguishing these qubes/roles. I think that we can
start with this gist where the text will be improved by Randy:

host qube

Text about it being the ultimate privileged qube with full
system control (Qrexec cannot deny it's calls). There can
only be one of those per system. In Xen, it's dom0.

- Type: Host, AdminVM
- Qrexec: @host, @adminvm

admin qube

Text about it it being an administrative qube, where its
privileges are limited by Qrexec (link to admin-api page). By
default, there is no such qube present on the system.

- Examples: audio qube (sys-audio), interface qube (sys-gui*)

> > There is also one case where I have a vague idea for @adminvm policy
> > term to reference "admin qube" - specifically for remote qube. A policy
> > like "admin.something * some-local-admin-qube some-remote-qube allow
> > target=@adminvm" could mean redirecting to a _remote_ admin qube that
> > can manage that qube. This idea is very vague for now (together with
> > anything related to managing remote qubes), and maybe completely wrong,
> > but kinda related to evolution of the term AdminVM/Admin qube.
>
> But in that case the call gets logically redirected to the remote dom0
> ("host qube" or on whatever we settle on). Sure internally it is
> relayed/proxied, but not sure "@adminvm" is a good description assuming
> we drop the dom0 meaning of "admin qube". "@hostqube" that automatically
> means the remote one for remote VMs or an explicit "@remotehostqube" (or
> "@remote:hostqube", ...) sounds more fitting. But yeah, since this is,
> at this point, speculative, a bit hard to say what exactly will fit the
> implementation later.
>
> > Anyway, (kinda) changing meaning of an existing term is a risky thing
> > to do. Personally, I think this one may clarify things in the long run,
> > but maybe others have better ideas?
>
> I might not have expressed this clearly before, so to be clear: I'm not
> per-se objecting to change the meaning, but my concerns is that we then
> properly need to consider the previous use and ideally clean up things.
>
> > [1] https://doc.qubes-os.org/en/latest/user/reference/glossary.html#term-admin-qube

- --

Best regards,
Benjamin Grande

Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iHUEARYIAB0WIQRklnEdsUUe50UmvUUbcxS/DMyWhwUCalijMwAKCRAbcxS/DMyW
hz9xAQD8oKrxYl1Vwk7ArbcmsemD/LOtGLJB360xPvO95e6ebQD/aXKHt7m199Wp
a6tBmrQVoDLEIRT+EFwiaHESGUOO4QY=
=9nU2
-----END PGP SIGNATURE-----

[unman]

On Wed, Jul 15, 2026 at 06:05:41PM +0200, Simon Gaiser wrote:
> In the snip-ed quote you wrote
>
> [...] there is no requirement that an admin qube (or whatever term
> is used) has FULL administrative control over EVERYTHING.
>
> but for the "dom0(-equivalent)" usage of the term, this doesn't make
> sense. That's what I was responding to here.

I think we are talking past each other.

> So if we have a policy like:
>
> admin.vm.List * test-mon @anyvm allow target=@adminvm
>
> You would need so say something like: "This allows the test-mon admin
> qube to call the admin.vm.List qubes-rpc for any qubes and redirects it
> to the admin qube, since Admin API calls are executed by it." Where the
> first "admin qube" means "a qube that uses the Admin API" and the second
> "admin qube" means "dom0(-equivalent)".

Why ever would you want to say this?
The natural explanation would be "This allows the test-mon admin
qube to call the admin.vm.List qubes-rpc for any qube and redirects it
to dom0 , since Admin API calls are executed by it."

BECAUSE YOU WOULD HAVE ALREADY EXPLAINED THAT IN POLICIES @adminvm MEANS
dom0

Or more likely, "This policy allows test-mon to get a list of all the
qubes on the system."

Does @adminvm include all admin qubes? No, it specifically refers to
dom0.
Is dom0 an admin qube? Yes, it is. It's an unrestricted admin qube with
control over the whole system.
Are there other admin qubes with that level of control? There can be
depending on what policies you set. Often you will have admin qubes that
are limited in which qubes they can control.
&c

Of course you may want some new term in policies to refer to dom0 or
whatever host you have. OK.

In my experience people can make good use of new admin qubes -
apparently this makes them "advanced users". Perhaps. But they can do
this without understanding the plumbing. That's my experience.
And for most of those people the terms AdminVM and @adminvm do not
create any conflict with "admin qube".

[qubist]

On Wed, 15 Jul 2026 11:06:56 +0100 'unman' via qubes-devel wrote:

> I believe that "admin qube" is clear to users - it is a qube used for
> administration.

Yes. It would be bad to change such a straightforward term.

Introducing client/server, or host/guest would make things
unnecessarily complicated. Unless I am missing the essence, a second
"admin qube" is functionally still an "admin qube", right? - So, why
call it something else?

> AdminVM remains as the name of a klass, as DispVM, TemplateVM etc. It
> should be deprecated in normal use and replaced by "admin qube".
> Currently the only qube of Klass AdminVM is dom0, but MANY qubes can
> serve as admin qubes.

Perhaps using "Dom0" or "Domain0" as klass would remove the confusion.
Then, it will be perfectly clear that this is one-of-a-kind klass which
can be used only for one particular domain. Then perhaps, multiple
other "admin qubes" can have the "AdminQube" klass without that
creating confusion...

[qube...@4forl1st5.slmail.me]

On Wednesday, July 15th, 2026 at 14:57, Marek Marczykowski-Górecki <marm...@invisiblethingslab.com> wrote:

> Even in our glossary, "admin qube" is defined[1] as:
>
> A type of qube used for administering Qubes OS. In the default
> install, the only admin qube is dom0.
>
> Which already suggests there may be more of them.
>
> Eventually dom0 could gain some new term, maybe something like "host qube"
> (borrowing from KVM, and already used in few places like qubes builder)?

At the risk of trying to cut through this Gordian Knot with an
over-simplistic sword, I'd like to hack into that part of it,
as follows:

why not just refer to Dom0 as the "dom0 qube"


Unless Qubes is planning to move away from Xen, and hence having a/the
Dom0 at the root of the overall system, "dom0 qube" should stand the
test of time.

With apologies for trimming my reply.