mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-08-11 16:10:45 -04:00
Convert to RST
This is done using tools at https://github.com/maiska/qubes-translation-utilz, commit 4c8e2a7f559fd37e29b51769ed1ab1c6cf92e00d.
This commit is contained in:
Marek Marczykowski-Górecki
parent
e3db139fe3
commit
7e464d0f40
428 changed files with 32833 additions and 29703 deletions
|
|
@ -1,230 +0,0 @@
|
|||
---
|
||||
advanced: true
|
||||
lang: en
|
||||
layout: doc
|
||||
permalink: /doc/templates/debian/in-place-upgrade/
|
||||
redirect_from:
|
||||
- /doc/template/debian/upgrade/
|
||||
- /doc/templates/debian/upgrade/
|
||||
- /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 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).
|
||||
|
||||
## Summary instructions for Debian templates
|
||||
|
||||
**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>
|
||||
[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 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.
|
||||
|
||||
**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>
|
||||
```
|
||||
|
||||
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 template.
|
||||
|
||||
```
|
||||
[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 default_template 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!
|
||||
|
||||
## Standalones
|
||||
|
||||
The procedure for upgrading a Debian [standalone](/doc/standalone-and-hvm/) is
|
||||
the same as for a template.
|
||||
|
||||
## Release-specific notes
|
||||
|
||||
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).
|
||||
|
||||
This means that, when upgrading from Buster to Bullseye, an additional `sed`
|
||||
command is required:
|
||||
|
||||
```
|
||||
[user@dom0 ~]$ qvm-clone debian-10 debian-11
|
||||
[user@dom0 ~]$ qvm-run -a debian-11 gnome-terminal
|
||||
[user@debian-<new> ~]$ sudo sed -i 's/buster/bullseye/g' /etc/apt/sources.list
|
||||
[user@debian-<new> ~]$ sudo sed -i 's/debian-security bullseye\/updates/debian-security bullseye-security/g' /etc/apt/sources.list
|
||||
[user@debian-<new> ~]$ sudo sed -i 's/buster/bullseye/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-11
|
||||
```
|
||||
|
||||
### Debian 10 ("Buster")
|
||||
|
||||
Please see [Debian's Buster upgrade
|
||||
instructions](https://www.debian.org/releases/buster/amd64/release-notes.en.txt).
|
||||
|
||||
### 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 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}`.
|
||||
|
||||
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.en.txt).
|
||||
|
||||
### Debian 8 ("Jessie")
|
||||
|
||||
Please see [Debian's Jessie upgrade
|
||||
instructions](https://www.debian.org/releases/jessie/amd64/release-notes.en.txt).
|
||||
|
||||
### 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](/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.
|
||||
208
user/templates/debian/debian-upgrade.rst
Normal file
208
user/templates/debian/debian-upgrade.rst
Normal file
|
|
@ -0,0 +1,208 @@
|
|||
=========================================
|
||||
How to upgrade a Debian template in-place
|
||||
=========================================
|
||||
|
||||
.. warning::
|
||||
|
||||
This page is intended for advanced users.
|
||||
|
||||
.. DANGER::
|
||||
|
||||
**Warning:** This page is intended for advanced users only. Most users seeking to upgrade should instead :ref:`install a new Debian template <user/templates/debian/debian:installing>`. Learn more about the two options :ref:`here <user/templates/debian/debian:upgrading>`.
|
||||
|
||||
This page provides instructions for performing an in-place upgrade of an installed :doc:`Debian Template </user/templates/debian/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 :doc:`Debian Template </user/templates/debian/debian>` page instead. (:ref:`Learn more about the two options. <user/templates/debian/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
|
||||
-----------------------------------------
|
||||
|
||||
|
||||
**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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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:** :ref:`Switch everything that was set to the old template to the new template. <user/templates/templates:switching>`
|
||||
|
||||
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.
|
||||
|
||||
**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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@dom0 ~]$ qvm-shutdown debian-<old>
|
||||
|
||||
|
||||
2. Clone the existing template and start a terminal in the new template.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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.)
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@debian-<new> ~]$ sudo apt-get autoremove
|
||||
|
||||
|
||||
|
||||
6. (Optional) Clean cached packages from ``/var/cache/apt``.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@debian-<new> ~]$ sudo apt-get clean
|
||||
|
||||
|
||||
|
||||
7. (Optional) Trim the new template. (This should :ref:`no longer be necessary <user/templates/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.)
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[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.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@dom0 ~]$ qvm-shutdown debian-<new>
|
||||
|
||||
|
||||
9. (Recommended) :ref:`Switch everything that was set to the old template to the new template. <user/templates/templates:switching>`
|
||||
|
||||
10. (Optional) Make the new template the global default.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@dom0 ~]$ qubes-prefs --set default_template debian-<new>
|
||||
|
||||
|
||||
11. (Optional) :ref:`Uninstall the old template. <user/templates/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 :doc:`standalone </user/advanced-topics/standalones-and-hvms>` is the same as for a template.
|
||||
|
||||
Release-specific notes
|
||||
----------------------
|
||||
|
||||
|
||||
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>`__.
|
||||
|
||||
This means that, when upgrading from Buster to Bullseye, an additional ``sed`` command is required:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
[user@dom0 ~]$ qvm-clone debian-10 debian-11
|
||||
[user@dom0 ~]$ qvm-run -a debian-11 gnome-terminal
|
||||
[user@debian-<new> ~]$ sudo sed -i 's/buster/bullseye/g' /etc/apt/sources.list
|
||||
[user@debian-<new> ~]$ sudo sed -i 's/debian-security bullseye\/updates/debian-security bullseye-security/g' /etc/apt/sources.list
|
||||
[user@debian-<new> ~]$ sudo sed -i 's/buster/bullseye/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-11
|
||||
|
||||
|
||||
Debian 10 ("Buster")
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Please see `Debian’s Buster upgrade instructions <https://www.debian.org/releases/buster/amd64/release-notes.en.txt>`__.
|
||||
|
||||
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 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}``.
|
||||
|
||||
|
||||
|
||||
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.en.txt>`__.
|
||||
|
||||
Debian 8 ("Jessie")
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Please see `Debian’s Jessie upgrade instructions <https://www.debian.org/releases/jessie/amd64/release-notes.en.txt>`__.
|
||||
|
||||
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 :doc:`testing </user/downloading-installing-upgrading/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.
|
||||
|
||||
|
||||
|
|
@ -1,108 +0,0 @@
|
|||
---
|
||||
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 [template](/doc/templates/) is an officially [supported](/doc/supported-releases/#templates) template in Qubes OS.
|
||||
The Current version is Debian 12 ("bookworm"). It is available in 3 versions - `debian-12`, a standard template; `debian-12-xfce`, a larger template with more installed applications, selected for [Xfce](/doc/templates/xfce/); `debian-12-minimal`.
|
||||
This page is about the "full" templates.
|
||||
For the minimal version, please see the [Minimal templates](/doc/templates/minimal/) page.
|
||||
|
||||
## Installing
|
||||
|
||||
To [install](/doc/templates/#installing) a specific Debian template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
|
||||
|
||||
```
|
||||
$ qvm-template install XX
|
||||
```
|
||||
(Replace `XX` with the name of the template you wish to install.)
|
||||
|
||||
To reinstall a Debian template that is already installed in your system, see [How to Reinstall a template](/doc/reinstall-template/).
|
||||
|
||||
## After Installing
|
||||
|
||||
After installing a fresh Debian template, we recommend performing the following steps:
|
||||
|
||||
1. [Update the template](/doc/software-update-vm/).
|
||||
|
||||
2. [Switch any app qubes that are based on the old template to the new one](/doc/templates/#switching).
|
||||
|
||||
3. If desired, [uninstall the old template](/doc/templates/#uninstalling).
|
||||
|
||||
## Installing software
|
||||
|
||||
See [How to Install Software](/doc/how-to-install-software/).
|
||||
|
||||
## Updating
|
||||
|
||||
For routine daily updates within a given release, see [How to Update](/doc/how-to-update/).
|
||||
|
||||
## Upgrading
|
||||
|
||||
There are two ways to upgrade your template to a new Debian release:
|
||||
|
||||
- **Recommended:** [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.
|
||||
|
||||
- **Advanced:** [Perform an in-place upgrade of an existing Debian template.](/doc/templates/debian/in-place-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 12
|
||||
|
||||
The Debian-12 templates that ship with release 4.2.4 cannot be used for salting Fedora templates. You must change the template used by `default-mgmt-dvm` to a Fedora template. You can do this in the Qubes Template Switcher tool, or at the command line using `qvm-prefs default-mgmt-dvm template`.
|
||||
|
||||
If you have a Debian template from an earlier release that you want to use for salting Qubes, you **must** stop the salt-common and salt-ssh packages from being upgraded.
|
||||
Do this by marking these packages on hold *before* updating the template.
|
||||
|
||||
```
|
||||
sudo apt-mark hold salt-common salt-ssh
|
||||
sudo apt update
|
||||
sudo apt upgrade
|
||||
```
|
||||
This is a [known bug](https://github.com/QubesOS/qubes-issues/issues/9129) in Salt which affects version 3006-5.
|
||||
|
||||
### 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 Debian templates, 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)
|
||||
131
user/templates/debian/debian.rst
Normal file
131
user/templates/debian/debian.rst
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
================
|
||||
Debian templates
|
||||
================
|
||||
|
||||
|
||||
The Debian :doc:`template </user/templates/templates>` is an officially :ref:`supported <user/downloading-installing-upgrading/supported-releases:templates>` template in Qubes OS. The Current version is Debian 12 (“bookworm”). It is available in 3 versions - ``debian-12``, a standard template; ``debian-12-xfce``, a larger template with more installed applications, selected for :doc:`Xfce </user/templates/xfce-templates>`; ``debian-12-minimal``. This page is about the “full” templates. For the minimal version, please see the :doc:`Minimal templates </user/templates/minimal-templates>` page.
|
||||
|
||||
Installing
|
||||
----------
|
||||
|
||||
|
||||
To :ref:`install <user/templates/templates:installing>` a specific Debian template that is not currently installed in your system, use the Qubes Template Manager, or use the following command in a dom0 terminal:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ qvm-template install XX
|
||||
|
||||
|
||||
|
||||
(Replace ``XX`` with the name of the template you wish to install.)
|
||||
|
||||
To reinstall a Debian template that is already installed in your system, see :doc:`How to Reinstall a template </user/how-to-guides/how-to-reinstall-a-template>`.
|
||||
|
||||
After Installing
|
||||
----------------
|
||||
|
||||
|
||||
After installing a fresh Debian template, we recommend performing the following steps:
|
||||
|
||||
1. :doc:`Update the template </user/how-to-guides/how-to-install-software>`.
|
||||
|
||||
2. :ref:`Switch any app qubes that are based on the old template to the new one <user/templates/templates:switching>`.
|
||||
|
||||
3. If desired, :ref:`uninstall the old template <user/templates/templates:uninstalling>`.
|
||||
|
||||
|
||||
|
||||
Installing software
|
||||
-------------------
|
||||
|
||||
|
||||
See :doc:`How to Install Software </user/how-to-guides/how-to-install-software>`.
|
||||
|
||||
Updating
|
||||
--------
|
||||
|
||||
|
||||
For routine daily updates within a given release, see :doc:`How to Update </user/how-to-guides/how-to-update>`.
|
||||
|
||||
Upgrading
|
||||
---------
|
||||
|
||||
|
||||
There are two ways to upgrade your template to a new Debian release:
|
||||
|
||||
- **Recommended:** `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 :ref:`switch everything that was set to the old template to the new template <user/templates/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.
|
||||
|
||||
- **Advanced:** :doc:`Perform an in-place upgrade of an existing Debian template. </user/templates/debian/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 12
|
||||
^^^^^^^^^
|
||||
|
||||
|
||||
The Debian-12 templates that ship with release 4.2.4 cannot be used for salting Fedora templates. You must change the template used by ``default-mgmt-dvm`` to a Fedora template. You can do this in the Qubes Template Switcher tool, or at the command line using ``qvm-prefs default-mgmt-dvm template``.
|
||||
|
||||
If you have a Debian template from an earlier release that you want to use for salting Qubes, you **must** stop the salt-common and salt-ssh packages from being upgraded. Do this by marking these packages on hold *before* updating the template.
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo apt-mark hold salt-common salt-ssh
|
||||
sudo apt update
|
||||
sudo apt upgrade
|
||||
|
||||
|
||||
|
||||
This is a `known bug <https://github.com/QubesOS/qubes-issues/issues/9129>`__ in Salt which affects version 3006-5.
|
||||
|
||||
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``:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
systemctl unmask ssh
|
||||
systemctl start ssh
|
||||
|
||||
|
||||
|
||||
Don’t forget to make the file executable.
|
||||
|
||||
Unattended Upgrades
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
Some users have noticed that on upgrading Debian templates, 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 :ref:`this guide. <user/troubleshooting/vm-troubleshooting:fixing package installation errors>`
|
||||
Loading…
Add table
Add a link
Reference in a new issue