Installation documentation is insufficient

[keyser_soze]

I am a new user, moving from Windows 7.

The installation documentation is insufficient, there is not enough information provided for new users to understand or make deliberate choices with known/expected consequences.

Consider this image

from Installation guide — Qubes OS Documentation.

Unfortunately, the description that follows is indeed brief, it is superficial and somewhat redundant. The information provided does not explain further what can be inferred from the user interface itself.

Consider the first description:

Create default system qubes: These are the core components of the system, required for things like internet access. You can opt to have some created as disposables.

There are too many questions that are not answered anywhere in the documentation:

1. Why would sys-firewall and sys-usb be disposable, together, and not separately, as sys-net is?
2. What are the consequences (both benefits and disadvantages) for each of these services being or not disposable? (please let’s not waste our time with the definition of disposable, and no, a link to the disposable general documentation does not answer this question)
3. How can the result of each of the possible child options (regarding these services being disposable) be recreated/altered, manually, after the installation? (and thus, demonstrating to the user that if they change their mind, they don’t need to reinstall from scratch to try out something different)
4. What are the consequences (both benefits and disadvantages) for each of these services being or not created? (the parent checkbox checked, or not)
5. How do their consequences interact with each other?
6. How can each of these services be created manually, after the installation?

Answering these questions here does not help. The documentation should be updated instead. In fact, probably most of the information replied in this forum should be migrated in the documentation. The number of threads, and how often certain subjects reappear in different guises, these are demonstrations of how much the documentation itself should be improved.

[KitsuneNoBaka]

1. they should be separated, but maybe there is a deeper reason they are not
2. without knowing what is disposable there is no way to know of consequences
3. there is usb qube creating doc only
4. if not created, everything will be serviced in Dom0. If there’s an attack on net service or usb service then Dom0 will be doomed
5. their consequences affect Dom0 except that if you use usb network controller it might be better for sys-net to be service to usb as well
6. there is usb qube creating doc only

[unman]

Answering these questions here does not help. The documentation should be updated instead. In fact, probably most of the information replied in this forum should be migrated in the documentation. The number of threads, and how often certain subjects reappear in different guises, these are demonstrations of how much the documentation itself should be improved.

I agree.

The documentation is a community effort. Please help us improve it by
submitting a pull request.

How to edit the documentation

Or users can PM or email me with their suggestions.

In the present case I think that brief answers have been given.
If you understand what a disposable is then you will understand
the benefits and disadvantages of using them here.

The canonical way of (re)creating these qubes would be to use salt, but
this page contains detail about USB qubes:

USB qubes

Salt is lightly documented here:

Salt (management software)

sys-firewall is a qube with provides_network set to True. You can
produce a replacement firewall by creating a qube, enabling this setting,
and setting it as netvm in client qubes.
The disposable sys-firewall is a named disposable - explained here

I never presume to speak for the Qubes team.
When I comment in the Forum I speak for myself.

[parulin]

@unman

The documentation is a community effort. Please help us improve it by
submitting a pull request.

I don’t think we can ask that to @keyser_soze, as they are new to Qubes OS so, this feedback is already a huge effort.

Maybe the only thing we can ask is reporting the issue directly on Github?

There might be two issues here: unclear docs and an unclear user interface. When installing Qubes OS for the first time, one should keep the defaults most of the time.

[renehoj]

@parulin

There might be two issues here: unclear docs and an unclear user interface. When installing Qubes OS for the first time, one should keep the defaults most of the time.

The “Main configuration” could be hidden behind an “Advanced options” button, leaving only the template configuration as the visible options.

[keyser_soze]

@unman

The documentation is a community effort. Please help us improve it by
submitting a pull request.

Of course.

However, there are still no satisfactory answers. Maybe it may be because of the knowledge and experience you and other proponents already have. Maybe the answers may seem self-evident.

Consider this fragment:

It is not explicit, but it is assumed from the UI that sys-usb would be created too when selecting the parent checkbox. sys-usb is mentioned by the 1st child, but not the parent.

Why we, new users, can choose to make sys-net disposable or not, alone, but we cannot do that for sys-firewall and/or sys-usb? Why, for sys-firewall and sys-usb, this choice is for both, and not individually? As is for sys-net? That’s fine for this potentially lengthy detail not to be described in the UI, and just in the documentation, but so far, there is no answer.

