mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-07-30 10:09:23 -04:00
Update and reorganize documentation
- Convert "Common Tasks" to "How-to Guides" (QubesOS/qubes-issues#6694) - Make title capitalization consistent across docs - Fix leftover h1 headings - Reorganize various pages and topics - Update permalinks to better match titles - Create redirects for changed permalinks - Miscellaneous cleanup QubesOS/qubes-issues#6701
This commit is contained in:
Andrew David Wong
parent
12408884dd
commit
6d81f95cc2
73 changed files with 101 additions and 107 deletions
168
user/templates/debian/debian-upgrade.md
Normal file
168
user/templates/debian/debian-upgrade.md
Normal file
|
|
@ -0,0 +1,168 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/template/debian/upgrade/
|
||||
redirect_from:
|
||||
- /doc/template/debian/upgrade-8-to-9/
|
||||
- /doc/debian-template-upgrade-8/
|
||||
- /en/doc/debian-template-upgrade-8/
|
||||
- /doc/DebianTemplateUpgrade8/
|
||||
- /wiki/DebianTemplateUpgrade8/
|
||||
ref: 133
|
||||
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 TemplateVM</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 TemplateVM](/doc/templates/debian/).
|
||||
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM](/doc/templates/debian/) page instead. ([Learn more about the two options.](/doc/templates/debian/#upgrading))
|
||||
|
||||
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system](https://wiki.debian.org/DebianUpgrade).
|
||||
|
||||
## Summary instructions for Debian TemplateVMs
|
||||
|
||||
**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.
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ qvm-clone debian-<old> debian-<new>
|
||||
[user@dom0 ~]$ qvm-run -a debian-<new> gnome-terminal
|
||||
[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 apt update
|
||||
[user@debian-<new> ~]$ sudo apt upgrade
|
||||
[user@debian-<new> ~]$ sudo apt dist-upgrade
|
||||
[user@dom0 ~]$ qvm-shutdown debian-<new>
|
||||
```
|
||||
|
||||
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
|
||||
|
||||
## Detailed instructions for Debian TemplateVMs
|
||||
|
||||
These instructions will show you how to upgrade Debian TemplateVMs.
|
||||
The same general procedure may be used to upgrade any template based on the standard Debian TemplateVM.
|
||||
|
||||
**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.
|
||||
|
||||
1. Ensure the existing template is not running.
|
||||
|
||||
```
|
||||
[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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
5. (Optional) Remove unnecessary packages that were previously installed.
|
||||
|
||||
```
|
||||
[user@debian-<new> ~]$ sudo apt-get autoremove
|
||||
```
|
||||
|
||||
6. (Optional) Clean cached packages from `/var/cache/apt`.
|
||||
|
||||
```
|
||||
[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.)
|
||||
|
||||
```
|
||||
[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 TemplateVM.
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ qvm-shutdown debian-<new>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
[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!
|
||||
|
||||
## StandaloneVMs
|
||||
|
||||
The procedure for upgrading a Debian [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
|
||||
|
||||
## Release-specific notes
|
||||
|
||||
This section contains notes about upgrading to specific releases.
|
||||
|
||||
### Debian 10 ("Buster")
|
||||
|
||||
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.
|
||||
|
||||
* 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 templateVM 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}`.
|
||||
|
||||
Relevant discussions:
|
||||
|
||||
* [Stretch Template Installation](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/4rdayBF_UTc)
|
||||
* [Stretch availability in 3.2](https://groups.google.com/forum/#!topicsearchin/qubes-devel/debian$20stretch/qubes-devel/cekPfBqQMOI)
|
||||
* [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).
|
||||
|
||||
### Debian 8 ("Jessie")
|
||||
|
||||
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).
|
||||
|
||||
## 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).
|
||||
|
||||
* 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.
|
||||
|
||||
109
user/templates/debian/debian.md
Normal file
109
user/templates/debian/debian.md
Normal file
|
|
@ -0,0 +1,109 @@
|
|||
---
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/templates/debian/
|
||||
redirect_from:
|
||||
- /doc/debian/
|
||||
- /en/doc/templates/debian/
|
||||
- /doc/Templates/Debian/
|
||||
- /wiki/Templates/Debian/
|
||||
ref: 134
|
||||
title: Debian Templates
|
||||
---
|
||||
|
||||
|
||||
The Debian [TemplateVM](/doc/templates/) is an officially [supported](/doc/supported-versions/#templatevms) TemplateVM in Qubes OS.
|
||||
This page is about the standard (or "full") Debian TemplateVM.
|
||||
For the minimal version, please see the [Minimal TemplateVMs](/doc/templates/minimal/) page.
|
||||
There is also a [Qubes page on the Debian Wiki](https://wiki.debian.org/Qubes).
|
||||
|
||||
## Installing
|
||||
|
||||
To [install](/doc/templates/#installing) a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
|
||||
|
||||
```
|
||||
$ sudo qubes-dom0-update qubes-template-debian-XX
|
||||
```
|
||||
|
||||
(Replace `XX` with the Debian version number of the template you wish to install.)
|
||||
|
||||
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
|
||||
|
||||
## After Installing
|
||||
|
||||
After installing a fresh Debian TemplateVM, we recommend performing the following steps:
|
||||
|
||||
1. [Update the TemplateVM](/doc/software-update-vm/).
|
||||
|
||||
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
|
||||
|
||||
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
|
||||
|
||||
## Updating
|
||||
|
||||
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs](/doc/software-update-domu/#updating-software-in-templatevms).
|
||||
|
||||
## Upgrading
|
||||
|
||||
There are two ways to upgrade your TemplateVM to a new Debian release:
|
||||
|
||||
- [Install a fresh template to replace the existing one.](#installing) **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.
|
||||
|
||||
- [Perform an in-place upgrade of an existing Debian template.](/doc/template/debian/upgrade/) This option will preserve any modifications you've made to the template, **but it may be more complicated for less experienced users.**
|
||||
|
||||
## Release-specific notes
|
||||
|
||||
This section contains notes about specific Debian releases.
|
||||
|
||||
### Debian 10
|
||||
|
||||
Debian 10 (buster) - minimal:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10-minimal
|
||||
```
|
||||
|
||||
Debian 10 (buster) - stable:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10
|
||||
```
|
||||
|
||||
### Starting services
|
||||
|
||||
The Debian way (generally) is to start daemons if they are installed.
|
||||
This means that if you install (say) ssh-server in a template, *all* the qubes that use that template will run a ssh server when they start. (They will, naturally, all have the same server key.) This may not be what you want.
|
||||
|
||||
So be very careful when installing software in Templates - if the daemon spawns outbound connections then there is a serious security risk.
|
||||
|
||||
In general, a reasonable approach would be, (using ssh as example):
|
||||
|
||||
- Install the ssh service.
|
||||
- `systemctl stop ssh`
|
||||
- `systemctl disable ssh`
|
||||
- `systemctl mask ssh`
|
||||
- Close down template
|
||||
|
||||
Now the ssh service will **NOT** start in qubes based on this template.
|
||||
|
||||
Where you **DO** want the service to run, put this in `/rw/config/rc.local`:
|
||||
|
||||
```
|
||||
systemctl unmask ssh
|
||||
systemctl start ssh
|
||||
```
|
||||
|
||||
Don't forget to make the file executable.
|
||||
|
||||
### Unattended Upgrades
|
||||
|
||||
Some users have noticed that on upgrading to Stretch, the `unattended-upgrade` package is installed.
|
||||
|
||||
This package is pulled in as part of a Recommend chain, and can be purged.
|
||||
|
||||
The lesson is that you should carefully look at what is being installed to your system, particularly if you run `dist-upgrade`.
|
||||
|
||||
### Package installation errors in Qubes 4.0
|
||||
|
||||
If some packages throw installation errors, see [this guide.](/doc/vm-troubleshooting/#fixing-package-installation-errors)
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue