{{Header}}
{{title|title=
Operating System Software and Updates
}}
{{#seo:
|description=This page contains details on updating the {{project_name_long}} operating system, including frozen packages. Most software in {{project_name_long}} is maintained in a frozen state to ensure stability, so updates primarily focus on critical security fixes. The page also covers update indicators, version numbers, release upgrades versus re-installation, and common issues and their solutions.
|image=Operatingsystemupdated234234.jpg
}}
{{release_mininav}}
[[image:Operatingsystemupdated234234.jpg|thumb]]
{{intro|
This page contains details on updating the {{project_name_short}} operating system, including frozen packages. Most software in {{project_name_short}} is maintained in a frozen state to ensure stability, so updates primarily focus on critical security fixes. The page also covers update indicators, version numbers, release upgrades versus re-installation, and common issues and their solutions.
}}
= Updates =

== Introduction ==
{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = '''All packages must stay up-to-date for security purposes.'''
}}
<!--
* '''[[Qubes|Qubes {{project_name_short}}]]:''' Follow the [[Qubes/Update|{{q_project_name_long}} Update Guide]].
* '''All other {{project_name_short}} OS builds:''' Follow the update instructions below.
-->

== Special Notices ==
Currently none.

== Frozen Packages ==

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = As {{project_name_short}} is based on the stable Debian distribution, software is normally [https://release.debian.org/{{Stable project version based on Debian codename}}/freeze_policy.html "frozen" to the stable Debian version] at the [https://www.debian.org/releases/ point of each major Debian release]. The Debian packages page notes: <ref>
https://www.debian.org/distrib/packages
</ref>

{{Quotation
|quote=This is the latest official release of the Debian distribution. This is stable and well tested software, which changes only if major security or usability fixes are incorporated.
}}
}}

As a distribution, Debian's compilation of software is mostly acquired from "upstream" third parties (the original software vendors). Debian has embraced the principle of software stability which means each major release "freezes" software versions. As a result the stable distribution software is not regularly updated except for critical security fixes. This is called "security support" and only leads to minimal changes across the entire distribution. The intent is to improve stability by reducing the overall number of system changes.

The frozen packages policy means the versions of software installed from Debian package sources will not usually change when a newer release is made available by upstream. <ref>
https://forums.whonix.org/t/keepassxc-2-5-4/9669
</ref>