Since these are options that may be chosen by the user, it is assumed that these may result in an acceptable state of the system. Maybe it may not be the best use of the resources, or the features of Qubes OS, but still, an acceptable state. So we choose not to create any default system qubes. What are the consequences? That, and those other questions written before, we cannot infer from anywhere in the documentation. Or we choose to create them, but not make any of them disposable. Again, benefits, disadvantages, consequences, none can be inferred.

Contrast with dom0. There are no options related to it. We cannot choose to install it or not, or change any of its attributes. Thus, we assume that the options related to it that were omitted are coherent with its impact to the overall system state. There is no choosing for dom0.

The general descriptions for what are and how are used disposables, salt, or anything else do not answer together any of these questions.

@parulin

There might be two issues here: unclear docs and an unclear user interface. When installing Qubes OS for the first time, one should keep the defaults most of the time.

And this is why those questions were asked. To help determine the suitability of the defaults. As a critical analysis of the defaults, albeit by us, new, ignorant users. In fact, if that is the case, there should be no options.

However, I am experiencing this effect of the defaults myself: the installation correctly identifies that my system does not provide VT-d. As a user, I sincerely expected that, the same way it can identify this attribute and warn me, and even suggest to interrupt the installation, despite the documentation suggesting otherwise (User FAQ: Can I install Qubes on a system without VT-d?), I expected the installation process to alter the defaults to adapt to this significant attribute (lack of VT-d). It is my experience that it does not. Despite at least 2 different attempts suggested in the documentation, it remains impossible to login with sys-usb without qubes.skip_autostart in grub. But let’s not focus on that, I will raise an issue for this item soon. The focus is answers to those questions.

[unman]

However, there are still no satisfactory answers. Maybe it may be because of the knowledge and experience you and other proponents already have. Maybe the answers may seem self-evident.

It’s true that many things in Qubes seem obvious to experienced users and not to new
users. This is true of many things - Windows included…
I agree with @parulin that much of the installation could be hidden
behind an “Advanced options” button - or not shown at all. (This has
been mooted in the past.)

In the present case, I think I understand your questions but you have
not made it clear what lies behind them. Why is it not acceptable to you
to accept the options that Qubes has chosen?
The only question that remains seems to me to be why sys-firewall and
sys-usb are treated together: the answer could be that they need not be,
but Qubes has decided to treat them together. What more do you want?

Are there any other of your questions that have not been answered? Can
you be more exact about what remains and what further information would
help?

I never presume to speak for the Qubes team.
When I comment in the Forum I speak for myself.

[phceac]

@keyser_soze

despite the documentation suggesting otherwise

I think it is unfortunate that @keyser_soze seems to have fallen upon an external and obsolete clone of the Qubes documents from 10 years ago.

Maybe it is necessary to raise a bug to add a clear link to the relevant (current?) docs in the installer?

However, I am not sure that the current docs are optimally clear, although they are more accurate, I think.

[adw]

@phceac

I think it is unfortunate that @keyser_soze seems to have fallen upon an external and obsolete clone of the Qubes documents from 10 years ago.

It is unfortunate, but keep in mind that someone who wanted to attack Qubes users could easily set up an even more official-looking clone of the documentation that contains actively malicious instructions (instead of merely being 10 years out of date). It’s impossible for the Qubes OS Project to stop this, since we can’t force anyone else on the Internet to take down their websites (and trying to do so via court orders would be a waste of time, since cybercriminals would simply ignore them or operate outside of the relevant jurisdictions, and every successful takedown would immediately be replaced by many more, resulting in a pointless whack-a-mole that diverts time and resources away from productive activities).

@phceac

Maybe it is necessary to raise a bug to add a clear link to the relevant (current?) docs in the installer?

Sounds like a good idea. Please feel free to do so. Maybe adding a QR code in the installer (that links to the installation guide) might also be a nice touch.

[phceac]

@adw

a good idea

At long last, after a helpful prod from @FranklyFlawless, I have submitted the idea of adding more access to online/offline docs:
https://github.com/QubesOS/qubes-issues/issues/10399

I have expanded the scope a bit.

In particular, I propose a dedicated howto doc for each specific stage of the installer, which could include individual items explaining each of the options, but also needs to respond to the needs of a beginner.

Maybe it is too much?

I have various other ideas about how an interface could be both complete and easy to use… but that is probably another topic, and rather depends on what is actually possible in the fedora installer.

[FranklyFlawless]

A comprehensive installation guide is better than an insufficient one.