Documentation for template upgrade should recommend qvm-create-default-dvm

[andrewclausen]

Qubes OS version:

R3.2

Affected TemplateVMs:

all

Summary:

The documentation for upgrading template VMs ought to recommend using the new template for disposable VMs using qvm-create-default-dvm.

Details:

When upgrading Template VMs to a new version, e.g. Fedora 23 -> 24, the user will probably want to use the new version for their disposable VMs. The documentation should tell the user how to do this, both in the summary, and in the detailed steps.

• In the summary, only one new command is needed at the end:
  [user@dom0 ~]$ qvm-create-default-dvm fedora-24

• In the detailed instructions, add a final step:

(Optional) Instruct Qubes to use the upgraded template for all disposable VMs.
[user@dom0 ~]$ qvm-create-default-dvm fedora-24

[andrewdavidwong]

I don't think we should assume that everyone who upgrades a Fedora template from 23 to 24 will want to use it as their DispVM template. Besides, even if they do, this will be done automatically the next time a DispVM is started if the upgraded template is already set as the DispVM template.

[andrewdavidwong]

I don't think we should assume that everyone who upgrades a Fedora template from 23 to 24 will want to use it as their DispVM template. Besides, even if they do, this will be done automatically the next time a DispVM is started if the upgraded template is already set as the DispVM template.

[andrewclausen]

1. I agree that we ought not assume that everyone will want to switch. Most people will, so we should tell them how to do it.

2. I don't understand what you mean about it being done automatically. If the user updated a cloned template (as recommended by the instructions), then my new instructions are the only way I know of to switch the disposable VMs over to the new template. Is there another way?

[andrewclausen]

1. I agree that we ought not assume that everyone will want to switch. Most people will, so we should tell them how to do it.

2. I don't understand what you mean about it being done automatically. If the user updated a cloned template (as recommended by the instructions), then my new instructions are the only way I know of to switch the disposable VMs over to the new template. Is there another way?

[marmarek]

Besides, even if they do, this will be done automatically the next time a DispVM is started if the upgraded template is already set as the DispVM template.

No - automatic update of DispVM template (which is triggered by changing anything in appropriate template) do not switch the template used there. Explicit call to qvm-create-default-dvm is needed for that. So, basically 👍 for the proposed documentation change.

[marmarek]

Besides, even if they do, this will be done automatically the next time a DispVM is started if the upgraded template is already set as the DispVM template.

No - automatic update of DispVM template (which is triggered by changing anything in appropriate template) do not switch the template used there. Explicit call to qvm-create-default-dvm is needed for that. So, basically 👍 for the proposed documentation change.

[andrewdavidwong]

I agree that we ought not assume that everyone will want to switch. Most people will, so we should tell them how to do it.

A lot of users have more than one Fedora template, but they can only use one template as the DispVM template, so that final step (as you presented it) will often not make sense. Of course I agree that we should tell users how to do something that they might want to do. The question is what information will be helpful, in which situations, and presented in what way.

(For example, even if we mark a step as optional, if it turns out to be a step that most users who read this page will not be performing most of the time, it should probably be presented in a better way.)

2 I don't understand what you mean about it being done automatically. If the user updated a cloned template (as recommended by the instructions), then my new instructions are the only way I know of to switch the disposable VMs over to the new template. Is there another way?

(See below.)

No - automatic update of DispVM template (which is triggered by changing anything in appropriate template) do not switch the template used there. Explicit call to qvm-create-default-dvm is needed for that.

Right, which is why is said:

Besides, even if they do, this will be done automatically the next time a DispVM is started if the upgraded template is already set as the DispVM template.

It seems better to offer a general reminder to users to switch everything that was set to the old template to the new template, including:

• The "default template" setting in Qubes Manager
• Any desired AppVMs
• The DVM template

Why is this better than narrowly offering the qvm-create-default-dvm fedora-24 command?

• The other things may just as important to the user (if not more so) as the DVM template.
• The general reminder is directly relevant to the content of this page (upgrading a template), whereas advice that focuses specifically on DispVMs is less relevant. (The latter is more directly relevant to the content of the DispVM page.)
• We often (in the docs and on the mailing lists) recommend that users do qvm-create-default-dvm --default-template, which will not turn out as expected if the DVM template was generated for the new template while the default template is set to something else

[andrewdavidwong]

I agree that we ought not assume that everyone will want to switch. Most people will, so we should tell them how to do it.

A lot of users have more than one Fedora template, but they can only use one template as the DispVM template, so that final step (as you presented it) will often not make sense. Of course I agree that we should tell users how to do something that they might want to do. The question is what information will be helpful, in which situations, and presented in what way.

(For example, even if we mark a step as optional, if it turns out to be a step that most users who read this page will not be performing most of the time, it should probably be presented in a better way.)

