Is it more secure to update dom0 and templates via Salt?

[Andrew David Wong]

I still upgrade dom0 and templates the old-fashioned way, because I'm
used to it, I understand it, and I already have custom scripts for daily
maintenance that include these commands.

Specifically, I mean these kinds of commands:

`sudo qubes-dom0-update -y` in a dom0 terminal

`dnf -y --refresh upgrade` in Fedora TemplateVM terminals

`apt-get clean && apt-get -y update && apt-get -y dist-upgrade &&
apt-get -y autoremove && apt-get clean` in Debian-based TemplateVM terminals

However, when I occasionally use the Qubes Update tool, I see that it
creates a `disp-mgmt-*` DisposableVM for each VM it updates. This
prompts me to wonder: Is updating with the Qubes Update tool more secure
than my old-fashioned methods? Are certain operations performed within
that DisposableVM in order to protect the TemplateVM?

If so, then how should I invoke this new update method with a command
like the ones above? Are there drop-in replacements that I can use in my
scripts?

(I vaguely recall that this question may have been asked before, but I
can't find that thread now, so I figured I'd ask again. Besides, things
may have changed in the meantime.)

--
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org

[Marek Marczykowski-Górecki]

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

On Sat, Oct 10, 2020 at 09:50:00PM -0500, Andrew David Wong wrote:
> I still upgrade dom0 and templates the old-fashioned way, because I'm
> used to it, I understand it, and I already have custom scripts for daily
> maintenance that include these commands.
>
> Specifically, I mean these kinds of commands:
>
> `sudo qubes-dom0-update -y` in a dom0 terminal
>
> `dnf -y --refresh upgrade` in Fedora TemplateVM terminals
>
> `apt-get clean && apt-get -y update && apt-get -y dist-upgrade && apt-get -y
> autoremove && apt-get clean` in Debian-based TemplateVM terminals
>
> However, when I occasionally use the Qubes Update tool, I see that it
> creates a `disp-mgmt-*` DisposableVM for each VM it updates. This prompts me
> to wonder: Is updating with the Qubes Update tool more secure than my
> old-fashioned methods?

Short answer: in some cases yes.

> Are certain operations performed within that
> DisposableVM in order to protect the TemplateVM?

DisposableVM is used not to protect the TemplateVM, but to protect dom0
from potentially compromised TemplateVM. Salt stack is a complex piece
of software and we do not trust it won't get compromised when
interacting with compromised template. The benefit of using salt stack
is not there (the usage of DisposableVM actually makes it more resource
intensive and slower...). The good part is that in addition to perform
standard update commands, we can apply other changes before/after the
update. For example this is how we delivered APT fix for Debian
templates in context of QSB#46. This is also how we updated onion
version of repositories addresses when we switched them.
Another benefit is to have a single command to update any template.

> If so, then how should I invoke this new update method with a command like
> the ones above? Are there drop-in replacements that I can use in my scripts?

The salt version of dom0 update is:

sudo qubesctl state.sls update.qubes-dom0

And then for TemplateVM and StandaloneVM (all at once):

sudo qubesctl --skip-dom0 --templates --standalones state.sls update.qubes-vm

Useful options:

--max-concurrency - limit how many templates are updated at the same
time - adjust to available RAM (default 4, GUI updater sets it
to 1)
--targets=vm1,vm2,... - limit to specific VMs, instead of all the
templates (use instead of --templates --standalones)
--show-output - show update summary instead of just OK/FAIL

For other options see qubesctl --help

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAl+DL+IACgkQ24/THMrX
1yz3RggAmUQApMbqF5Ky2byELjFAUnXKLc+oqTcSmnLPbPkmWnIes6m7xj/JjHd2
H5pwReIDmWU52Li0FtDDnF25pX424ncWDdP/v/xRXtUU+/ZDGtt3GYPPSus3SRdS
WsGQP+YKPkQDBsWizmu4irV5hp4mnHf8oFvwue9VfVDWyAkHumtaC8ey+aFtLhlh
FpGcHNn2n9y+1MW5+mTIZd3U89ByNUj7BZJwxyQt68fjN6rTH7RyknS05BY5GOQi
4MygHqYqdoWMMKu78RvtIW0sbAVOUTq2gpecVzTeB2mt3gfKG307lByt2fClqKuB
JwjL0TWIYdj8lAXTBBni6fSMirJJqA==
=pAog
-----END PGP SIGNATURE-----

