Improve languge, syntax, and formatting; add link; wrap text

This commit is contained in:
Andrew David Wong 2021-09-26 16:47:15 -07:00
parent 86988470a3
commit 90ac679fab
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17

View File

@ -15,18 +15,31 @@ title: How to upgrade a Debian template in-place
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> This page is intended for advanced users only. Most users seeking to upgrade should instead <a href="/doc/templates/debian/#installing">install a new Debian template</a>. Learn more about the two options <a href="/doc/templates/debian/#upgrading">here</a>.
<b>Warning:</b> This page is intended for advanced users only. Most users
seeking to upgrade should instead <a
href="/doc/templates/debian/#installing">install a new Debian template</a>.
Learn more about the two options <a
href="/doc/templates/debian/#upgrading">here</a>.
</div>
This page provides instructions for performing an in-place upgrade of an installed [Debian Template](/doc/templates/debian/).
If you wish to install a new, unmodified Debian template instead of upgrading a template that is already installed in your system, please see the [Debian Template](/doc/templates/debian/) page instead. ([Learn more about the two options.](/doc/templates/debian/#upgrading))
In general, upgrading a Debian template follows the same process as [upgrading a native Debian system](https://wiki.debian.org/DebianUpgrade).
This page provides instructions for performing an in-place upgrade of an
installed [Debian Template](/doc/templates/debian/). If you wish to install a
new, unmodified Debian template instead of upgrading a template that is already
installed in your system, please see the [Debian
Template](/doc/templates/debian/) page instead. ([Learn more about the two
options.](/doc/templates/debian/#upgrading)) In general, upgrading a Debian
template follows the same process as [upgrading a native Debian
system](https://wiki.debian.org/DebianUpgrade).
## Summary instructions for Debian templates
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian version number *from* which you are upgrading, and `<new>` is the Debian version number *to* which you are upgrading. When upgrading from `buster` to `bullseye` please see the [release specific notes](/doc/template/debian/upgrade/#release-specific-notes).
**Important:** The prompt on each line indicates where each command should be
entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian
version number *from* which you are upgrading, and `<new>` is the Debian
version number *to* which you are upgrading. The instructions may differ for
certain releases. See [release-specific notes](#release-specific-notes) for any
instructions specific to your particular release.
```
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
@ -43,72 +56,80 @@ In general, upgrading a Debian template follows the same process as [upgrading a
## Detailed instructions for Debian templates
These instructions will show you how to upgrade Debian templates.
The same general procedure may be used to upgrade any template based on the standard Debian template.
These instructions will show you how to upgrade Debian templates. The same
general procedure may be used to upgrade any template based on the standard
Debian template.
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian version number *from* which you are upgrading, and `<new>` is the Debian version number *to* which you are upgrading.
**Important:** The prompt on each line indicates where each command should be
entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian
version number *from* which you are upgrading, and `<new>` is the Debian
version number *to* which you are upgrading. The instructions may differ for
certain releases. See [release-specific notes](#release-specific-notes) for any
instructions specific to your particular release.
1. Ensure the existing template is not running.
```
[user@dom0 ~]$ qvm-shutdown debian-<old>
```
```
[user@dom0 ~]$ qvm-shutdown debian-<old>
```
2. Clone the existing template and start a terminal in the new template.
```
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
```
```
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
```
3. Update your `apt` repositories to use the new release's code name instead of the old release's code name.
(This can be done manually with a text editor, but `sed` can be used to automatically update the files.)
3. Update your `apt` repositories to use the new release's code name instead of
the old release's code name. (This can be done manually with a text editor,
but `sed` can be used to automatically update the files.)
```
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list.d/qubes-r4.list
```
```
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list
[user@debian-<new> ~]$ sudo sed -i 's/<old-name>/<new-name>/g' /etc/apt/sources.list.d/qubes-r4.list
```
4. Update the package lists and upgrade.
During the process, it may prompt you to overwrite the file `qubes-r4.list`.
You should overwrite this file.
4. Update the package lists and upgrade. During the process, it may prompt you
to overwrite the file `qubes-r4.list`. You should overwrite this file.
```
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
[user@debian-<new> ~]$ sudo apt dist-upgrade
```
```
[user@debian-<new> ~]$ sudo apt update
[user@debian-<new> ~]$ sudo apt upgrade
[user@debian-<new> ~]$ sudo apt dist-upgrade
```
5. (Optional) Remove unnecessary packages that were previously installed.
```
[user@debian-<new> ~]$ sudo apt-get autoremove
```
```
[user@debian-<new> ~]$ sudo apt-get autoremove
```
6. (Optional) Clean cached packages from `/var/cache/apt`.
```
[user@debian-<new> ~]$ sudo apt-get clean
```
```
[user@debian-<new> ~]$ sudo apt-get clean
```
7. (Optional) Trim the new template.
(This should [no longer be necessary](/doc/templates/#important-notes), but it does not hurt.
Some users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055) that it makes a difference.)
7. (Optional) Trim the new template. (This should [no longer be
necessary](/doc/templates/#important-notes), but it does not hurt. Some
users have [reported](https://github.com/QubesOS/qubes-issues/issues/5055)
that it makes a difference.)
```
[user@debian-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-<new>
[user@dom0 ~]$ qvm-start debian-<new>
[user@debian-<new> ~]$ sudo fstrim -av
```
```
[user@debian-<new> ~]$ sudo fstrim -av
[user@dom0 ~]$ qvm-shutdown debian-<new>
[user@dom0 ~]$ qvm-start debian-<new>
[user@debian-<new> ~]$ sudo fstrim -av
```
8. Shut down the new template.
```
[user@dom0 ~]$ qvm-shutdown debian-<new>
```
```
[user@dom0 ~]$ qvm-shutdown debian-<new>
```
9. (Recommended) [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
9. (Recommended) [Switch everything that was set to the old template to the new
template.](/doc/templates/#switching)
10. (Optional) Make the new template the global default.
@ -116,12 +137,13 @@ The same general procedure may be used to upgrade any template based on the stan
[user@dom0 ~]$ qubes-prefs --set debian-<new>
```
11. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling)
Make sure that the template you're uninstalling is the old one, not the new one!
11. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling) Make
sure that the template you're uninstalling is the old one, not the new one!
## Standalones
The procedure for upgrading a Debian [standalone](/doc/standalone-and-hvm/) is the same as for a template.
The procedure for upgrading a Debian [standalone](/doc/standalone-and-hvm/) is
the same as for a template.
## Release-specific notes
@ -129,9 +151,16 @@ This section contains notes about upgrading to specific releases.
### Debian 11 ("Bullseye")
Please see [Debian's Bullseye upgrade instructions](https://www.debian.org/releases/bullseye/amd64/release-notes/ch-upgrading.en.html). In particular: for APT source lines referencing the security archive, the format has changed slightly along with the release name, going from buster/updates to bullseye-security; see [Section 5.1.2, “Changed security archive layout”](https://www.debian.org/releases/stable/mips64el/release-notes/ch-information.en.html#security-archive).
Please see [Debian's Bullseye upgrade
instructions](https://www.debian.org/releases/bullseye/amd64/release-notes/ch-upgrading.en.html).
In particular: for APT source lines referencing the security archive, the
format has changed slightly along with the release name, going from
buster/updates to bullseye-security; see [Section 5.1.2, “Changed security
archive
layout”](https://www.debian.org/releases/stable/mips64el/release-notes/ch-information.en.html#security-archive).
This means that when upgrading from `buster` to `bullseye` an additional `sed` command is required:
This means that, when upgrading from Buster to Bullseye, an additional `sed`
command is required:
```
[user@dom0 ~]$ qvm-clone debian-10 debian-11
@ -147,18 +176,24 @@ This means that when upgrading from `buster` to `bullseye` an additional `sed` c
### Debian 10 ("Buster")
Please see [Debian's Buster upgrade instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html).
Please see [Debian's Buster upgrade
instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgrading.en.html).
### Debian 9 ("Stretch")
* The upgrade process may prompt you to overwrite two files: `qubes-r4.list` and `pulse/client.conf`.
`qubes-r4.list` can be overwritten, but `pulse/client.conf` must be left as the currently-installed version.
* The upgrade process may prompt you to overwrite two files: `qubes-r4.list`
and `pulse/client.conf`. `qubes-r4.list` can be overwritten, but
`pulse/client.conf` must be left as the currently-installed version.
* If sound is not working, you may need to enable the Qubes testing repository to get the testing version of `qubes-gui-agent`.
This can be done by editing the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes Updates Candidates` repo.
* If sound is not working, you may need to enable the Qubes testing repository
to get the testing version of `qubes-gui-agent`. This can be done by editing
the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes
Updates Candidates` repo.
* User-initiated updates/upgrades may not run when a template first starts.
This is due to a new Debian config setting that attempts to update automatically; it should be disabled with `sudo systemctl disable apt-daily.{service,timer}`.
This is due to a new Debian config setting that attempts to update
automatically; it should be disabled with `sudo systemctl disable
apt-daily.{service,timer}`.
Relevant discussions:
@ -167,20 +202,29 @@ Relevant discussions:
* [Fixing sound in Debian Stretch](https://groups.google.com/forum/#!topic/qubes-users/JddCE54GFiU)
* [User apt commands blocked on startup](https://github.com/QubesOS/qubes-issues/issues/2621)
Also see [Debian's Stretch upgrade instructions](https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html).
Also see [Debian's Stretch upgrade
instructions](https://www.debian.org/releases/stretch/amd64/release-notes/ch-upgrading.en.html).
### Debian 8 ("Jessie")
Please see [Debian's Jessie upgrade instructions](https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html).
Please see [Debian's Jessie upgrade
instructions](https://www.debian.org/releases/jessie/amd64/release-notes/ch-upgrading.en.html).
### End-of-life (EOL) releases
We strongly recommend against using any Debian release that has reached [end-of-life (EOL)](https://wiki.debian.org/DebianReleases#Production_Releases).
We strongly recommend against using any Debian release that has reached
[end-of-life
(EOL)](https://wiki.debian.org/DebianReleases#Production_Releases).
## Additional information
* Please note that, if you installed packages from one of the testing repositories, you must make sure that the repository is enabled in `/etc/apt/sources.list.d/qubes-r4.list` before attempting the upgrade.
Otherwise, your upgrade will [break](https://github.com/QubesOS/qubes-issues/issues/2418).
* Please note that, if you installed packages from one of the
[testing](/doc/testing/) repositories, you must make sure that the repository
is enabled in `/etc/apt/sources.list.d/qubes-r4.list` before attempting the
upgrade. Otherwise, your upgrade will
[break](https://github.com/QubesOS/qubes-issues/issues/2418).
* By default, Qubes uses code names in the `apt` sources files, although the templates are referred to by release number.
Check the code names for the templates, and ensure you are aware of any changes you have made in the repository definitions.
* By default, Qubes uses code names in the `apt` sources files, although the
templates are referred to by release number. Check the code names for the
templates, and ensure you are aware of any changes you have made in the
repository definitions.