mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-03-01 03:11:19 -05:00
261 lines
9.3 KiB
ReStructuredText
261 lines
9.3 KiB
ReStructuredText
=========================================
|
||
How to upgrade a Debian template in-place
|
||
=========================================
|
||
|
||
|
||
.. DANGER::
|
||
Warning: This page is intended for advanced users only. Most users
|
||
seeking to upgrade should instead install a new Debian template.
|
||
Learn more about the two options here.
|
||
|
||
|
||
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/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 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/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
|
||
: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.
|
||
|
||
|