[Andrew David Wong]

Ah, so if I understand correctly, it's not that using dnf and apt-get
manually in the template is somehow less safe, but rather that I run the
risk of missing out on occasional security actions performed via Salt
beyond normal dnf and apt-get updates.

>> If so, then how should I invoke this new update method with a command like
>> the ones above? Are there drop-in replacements that I can use in my scripts?
>
> The salt version of dom0 update is:
>
> sudo qubesctl state.sls update.qubes-dom0
>
> And then for TemplateVM and StandaloneVM (all at once):
>
> sudo qubesctl --skip-dom0 --templates --standalones state.sls update.qubes-vm
>
> Useful options:
>
> --max-concurrency - limit how many templates are updated at the same
> time - adjust to available RAM (default 4, GUI updater sets it
> to 1)
> --targets=vm1,vm2,... - limit to specific VMs, instead of all the
> templates (use instead of --templates --standalones)
> --show-output - show update summary instead of just OK/FAIL
>
> For other options see qubesctl --help

Thanks for the great answer, Marek! I noticed that these commands don't
show the actual output from dnf or apt-get. Is there a way to do that?

Also, does this have a way of notifying users when they need to restart
dom0 after updates that require it (e.g., Xen, kernel)?

[Marek Marczykowski-Górecki]

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

Yes.

> > > If so, then how should I invoke this new update method with a command like
> > > the ones above? Are there drop-in replacements that I can use in my scripts?
> >
> > The salt version of dom0 update is:
> >
> > sudo qubesctl state.sls update.qubes-dom0
> >
> > And then for TemplateVM and StandaloneVM (all at once):
> >
> > sudo qubesctl --skip-dom0 --templates --standalones state.sls update.qubes-vm
> >
> > Useful options:
> >
> > --max-concurrency - limit how many templates are updated at the same
> > time - adjust to available RAM (default 4, GUI updater sets it
> > to 1)
> > --targets=vm1,vm2,... - limit to specific VMs, instead of all the
> > templates (use instead of --templates --standalones)
> > --show-output - show update summary instead of just OK/FAIL
> >
> > For other options see qubesctl --help
>
> Thanks for the great answer, Marek! I noticed that these commands don't show
> the actual output from dnf or apt-get. Is there a way to do that?

For direct dnf/apt output, not really. But you can get a summary by
using --show-output.

> Also, does this have a way of notifying users when they need to restart dom0
> after updates that require it (e.g., Xen, kernel)?

Not that I know of. But there could be some salt module to handle that.

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAl+Dqj4ACgkQ24/THMrX
1yzXjggAk68o+dYfPcuY0zWXWjQDxUd/w/p0DJY7fMUvYEanzR7whC1XyLhMESWf
zrSw8ylkJuOl5M17yHen1wwrpUw9ML7KDqrsvkLNkmxPhQdNQFaacJ7qdTWr/SYb
q3qXsPHm9mIzLar8awlHVPfYUDpJPsHVcJqHJh+FZAF/Sj3Eew/ZfR1SRSCQsCyr
w5x6FL8e49+rlt2Zgm5P23ZlGMJL5rYNpgLBWqCcc+6pEZOW62T2R2ePBwVR7DOy
xJ1rXaV8NlfiifwpDzvDQcL6F3iZQOl0VusXnTDAp9a/Gfjig6cqsvOaZKi9aLUO
/L1VJujeI0q4DZrq9h0jnlr2jrcJgw==
=BsE+
-----END PGP SIGNATURE-----

[Rafael Reis]

It'd be useful if those qubesctl update commands were in the docs, especially with the concurrency option.

[Chris Laprise]

It would be better if Qubes could discern between updates that require
salt and those that don't. As you mention, there is a drag on system
performance, and these salt-directed updates appear to take longer to
execute. They also appear to fail more frequently than regular updates.

--
Chris Laprise, tas...@posteo.net
https://github.com/tasket
https://twitter.com/ttaskett
PGP: BEE2 20C5 356E 764A 73EB 4AB3 1DC4 D106 F07F 1886

[Andrew David Wong]

On 10/11/20 5:58 PM, Marek Marczykowski-Górecki wrote:
[...]

>>> And then for TemplateVM and StandaloneVM (all at once):
>>>
>>> sudo qubesctl --skip-dom0 --templates --standalones state.sls update.qubes-vm
>>>
>>> Useful options:
>>>
>>> --max-concurrency - limit how many templates are updated at the same
>>> time - adjust to available RAM (default 4, GUI updater sets it
>>> to 1)
>>> --targets=vm1,vm2,... - limit to specific VMs, instead of all the
>>> templates (use instead of --templates --standalones)
>>> --show-output - show update summary instead of just OK/FAIL
>>>
>>> For other options see qubesctl --help
>>

Just a quick note:

When I try to use --templates and --standalones at the same time, I get:

"qubesctl: error: argument --standalones: not allowed with argument
--templates"

[Andrew David Wong]

On 10/13/20 11:51 AM, Rafael Reis wrote:
> It'd be useful if those qubesctl update commands were in the docs,
> especially with the concurrency option.
>

I've just added them:

https://www.qubes-os.org/doc/salt/#updatequbes-dom0
https://www.qubes-os.org/doc/salt/#updatequbes-vm

In case you (or any others reading this) are not already aware, the
documentation is a community effort, and everyone is welcome to
contribute. (That's how things like this get updated!) So, if you'd like
to get involved with the project, this is a great way to do it. You can
read more about how to submit documentation changes here:

https://www.qubes-os.org/doc/doc-guidelines/


P.S. -- Please avoid top posting.

> Em domingo, 11 de outubro de 2020 às 13:16:43 UTC-3,
> marm...@invisiblethingslab.com escreveu:
>

[Andrew David Wong]

I wasn't aware that they fail more frequently. Can you elaborate? What
kind of failure, and why?

[Chris Laprise]

I'm recalling times when I received a cryptic error message that the
update failed (no detail). In these cases I would just go back to my
update script and then the update(s) would succeed. So this is not
something I tried to troubleshoot, and the failures were a little too
common for me to keep using that method.

[Demi M. Obenour]

On 10/16/20 2:17 PM, Chris Laprise wrote:
> I'm recalling times when I received a cryptic error message that the update failed (no detail). In these cases I would just go back to my update script and then the update(s) would succeed. So this is not something I tried to troubleshoot, and the failures were a little too common for me to keep using that method.

Also, Arch explicitly does not support unattended upgrades (which Salt is).

Sincerely,

Demi M. Obenour
she/her/hers

[icequbes1]

Oct 16, 2020, 02:54 by a...@qubes-os.org:

> On 10/13/20 11:51 AM, Rafael Reis wrote:
>
>> It'd be useful if those qubesctl update commands were in the docs,
>> especially with the concurrency option.
>>
>
> I've just added them:
>
> https://www.qubes-os.org/doc/salt/#updatequbes-dom0
> https://www.qubes-os.org/doc/salt/#updatequbes-vm
>

While the docs are very nice, sometimes I think there is too much documentation in Qubes that it might scare new users away.

While some users may be unaware of the ability to update TemplateVMs with qubesctl, is a _typical_ user really asking "how can I use salt stack to update templates from the command line?"

I would think a user might ask "how do I update templates without having to manually start them or type dnf commands?"

Though qubesctl and salt is used behind the scenes, why not just point out the presence of qubes-update-gui which allows running the updater GUI at-will, and still doing things the "salt" way? Inquisitive minds will look deeper and discover qubesctl is used internally. They'd then hopefully read the man page to see available options.

I love documentation as much as the next person, but let's hide the more scary parts that they probably will never use? Some new users think Qubes OS is overwhelming to begin with; reading esoteric commands (to a new user) in Qubes' documentation can unnecessarily add to that. My apologies if I am getting off-topic.

[David Hobach]

On 10/17/20 6:22 AM, 'icequbes1' via qubes-devel wrote:
> While the docs are very nice, sometimes I think there is too much documentation in Qubes that it might scare new users away.
>
> While some users may be unaware of the ability to update TemplateVMs with qubesctl, is a _typical_ user really asking "how can I use salt stack to update templates from the command line?"
>
> I would think a user might ask "how do I update templates without having to manually start them or type dnf commands?"
>
> Though qubesctl and salt is used behind the scenes, why not just point out the presence of qubes-update-gui which allows running the updater GUI at-will, and still doing things the "salt" way? Inquisitive minds will look deeper and discover qubesctl is used internally. They'd then hopefully read the man page to see available options.
>
> I love documentation as much as the next person, but let's hide the more scary parts that they probably will never use? Some new users think Qubes OS is overwhelming to begin with; reading esoteric commands (to a new user) in Qubes' documentation can unnecessarily add to that. My apologies if I am getting off-topic.

Basic users should be able to manage with some "Getting started" guide where something like the above certainly does not belong.

I however totally disagree with the idea that advanced users shouldn't have any good documentation at hand. Reading code is still a lot more time intensive than reading doc. And Qubes OS probably doesn't want the advanced users from which it profits a lot with pull requests and other contributions to turn away.

[Andrew David Wong]

On 10/16/20 9:22 PM, icequbes1 wrote:
> Oct 16, 2020, 02:54 by a...@qubes-os.org:
>
>> On 10/13/20 11:51 AM, Rafael Reis wrote:
>>
>>> It'd be useful if those qubesctl update commands were in the docs,
>>> especially with the concurrency option.
>>>
>>
>> I've just added them:
>>
>> https://www.qubes-os.org/doc/salt/#updatequbes-dom0
>> https://www.qubes-os.org/doc/salt/#updatequbes-vm
>>
>
> While the docs are very nice, sometimes I think there is too much documentation in Qubes that it might scare new users away.
>

Really?

> While some users may be unaware of the ability to update TemplateVMs with qubesctl, is a _typical_ user really asking "how can I use salt stack to update templates from the command line?"
>

No, of course not. That's why this is a thread in qubes-devel, not
qubes-users, and why that doc page is under "Advanced Configuration."

> I would think a user might ask "how do I update templates without having to manually start them or type dnf commands?"
>

Or, more likely, just "How do I update Qubes?" which is why we have a
simple page for exactly that under "Common Tasks":

https://www.qubes-os.org/doc/updating-qubes-os/

> Though qubesctl and salt is used behind the scenes, why not just point out the presence of qubes-update-gui which allows running the updater GUI at-will, and still doing things the "salt" way?

We do, but not on the Salt page, because the Salt page is about Salt things.

> Inquisitive minds will look deeper and discover qubesctl is used internally. They'd then hopefully read the man page to see available options.
>

This is basically the man page.

> I love documentation as much as the next person, but let's hide the more scary parts that they probably will never use?

As far as I can tell, that's already the case. Are you perhaps
misinterpreting the situation as somehow being the opposite?

> Some new users think Qubes OS is overwhelming to begin with; reading esoteric commands (to a new user) in Qubes' documentation can unnecessarily add to that. My apologies if I am getting off-topic.
>

I'd say the solution is common sense: If you're new, stick with the
basic docs meant for new users. Don't go into the advanced section and
expect to understand it yet.

[Andrew David Wong]

Hm, interesting. The qubesctl method has been working for me so far
(failure rate doesn't seem any higher than the old method), but let me
know if you ever discover anything more about this.

[Jean-Philippe Ouellet]

On Fri, Oct 16, 2020 at 9:22 PM 'icequbes1' via qubes-devel
<qubes...@googlegroups.com> wrote:
>
> Oct 16, 2020, 02:54 by a...@qubes-os.org:
>
> > On 10/13/20 11:51 AM, Rafael Reis wrote:
> >
> >> It'd be useful if those qubesctl update commands were in the docs,
> >> especially with the concurrency option.
> >>
> >
> > I've just added them:
> >
> > https://www.qubes-os.org/doc/salt/#updatequbes-dom0
> > https://www.qubes-os.org/doc/salt/#updatequbes-vm
> >
>
> While the docs are very nice, sometimes I think there is too much documentation in Qubes that it might scare new users away.

I must strongly disagree.

There are different types of documentation, with different target
audiences, which serve different roles. Not all types of information
may be appropriate for all contexts, but if anything Qubes is lacking
documentation. This is particularly true of many areas of its
internals, for which "the source is the documentation" is true more
often than one might wish.

I highly recommend this talk:
https://www.youtube.com/watch?v=t4vKPhjcMZg ("What nobody tells you
about documentation")

tl;dr of the thesis, is that there are:
- learning-oriented tutorials
- goal-oriented how-to guides
- understanding-oriented discussions
- information-oriented reference material

It's useful to understand the distinction, and what type of content is
appropriate for each, but having _too much_ documentation is most
definitely not the problem. Organization? Clarity? Staleness? Perhaps,
sure. Hopefully GSoD may help somewhat with that :)

The salt stuff in particular has not seen as much adoption as it
might, with people reimplementing equivelant functionality in easier
and simpler ways (for instance, this very thread!), which is I'm sure
in no small part due to Salt's notable learning curve as a result of
its opaque terminology and its own less-than-ideal docs.

This is not the first time this subject has come up within the context
of Salt in particular. See also:
- https://github.com/QubesOS/qubes-issues/issues/1983
- https://groups.google.com/g/qubes-users/c/F_TB7Zzseeo/m/KgTbS-L-CAAJ

> While some users may be unaware of the ability to update TemplateVMs with qubesctl, is a _typical_ user really asking "how can I use salt stack to update templates from the command line?"
>
> I would think a user might ask "how do I update templates without having to manually start them or type dnf commands?"
>
> Though qubesctl and salt is used behind the scenes, why not just point out the presence of qubes-update-gui which allows running the updater GUI at-will, and still doing things the "salt" way? Inquisitive minds will look deeper and discover qubesctl is used internally. They'd then hopefully read the man page to see available options.
>
> I love documentation as much as the next person, but let's hide the more scary parts that they probably will never use? Some new users think Qubes OS is overwhelming to begin with; reading esoteric commands (to a new user) in Qubes' documentation can unnecessarily add to that. My apologies if I am getting off-topic.

I'll leave UX decisions to the UX people, but I know you'll find
notable disagreement among Qubes users about the merit of this
approach and its suitability for Qubes. As a recent example of
disagreement about this philosophy, I point to
https://github.com/QubesOS/qubes-issues/issues/1919#issuecomment-691611785

[icequbes1]

Oct 17, 2020, 21:12 by j...@vt.edu:

> On Fri, Oct 16, 2020 at 9:22 PM 'icequbes1' via qubes-devel
> <qubes...@googlegroups.com> wrote:
>
>>
>> While the docs are very nice, sometimes I think there is too much documentation in Qubes that it might scare new users away.
>>
>
> I must strongly disagree.

> ...> It's useful to understand the distinction, and what type of content is

> appropriate for each, but having _too much_ documentation is most
> definitely not the problem. Organization? Clarity? Staleness? Perhaps,
> sure. Hopefully GSoD may help somewhat with that :)
>
>

Perhaps my English could use improvement, but my intent was addressing level of detail on the documentation resources most users would reference first; not that there shouldn't be good docs for advanced users or that docs should be removed. I've got qubes-doc cloned and often grep against it.

>> I love documentation as much as the next person, but let's hide the more scary parts that they probably will never use? Some new users think Qubes OS is overwhelming to begin with; reading esoteric commands (to a new user) in Qubes' documentation can unnecessarily add to that. My apologies if I am getting off-topic.
>>
>
> I'll leave UX decisions to the UX people, but I know you'll find
> notable disagreement among Qubes users about the merit of this
> approach and its suitability for Qubes. As a recent example of
> disagreement about this philosophy, I point to
> https://github.com/QubesOS/qubes-issues/issues/1919#issuecomment-691611785
>

My initial thoughts to this thread were, why not just document how to pop open the GUI updater with qubes-update-gui if one wants to update using salt. If you're not writing pillars or states or trying to script things, why not just point people to the GUI (in the documentation) and instruct users who need more control to read the man page of qubesctl (which has sufficient documentation and is authoritative).

I understand Qubes OS to be very thoughtful and intentional with the decisions it makes, which is good. But at times, I feel there's a bit of over-explaining to the point where less experienced linux users might feel alienated, overwhelmed, or simply find it easier to pose questions without referencing written works that already answer their question in detail. I am not diminishing anyone's documentation contributions (I've made none), but my goal was to help with appearances if I were to take on the perspective of a less experienced user. While I am familiar with linux, I have only used Qubes OS for months, so my apologies if my observations are premature.

[Andrew David Wong]

On 10/17/20 10:29 PM, icequbes1 wrote:
> Oct 17, 2020, 21:12 by j...@vt.edu:
>
>> On Fri, Oct 16, 2020 at 9:22 PM 'icequbes1' via qubes-devel
>> <qubes...@googlegroups.com> wrote:
>>
>>>
>>> While the docs are very nice, sometimes I think there is too much documentation in Qubes that it might scare new users away.
>>>
>>
>> I must strongly disagree.
>> ...> It's useful to understand the distinction, and what type of content is
>> appropriate for each, but having _too much_ documentation is most
>> definitely not the problem. Organization? Clarity? Staleness? Perhaps,
>> sure. Hopefully GSoD may help somewhat with that :)
>>
>>
> Perhaps my English could use improvement, but my intent was addressing level of detail on the documentation resources most users would reference first; not that there shouldn't be good docs for advanced users or that docs should be removed. I've got qubes-doc cloned and often grep against it.
>
>>> I love documentation as much as the next person, but let's hide the more scary parts that they probably will never use? Some new users think Qubes OS is overwhelming to begin with; reading esoteric commands (to a new user) in Qubes' documentation can unnecessarily add to that. My apologies if I am getting off-topic.
>>>
>>
>> I'll leave UX decisions to the UX people, but I know you'll find
>> notable disagreement among Qubes users about the merit of this
>> approach and its suitability for Qubes. As a recent example of
>> disagreement about this philosophy, I point to
>> https://github.com/QubesOS/qubes-issues/issues/1919#issuecomment-691611785
>>
> My initial thoughts to this thread were, why not just document how to pop open the GUI updater with qubes-update-gui if one wants to update using salt. If you're not writing pillars or states or trying to script things, why not just point people to the GUI (in the documentation) and instruct users who need more control to read the man page of qubesctl (which has sufficient documentation and is authoritative).
>

