Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update template switching instructions #1297

Merged
merged 2 commits into from Mar 5, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
81 changes: 49 additions & 32 deletions user/templates/templates.md
Expand Up @@ -218,40 +218,57 @@ Please see [How to Reinstall a Template](/doc/reinstall-template/).

## Switching

When you install a new template or upgrade a clone of a template, it is
recommended that you switch everything that was set to the old template to the
When you install a new template or
[upgrade](/doc/how-to-update/#upgrading-to-avoid-eol) a template, it is
recommended that you switch everything that was using the old template to the
new template:

1. Make the new template the default template.

```
Applications Menu -> System Tools -> Qubes Global Settings -> Default template
```

2. If your keyboard or mouse is connected through `sys-usb`, switch `sys-usb`
to the new template. (Note that this is a single command to ensure that
`sys-usb` restarts. If it does not, you will not be able to use your USB
keyboard or mouse.)

```
[user@dom0 ~]$ qvm-shutdown --wait sys-usb; qvm-prefs sys-usb template <NEW_TEMPLATE>; qvm-start sys-usb
```

3. Base app qubes on the new template.

```
Applications Menu -> System Tools -> Qubes Template Manager
```

4. Base the [disposable template](/doc/glossary/#disposable-template) on the new
template.

```
[user@dom0 ~]$ qvm-create -l red -t <NEW_TEMPLATE> <NEW_DISPOSABLE_TEMPLATE>
[user@dom0 ~]$ qvm-prefs <NEW_DISPOSABLE_TEMPLATE> template_for_dispvms True
[user@dom0 ~]$ qvm-features <NEW_DISPOSABLE_TEMPLATE> appmenus-dispvm 1
[user@dom0 ~]$ qubes-prefs default-dispvm <NEW_DISPOSABLE_TEMPLATE>
```
1. **Make the new template the default template.** In the App Menu, go
to Qubes Tools, then click on Qubes Global Settings. In the Qube Defaults
section, next to Template, select the new template from the
drop-down list. Press OK.

2. **Base your [disposable templates](/doc/glossary/#disposable-template) on
the new template.**

- If your only keyboard and mouse are *not* connected through a [USB
qube](/doc/usb-qubes/), or that USB qube is *not* a disposable, then shut
down all disposables. In the App Menu, go to Qubes Tools, then click on
Qube Manager. In the Qube Manager, find your disposable template(s). (By
default, they end in `-dvm`.) Right click, hover over Template, then click
on the new template. Repeat for each disposable template.

- If your only keyboard or mouse *are* connected through a USB qube, and
that USB qube *is* a disposable, then you will have to enter a special
command that shuts down all of your qubes, switches the USB qube's
disposable template to the new template, then starts the USB qube again.
In order to avoid being locked out of your system, you must be very
careful to enter this command without typos and with the correct
substitutions.

In the App Menu, click on Terminal Emulator. Type the command below,
substituting `<SYS_USB_DISPOSABLE_TEMPLATE>` with the name of the
disposable template on which `sys-usb` is based, `<NEW_TEMPLATE>` with the
name of the new template, and `<USB_QUBE>` with the name of your USB qube.
Other than these substitutions, make sure to enter the command exactly as
written.

```
qvm-shutdown --wait --all; qvm-prefs <SYS_USB_DISPOSABLE_TEMPLATE> template <NEW_TEMPLATE>; qvm-start <USB_QUBE>
```

With substitutions, your command should look similar to this example.
(Warning: This is just an example. Do not attempt to use it.)

```
qvm-shutdown --wait --all; qvm-prefs fedora-01-dvm template fedora-02; qvm-start sys-usb
```

3. **Base your app qubes on the new template.** In the Qube Manager, click on
the Template heading to sort by template. Select all the qubes based on the
old template by clicking on the first one, holding shift, then clicking on
the last one. With multiple qubes selected, right-click on any of them,
hover your cursor over Template, then click on the new template.

## Advanced

Expand Down