2 I don't understand what you mean about it being done automatically. If the user updated a cloned template (as recommended by the instructions), then my new instructions are the only way I know of to switch the disposable VMs over to the new template. Is there another way?

(See below.)

No - automatic update of DispVM template (which is triggered by changing anything in appropriate template) do not switch the template used there. Explicit call to qvm-create-default-dvm is needed for that.

Right, which is why is said:

Besides, even if they do, this will be done automatically the next time a DispVM is started if the upgraded template is already set as the DispVM template.

It seems better to offer a general reminder to users to switch everything that was set to the old template to the new template, including:

• The "default template" setting in Qubes Manager
• Any desired AppVMs
• The DVM template

Why is this better than narrowly offering the qvm-create-default-dvm fedora-24 command?

• The other things may just as important to the user (if not more so) as the DVM template.
• The general reminder is directly relevant to the content of this page (upgrading a template), whereas advice that focuses specifically on DispVMs is less relevant. (The latter is more directly relevant to the content of the DispVM page.)
• We often (in the docs and on the mailing lists) recommend that users do qvm-create-default-dvm --default-template, which will not turn out as expected if the DVM template was generated for the new template while the default template is set to something else

[andrewclausen]

I can't get it to work following the new advice. I tried doing the following:

1. Instruct Qubes to use the default template VM for disposable VMs with qvm-create-default-dvm --default-template.

2. Changed the default template VM using the Qubes Manager (from A to B).

3. When I started a new disposable VM, it still used the old template (A).

Did I misunderstand something?

[andrewclausen]

I can't get it to work following the new advice. I tried doing the following:

1. Instruct Qubes to use the default template VM for disposable VMs with qvm-create-default-dvm --default-template.

2. Changed the default template VM using the Qubes Manager (from A to B).

3. When I started a new disposable VM, it still used the old template (A).

Did I misunderstand something?

[andrewdavidwong]

Swap the first two steps.

[andrewdavidwong]

Swap the first two steps.

[andrewclausen]

Oh, so you don't want to tell users how to do these three items? It's only a few words in each case, and would help users quite a bit. I would propose rewording your three items as follows:

• Switch the "default template" in the Qubes Manager "Global settings".

• Switch the AppVMs over to the new template in Qubes Manager under "VM settings".

• Switch the Disposable VMs to the new template with qvm-create-default-dvm fedora-24.

PS1. What's the advantage of --default-template?

PS2. qvm-create-default-dvm is not documented on the DispVM page.

[andrewclausen]

Oh, so you don't want to tell users how to do these three items? It's only a few words in each case, and would help users quite a bit. I would propose rewording your three items as follows:

• Switch the "default template" in the Qubes Manager "Global settings".

• Switch the AppVMs over to the new template in Qubes Manager under "VM settings".

• Switch the Disposable VMs to the new template with qvm-create-default-dvm fedora-24.

PS1. What's the advantage of --default-template?

PS2. qvm-create-default-dvm is not documented on the DispVM page.

[andrewdavidwong]

Oh, so you don't want to tell users how to do these three items?

This kind of attitude is unproductive.

It's only a few words in each case, and would help users quite a bit. I would propose rewording your three items as follows: [...]

Good idea. Thanks.

PS1. What's the advantage of --default-template?

No inherent "advantage" that I'm aware of. It's just an optional flag that causes the default template to be used.

PS2. qvm-create-default-dvm is not documented on the DispVM page.

Ok, thanks: #2474

[andrewdavidwong]

Oh, so you don't want to tell users how to do these three items?

This kind of attitude is unproductive.

It's only a few words in each case, and would help users quite a bit. I would propose rewording your three items as follows: [...]

Good idea. Thanks.

PS1. What's the advantage of --default-template?

No inherent "advantage" that I'm aware of. It's just an optional flag that causes the default template to be used.

PS2. qvm-create-default-dvm is not documented on the DispVM page.

Ok, thanks: #2474

[andrewclausen]

Oh, so you don't want to tell users how to do these three items?

This kind of attitude is unproductive.

It wasn't a rhetorical question. I was confused about what you thought the best solution was. I'm just trying to help!

Anyway, I think it would be easier to read if it read qvm-create-default-dvm fedora-24 instead of qvm-create-default-dvm <new-template-name> because people learn better by example, and it would be consistent with the rest of the guide. In any case, it's much better now!

[andrewclausen]

Oh, so you don't want to tell users how to do these three items?

This kind of attitude is unproductive.

It wasn't a rhetorical question. I was confused about what you thought the best solution was. I'm just trying to help!

Anyway, I think it would be easier to read if it read qvm-create-default-dvm fedora-24 instead of qvm-create-default-dvm <new-template-name> because people learn better by example, and it would be consistent with the rest of the guide. In any case, it's much better now!