This thread was never about primarily about documentation. Rafael simply
suggested, as a side note, documenting the information Marek provided
(which is fine and reasonable).

> I understand Qubes OS to be very thoughtful and intentional with the decisions it makes, which is good. But at times, I feel there's a bit of over-explaining to the point where less experienced linux users might feel alienated, overwhelmed, or simply find it easier to pose questions without referencing written works that already answer their question in detail. I am not diminishing anyone's documentation contributions (I've made none), but my goal was to help with appearances if I were to take on the perspective of a less experienced user. While I am familiar with linux, I have only used Qubes OS for months, so my apologies if my observations are premature.
>

Apparently my earlier explanations have failed, so let me try again with
an analogy: Suppose you know nothing about computer hardware. You can
use computers fine, but the internals are a mystery. What you're saying
is analogous to saying, "Computers are great, but all of these
whitepapers and articles discussing processors, motherboards, memory,
and drives are too overwhelming and intimidating for novices who just
want to do web browsing, email, word processing, and video conferencing.
They don't need to know anything about clock rates, PCIe lanes, RAM
timings, or sequential read/write speeds!

The obvious answer is: Of course they don't. These articles and other
content *aren't for them*. Those folks should just buy a suitable
computer and move on with their lives. There are others who need or want
to know details about hardware -- people whose jobs or hobbies involve
maintaining, repairing, and building computers. Surely you're not
suggesting that no content should exist for them simply because it might
scare away novice computer users.

Again, I have to point out that this is the qubes-devel mailing list. If
this sort of technical discussion isn't appropriate for qubes-devel,
then what is? Is the very *existence* of qubes-devel too alienating for
novice users? Surely not (and, even if it were, those novice users
should simply avert their eyes until the sight of qubes-devel no longer
causes consternation).

Likewise, the documentation is split between user and developer
documentation, and the user section is further split with an "Advanced
Configuration" section. What you see as a document that "over-explains"
I see as a document targeted at a different audience (an advanced,
technical audience for whom the level of explanation is appropriate). A
single level of explanation cannot be appropriate for all audiences. The
alternative would be eliminating all but the simplest level of
explanation (literally "dumbing down" all the documentation to fit the
lowest common denominator). I can't entertain this as a serious suggestion.

There's a common theme in all this: Context matters. A thread in
qubes-devel vs. qubes-users. A doc in the user vs. dev or basic vs.
advanced section. Writing for your audience. It's all about context.