== Application Specific Update Indicators ==
In most cases, specific end user applications such as [[electrum]] show notifications about the availability of newer versions can be safely ignored since electrum is also a [[#Frozen Packages|Frozen Packages]]. No manual user action required. To receive security advisories should there be a special case that requires manual user action, see [[Stay_Tuned|Follow {{project_name_short}} Developments]].

Application specific update indicators should not be shown to the user, should be disabled by Debian. This is a bug that shouldn't happen. It is happening due to the [[Linux User Experience versus Commercial Operating Systems|organisational background]].

== Standard Update vs Release Upgrade ==

There are two different types of updates.

# Standard Update
# Release Upgrade

This procedure on this wiki page is for ''standard'' ("everyday") updating of {{non_q_project_name_short}} and will not perform a [[Release Upgrade]].

It is recommended to first complete a [[#Standard_Update_Steps|standard update]] before applying a release upgrade.

== Update vs Image Re-Installation ==

The [[#Standard_Update_Steps|standard ("everyday") update]] procedure for {{non_q_project_name_short}} is more convenient than a complete re-installation of {{project_name_short}} images because all (VM) settings and user data are persistent. Backups are possible using (VM) clones and/or snapshots.

In contrast, a complete re-installation of {{project_name_short}} images requires {{project_name_short}} to be completely removed and then re-installed, similar to newcomers installing the platform for the first time. This is "cleaner" and elaborated on the [[Factory Reset]] page. Obviously all (VM) settings and data are lost during this procedure. If this is necessary, follow these steps:

* <u>[[Qubes|{{q_project_name_short}}]]</u>: [[Qubes/Uninstall|uninstall {{q_project_name_short}}]] and then [[Qubes/Uninstall|install {{q_project_name_short}}]].
* <u>[[Qubes|{{non_q_project_name_short}}]]</u>: remove any {{project_name_short}} (VMs) and then re-install them.

Developers periodically announce a newer {{project_name_short}} [[Point Release]] or major release. To stay informed about releases, see: [[Stay Tuned|Follow {{project_name_short}} Developments]]. It is recommended to subscribe to relevant news channels for this purpose.

Standard updates are generally easier, but image re-installation can completely avoid [[Dev/Stateless|technical issues]] that might emerge during upgrades.

== Standard Update Steps ==

{{Box|text=
{{Operating_System_Updates}}
}}

= End-of-life Software =

{{End_of_life_software}}

= Issues =
{{Anchor|fasttrack 500  SSL error: wrong version number}}
== fasttrack repository issues ==
If an issue happens such as...

<pre>
SOCKS proxy socks5h://127.0.0.1:9050 could not connect to fasttrack.debian.net (0.0.0.0:0) due to: general SOCKS server failure (1) [IP: 127.0.0.1 9050]
</pre>

Or...

<pre>
Err:4 http://HTTPS///fasttrack.debian.net/debian bookworm-fasttrack InRelease
  500  SSL error: wrong version number [IP: 127.0.0.1 3142]
</pre>

Or similar.

* Cause: That’s an issue caused by Debian fasttrack.
* Workarounds: 
** '''A)''' Fasttrack Repository Ignoring Method: Ignore this issue according to instructions below.
** '''B)''' Fasttrack Repository Disabling Method: Temporarily disable Debian fasttrack repository until this gets resolved in Debian. Documented below.
* Fixed when? Debian hopefully, probably will notice this would any need for a bug report since that is happening to all users of Debian fasttrack.
* forum discussion: https://forums.whonix.org/t/update-issue-fasttrack-repository-issue/15876

Choose either workaround '''A)''' <u>or</u> '''B)'''.

{{Tab
|type=controller
|content=
{{Tab
|active=true
|addToClass=info-box
|title= == A) Fasttrack Repository Ignoring Method ==
|content=
'''1.''' upgrade-nonroot notice

Upgrading <code>upgrade-nonroot</code> will not be possible but that is no concern as <code>upgrade-nonroot</code> internally uses APT which is still functional according to instructions below.

'''2.''' Update the package lists.

{{CodeSelect|code=
sudo apt update
}}

'''3.''' Ignore if the fasttrack repository cannot be updated.

This is OK because package lists for other repositoryies will still be updated.

'''4.''' Continue upgrading as usual according to the instructions on this wiki page generally.

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

'''5.''' Done.

The workaround has been completed.
}}

{{Tab
|addToClass=info-box
|title= == B) Fasttrack Repository Disabling Method ==
|content=
'''1.''' {{Open with root rights|filename=
/etc/apt/sources.list.d/debian.list
}}

'''2.''' Edit the file.

Search the following line (approximately line 28).

Optional: In the editor the feature View -> Line numbers might be helpful.

<pre>
deb tor+https://fasttrack.debian.net/debian bookworm-fasttrack main contrib non-free
</pre>

Comment it out by adding a hash ("<code>#</code>") in front of it. Should look like the following.

{{CodeSelect|code=
#deb tor+https://fasttrack.debian.net/debian bookworm-fasttrack main contrib non-free
}}

'''3.''' Save and exit.

'''4.''' Remember to re-enable this repository.

Add an appointment to your callender with a reminder to re-enable that in 1-2 weeks or so.

'''5.''' Done.

The process of disabling the Debian fasttrack repository has been completed.
}}
}} <!-- End Tab Controller -->

== Release File Expired Error ==
Same as below.

== InRelease is not valid yet error ==
A release file expired error can look like this.

<pre>
E: Release file for tor+https://fasttrack.debian.net/debian/dists/bookworm-fasttrack/InRelease is not valid yet (invalid for another 49s). Updates for this repository will not be applied.
</pre>

'''1.''' Retry.

If this message is transient, it can be safely ignored. Try again later. There is a good chance that is has been resolved.

'''2.''' Platform specific.

* Non-Qubes: no platform specific step reuqired.
* Qubes: If using Qubes, try [[#Standard Update Steps|Standard Update Steps]] instead of Qubes update tool.

'''3.''' Attempt to debug the issue.

See the following box.

{{box|text=
'''A)''' fasttrack in Debian

If it's an issue with the fasttrack repository, for debugging the issue further, the user could try to [[Install_Software#Enable_Debian_Fasttrack_Repository|enable the Debian fasttrack repository]] in the Qubes Debian template and attempt to reproduce the issue there as per [[Reporting_Bugs#Generic_Bug_Reproduction|generic bug reproduction]] and report the result to the forums.

'''B)''' Check the release file.

When this issue is happening, could you please check this link/file?

https://fasttrack.debian.net/debian/dists/bookworm-fasttrack/Release

Note the <code>Date:</code> and <code>Valid-Until</code> fields.

<pre>
Date: Sat, 20 Nov 2021 15:30:10 UTC
Valid-Until: Sat, 27 Nov 2021 15:30:10 UTC
</pre>

'''C)''' Note the VM time.

Inside the VM.

{{CodeSelect|code=
date --utc
}}

'''D)''' Note the host time.

On the host operating system (or dom0 when using Qubes).

{{CodeSelect|code=
date --utc
}}

'''E)''' Report to developers.

If none of the following gave any ideas how to fix the issue, please copy the error message and results from above debugging steps to developers. Forum discussion:
https://forums.whonix.org/t/whonix-ws-16-fails-to-update-due-to-timing-issue/12739
}}

== does not have a Release file ==
<pre>
E: The repository 'tor+deb.kicksecure.com bookworm Release' does not have a Release file.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.
</pre>
'''1.''' User exceptions.

100% uptime should not be expected. See also [[Trust#Server_Downtime|server downtime]].

'''2.''' Retry.

If this message is transient, it can be safely ignored. Try again later. There is a good chance that is has been resolved.

== APT Hash Sum Mismatch ==

A hash sum mismatch can look like this.

<pre>
W: Failed to fetch https://deb.debian.org/debian/dists/stable/main/i18n/Translation-enIndex  Hash Sum mismatch
</pre>

This might occur due to Tor and/or network unreliability issues. If this warning message is transient, it can be safely ignored. Otherwise, try one of the fixes below.
# [[Tor_Controller#Nyx|Change the Tor circuit]] and/or try again later.
# If the warning message still persists, deleting the package lists should solve it. <ref>
https://askubuntu.com/questions/41605/trouble-downloading-updates-due-to-hash-sum-mismatch-error
</ref>

To delete the package lists, run:

{{CodeSelect|code=
sudo rm -rf /var/lib/apt/lists/*
}}

To check everything is functional, update the package lists and then upgrade the distribution. It is likely  that previous update/upgrade attempts failed due to the mismatch.

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

[[File:Windows_logo_-_2012.svg.png|15px|link=]] Windows <u>10</u>, [[File:Virtualbox_logo.png|25px|link=]] VirtualBox users only: refer to the [https://forums.whonix.org/t/hash-sum-mismatch-downloads-all-fail-since-win10-2004-update/9740/2 Hash Sum mismatch?] forum thread.

== Non-functional Onion Services ==

{{Non-functional Onion Services}}

== Broken APT ==
This chapter is dedicated to providing a series of commands that can help in fixing a broken APT system. However, it's important to note that these steps might not resolve all cases of broken APT.

'''1.''' Relation to Debian.

Since [[About#Based_on_Debian|{{project_name_short}} is based on Debian]], the methods to fix broken APT are also [[unspecific|applicable to {{project_name_short}}]].

'''2.''' Interactive vs Non-interactive Commands.

For each troubleshooting step, two types of commands are provided. Choose one. No need to use both.

* '''A)''' <u>Interactive</u>: Commands without the <code>-noninteractive</code> suffix.
* '''B)''' <u>Non-interactive</u>: Commands with the <code>-noninteractive</code> suffix, available in Kicksecure to avoid user prompts.

'''3.''' Update the Package Lists.

{{CodeSelect|code=
sudo apt update
}}

'''4.''' Resolve Incomplete DPKG Processes.

Since APT uses DPKG internally, ensure to complete any interrupted DPKG processes:

* {{CodeSelect|code=
sudo dpkg --configure -a
}}
* {{CodeSelect|code=
sudo dpkg-noninteractive --configure -a
}}

'''5.''' Address Interrupted APT Processes.

To continue any interrupted APT processes:

* {{CodeSelect|code=
sudo apt install -f
}}
* {{CodeSelect|code=
sudo apt-get-noninteractive install -f
}}

'''6.''' Address Interrupted APT Processes.

To continue any interrupted APT processes:

* {{CodeSelect|code=
sudo apt full-upgrade -f
}}
* {{CodeSelect|code=
sudo apt-get-noninteractive full-upgrade -f
}}

'''7.''' Run a DPKG audit.

The following command does not fix anything but might return error messages which might be helpful to resolve this issue.

* {{CodeSelect|code=
dpkg --audit
}}

* If the command outputs nothing, then this is a good sign.
* If the command outputs something, then you need to address this.

'''8.''' Additional Steps for Persistent Issues.

If the issue persists, consult the [[Self Support First Policy]] and consider enhancing this documentation.

= Advanced =
== Non-Torified Updates ==
[[About#torified_updates|By {{project_name_short}} default, all updates are torified, which is a security feature.]]

To optionally update without Tor, apply the following instructions.

{{Testers-only}}

'''1.''' Platform specific notice:

* {{project_name_short}}: No special notice.
* Whonix: These instructions won't work for Whonix (a derivative of Kicksecure).

'''2.''' Configure {{project_name_short}} APT sources to use plain TLS.

{{CodeSelect|code=
sudo repository-dist --transport plain-tls
}}

'''3.''' Configure Debian APT sources to use plain TLS.

{{CodeSelect|code=
sudo str_replace "tor+https" "https" /etc/apt/sources.list.d/debian.list
}}

'''4.''' Notice.

These instructions are not an absolute prevention of never using Tor.

Optional: To avoid ever using Tor, system Tor needs to be removed.

Note: Understanding [[Debian Packages|meta packages]] is required.

{{CodeSelect|code=
sudo apt purge tor
}}

'''5.''' Done.

The process of setting up non-torified (clearnet TLS) updates has been completed.

= See Also =

* [[Install Software|Install Additional Software Safely]]
* [[Configuration Files]]
* [[Operating_System_Software_and_Updates#Changed_Configuration_Files|Changed Configuration Files]]
* [[Configuration_Files#Reset_Configuration_Files_to_Vendor_Default|Reset Configuration Files to Vendor Default]]
* [[Factory Reset]]
* [[Project-APT-Repository|{{project_name_short}} APT Repository]]
* [[Install_Software#How-to:_Install_or_Update_with_Utmost_Caution|How-to: Install or Update with Utmost Caution]]
* [[root#Graphical Applications with Root Rights|Safely Use Root Commands: Graphical Applications with Root Rights]]
* [[Firmware Security and Updates]]

= Footnotes =
{{reflist|close=1}}

{{Footer}}

[[Category:Documentation]]