{{Header}}
{{title|title=
Release Upgrade {{project_name_long}} 16 to {{project_name_long}} 17
}}
{{#seo:
|description=How to Release Upgrade from {{project_name_short}} 16 to {{project_name_short}} 17
|image=Upgrade.jpg
}}
[[File:Upgrade.jpg|thumb]]
{{intro|
How to Release Upgrade from {{project_name_short}} 16 to {{project_name_short}} 17
}}

= Notices =
'''Table:''' ''Release Upgrade {{project_name_short}} Notices''

{| class="wikitable"
|-
! scope="col"| '''Notice'''
! scope="col"| '''Description'''
|-

! scope="row"| Difficulty
|
* Downloading a new {{project_name_gateway_long}} / {{project_name_workstation_long}} ([[Factory Reset]]) is easier than applying the [[Release Upgrade|Release Upgrade]] instructions on this page.
* Debian release notes:
** [https://www.debian.org/releases/bookworm/amd64/release-notes/ch-upgrading.en.html Chapter 4. Upgrades from Debian 11 (bullseye)]
** [https://www.debian.org/releases/bookworm/amd64/release-notes/ch-information Chapter 5. Issues to be aware of for bookworm]
|-
! scope="row"| Release Upgrade vs Re-Installation
|
To use [[About|{{project_name_short}}]] 17, users can either:

* '''A)''' Release upgrade existing {{project_name_short}} 16 images using the instructions on this page; <u>OR</u>
* '''B)''' Factory Reset using the {{project_name_short}} re-install method by downloading the new release, which is much simpler than upgrading:
** [[{{non_q_project_name_short}}|{{non_q_project_name_short}}]] 17: [[Download|download the new release]].
** [[{{q_project_name_short}}|{{q_project_name_long}}]] 17: [[Qubes/Install|download the new release]].
|-

! scope="row"| Standard Updates
|
* For standard ("everyday") update instructions see [[Operating System Software and Updates]]. <br />
* The instructions on this page describe how to perform a [[Release Upgrade]] from {{project_name_short}} 16 to {{project_name_short}} 17.
|-

! scope="row"| Automated Release Upgrade vs Manual Release Upgrade
|
* [[#Release Upgrade|Automated Release Upgrade]] is the newer method that has been implemented. It does not ask for user input and is therefore easier to use.
* The former Manual Release Upgrade effectively did the same, but it offered more control over system customization. It is now [[Deprecated#Manual Release Upgrade|deprecated]]. <ref>
This method is still possible. All the automated [https://github.com/{{project_name_short}}/legacy-dist/blob/master/usr/sbin/release-upgrade <code>release-upgrade</code>] script does is perform actions which the user could perform manually. If a manual release upgrade is desired, emulate what the <code>release-upgrade</code> script is doing. The manual release upgrading procedure is [[Unsupported|undocumented]] due to the size of the instructions and duplication involved.
</ref>
|-

! scope="row"| Configuration Files Resets
| Since this is an automated release upgrade, user modified configuration files (if any) in folder <code>/etc</code> will be reset, overwritten with the Debian or {{project_name_short}} package version. The user is free to restore the configuration after the release upgrade.
|-

|}

= High Level Overview =

# Backup all data - ideally have a copy of the VM(s) so it is possible to try again (if necessary).
# Perform the usual [[Operating_System_Software_and_Updates#Standard_Upgrade_Steps|standard ("everyday") update instructions]].
# Consider running the optional [[#Sanity Tests|sanity tests]].
# Release Upgrade {{project_name_workstation_short}}
# Power off {{project_name_workstation_short}}
# Release Upgrade {{project_name_gateway_short}}
# Restart {{project_name_gateway_short}}
# Restart {{project_name_workstation_short}}

= Sanity Tests =

<div class="toccolours mw-collapsible mw-collapsed">
These are optional, but recommended. To complete sanity tests, please press on expand on the right.
<div class="mw-collapsible-content">
{{CodeSelect|code=
sudo dpkg --audit ; echo $?
}}

Expected output.

{{CodeSelect|code=
0
}}

{{CodeSelect|code=
sudo dpkg --configure -a ; echo $?
}}

Expected output.

{{CodeSelect|code=
0
}}

[[Operating System Software and Updates|Get package upgrades.]]

{{CodeSelect|code=
sudo apt update
}}

{{CodeSelect|code=
sudo apt full-upgrade
}}

For testing purposes, install package <code>nano</code>.

{{CodeSelect|code=
sudo apt install nano ; echo $?
}}

{{CodeSelect|code=
## ... successful installation of nano ...
0
}}

Apt install fix missing.

{{CodeSelect|code=
sudo apt install -f
}}

Expected upgrade.

<pre>
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
</pre>
</div>
</div>

= Release Upgrade =

# Backup all data - ideally have a clone of the VM(s) so it is possible to try again (if necessary).
# Perform the usual [[Operating_System_Software_and_Updates#Standard_Upgrade_Steps|standard ("everyday") update instructions]].
# Consider running the optional [[#Sanity Tests|sanity tests]].
# Run [https://www.kicksecure.com/wiki/Systemcheck systemcheck].
# View <code>release-upgrade</code> command version. {{CodeSelect|code=
cat /usr/sbin/release-upgrade {{!}} grep version=
}}
# Check <code>release-upgrade</code> command version. Should be minimum <code>2.0</code>, should show <code>version="2.0"</code>.
# Consider keeping the full release upgrade log output. It will be required for [[Support]] in case there are issues.
# Perform the automated [[Release Upgrade|release upgrade]] using <code>release-upgrade</code> command. {{CodeSelect|code=
sudo release-upgrade
}}
# Done. If everything went well, at the end it will show: <blockquote>INFO: OK. (release-upgrade version: 2.0) Release upgrade success.</blockquote>
# Reboot.
# Optional, recommended: [[Debian_Packages|Re-install Meta Packages and Safely Run Autoremove]]

= Footnotes =

{{reflist|close=1}}

[[Category:Documentation]]

{{Footer}}