{{Header}} {{Title|title= Reinstall {{q_project_name_long}} Templates }} {{#seo: |description=How to Reinstall {{q_project_name_short}} Templates |image=Qubesreinstall123123.png }} {{qubes_mininav}} [[File:Qubesreinstall123123.png|250px|thumb]] {{intro| How to Reinstall {{q_project_name_short}} Templates }} = Introduction = On occasion, it is necessary to reinstall a {{project_name_long}} template from the Qubes repository. https://www.qubes-os.org/doc/how-to-reinstall-a-template/ {{mbox | type = notice | image = [[File:Ambox_notice.png|40px|alt=Info]] | text = Note: * If {{q_project_name_short}} 16 is installed and you want to get {{q_project_name_short}} 17, it is unnecessary to follow the instructions on this page. Refer to the [[Qubes/Install|Install {{q_project_name_short}}]] instructions instead, since this is easier. * If {{q_project_name_short}} 17 is installed and you want to get {{q_project_name_short}} 18, it is unnecessary to follow the instructions on this page. Refer to the [[Qubes/Install|Install {{q_project_name_short}}]] instructions instead, since this is easier. This is because the names of the Templates changed from: * whonix-gw-16 to whonix-gateway-17 * whonix-workstation-16 to whonix-workstation-17 }} This chapter usually applies when the Template is: * Outdated: To upgrade to a newer [[Point Release]] or a testers-only version of {{project_name_short}}. * Broken: Templates can become broken and/or unbootable for a number of reasons, such as when [[Debian_Packages#Packages_FAQ|removing meta-packages]] that {{project_name_short}} "depends" on to function properly, or after {{kicksecure_wiki |wikipage=Install_Software#Install_from_Debian_Testing |text=mixing packages }} from a later Debian release. * Misconfigured: Not all Template modifications are easily reversible. In some cases, it may be necessary to reinstall the Template. * Compromised: Users may suspect their Template has been compromised. For further information on this topic, see [[Malware and Firmware Trojans#Valid_Compromise_Indicators_versus_Invalid_Compromise_Indicators|Indicators of Compromise]]. * Testing: To ensure high quality of future {{project_name_short}} releases by becoming a {{project_name_short}} tester. == Warning == {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = If the {{project_name_short}} Template is broken, misconfigured, or potentially compromised, discontinue using any App Qubes based on the affected Template. }} The reason is that any App Qubes based on the affected Template will inherit the same issues. Disregarding this advice could lead to serious consequences. For example, a core component of the {{project_name_short}} security model depends on {{project_name_gateway_vm}} to force all traffic through Tor or block it. If {{project_name_gateway_vm}} is based on a Template with a misconfigured or broken firewall, the {{project_name_short}} security model would be broken. [[Dev/Technical_Introduction#With_more_technical_terms|Technical Introduction: With more technical terms]] == Reinstallation Methods == Qubes has its own [https://www.qubes-os.org/doc/how-to-reinstall-a-template/ template reinstallation guide]; however, this {{project_name_short}} wiki entry should be preferred when reinstalling [[Qubes|{{q_project_name_short}}]] Templates. The reason is that this guide is Whonix-specific and contains instructions on how to properly configure all settings. Using salt. {{mbox | type = notice | image = [[File:Ambox_notice.png|40px|alt=Info]] | text = Note: The root file system of the affected Template will be lost during the reinstallation process. It is recommended that you create a backup of any important files first. }} Use one of the following methods: * '''A)''' [[Qubes/Uninstall|Uninstall {{q_project_name_short}}]] and then [[Qubes/Install|Install {{q_project_name_short}}]]; OR * '''B)''' Follow the [[#Reinstall the {{project_name_short}} template|Reinstall the {{project_name_short}} template]] instructions below. = Reinstall the {{project_name_short}} template = == UpdateVM Setting == Since only Fedora-based UpdateVMs support the --action=upgrade option for reinstalling the Template, it is recommended that you create a dedicated Qubes dom0 UpdateVM based on Qubes' Fedora template. Forcing dom0 updates over Tor is still possible by setting {{project_name_gateway_vm}} as the NetVM for the UpdateVM. * sys-net → sys-firewall → {{project_name_gateway_vm}} → UpdateVM * UpdateVM → {{project_name_gateway_vm}} → sys-firewall → sys-net {{Box|text= '''1.''' Create a new VM named dom0-updatevm. Qubes VM Manager → VM → Create App Qube * Name and label: Name the App Qube. Do not include any personal information (if the App Qube is compromised, the attacker could run qubesdb-read /name to reveal the VM name). Name the App Qube something generic, for example: dom0-updatevm. * Color: Choose a color label for the UpdateVM. * Use this template: Choose the Fedora-based Template. For example: fedora-42. (There may be a higher version number than 34 available than there was at time time of writing.) * Standalone: Leave the Standalone field unchecked. * Type: Choose the type App Qube. * Allow networking: Choose the desired NetVM from the list. For example: {{project_name_gateway_vm}}. * Press: OK. '''2.''' Configure the NetVM setting of dom0-updatevm. * '''Option A, clearnet updates:''' If non-torified, clearnet Qubes dom0 updates are preferred, then set the NetVM of dom0-updatevm, for example, to sys-firewall. Qube Manager → dom0-updatevm → Qube settings → Networking: sys-firewall → OK {{CodeSelect|code= qvm-prefs updatevm-name netvm {{project_name_gateway_vm}} }} * '''Option B, torified updates:''' If torified Qubes dom0 updates are preferred, then set the NetVM of dom0-updatevm to {{project_name_gateway_long}}. Qube Manager → dom0-updatevm → Qube settings → Networking: {{project_name_gateway_vm}} → OK {{CodeSelect|code= qvm-prefs updatevm-name netvm {{project_name_gateway_vm}} }} '''3.''' The process of configuring the UpdateVM is now complete. If the dom0 UpdateVM is based on a Template that is broken or no longer trusted (the Template is broken, misconfigured, or compromised), an alternate UpdateVM can be used temporarily. In other words, more specifically, if the {{project_name_gateway_short}} Template ({{project_name_gateway_template}}) and/or its {{project_name_gateway_short}} ProxyVM ({{project_name_gateway_vm}}) are no longer trusted, then configure Qubes dom0 to use a different UpdateVM by applying the following steps. TODO }} == Update dom0 == {{Qubes_upgrade_dom0}} == Configure salt using Qubes dom0 Community Testing Repository == {{Qubes_testing}} == Reinstall == In the instructions below, a check is first made for a newer version of the Template. * Upgrade if available: If a newer Template version exists, install it (upgrade). * Reinstall if not: If no newer Template version is available, reinstall the existing version (reinstall). Unfortunately, there is no combined upgrade and reinstall command. [https://github.com/QubesOS/qubes-issues/issues/4518 qubes-dom0-update combined upgrade reinstall command] {{Box|text= '''1.''' {{Qubes_Terminal}} '''2.''' Try to upgrade the Template. * Requirement: This will only work if a new [[Point Release]] of the Template is available. * Template choice: Replace qubes-template-package with either qubes-template-whonix-workstation-{{VersionShort}} or qubes-template-whonix-gateway-{{VersionShort}}. * Testers: Replace --enablerepo=qubes-templates-community with --enablerepo=qubes-templates-community-testing if you are a tester. 
qvm-template --enablerepo=qubes-templates-community upgrade
For example, to upgrade the whonix-gateway-{{VersionShort}} Template: {{CodeSelect|code= qvm-template --enablerepo=qubes-templates-community upgrade whonix-gateway-{{VersionShort}} }} For example, to upgrade the whonix-workstation-{{VersionShort}} Template: {{CodeSelect|code= qvm-template --enablerepo=qubes-templates-community upgrade whonix-workstation-{{VersionShort}} }} '''3.''' Check the command output. The following results are possible: * Template was successfully upgraded: No further action required. Skip step four. * No upgrade available: The Template is already the latest version. Proceed to step four to force a reinstall. * Upgrade unsupported or failed: This may occur if your UpdateVM is not Fedora-based. Refer to [[Qubes/Reinstall#UpdateVM_Setting|UpdateVM Setting]]. * Unexpected error: Could be caused by networking issues or repository problems. Investigate and retry as necessary. '''4.''' ''Optional:'' Reinstall the Template. * When to reinstall: If step two did not reinstall the Template (i.e. no new Point Release), you may force a reinstall here. * Safety: Safe to run even if the Template is already up-to-date. It will simply be reinstalled. 
qvm-template --enablerepo=qubes-templates-community reinstall
For example, to reinstall the whonix-gateway-{{VersionShort}} Template: {{CodeSelect|code= qvm-template --enablerepo=qubes-templates-community reinstall qubes-template-whonix-gateway-{{VersionShort}} }} For example, to reinstall the whonix-workstation-{{VersionShort}} Template: {{CodeSelect|code= qvm-template --enablerepo=qubes-templates-community reinstall qubes-template-whonix-workstation-{{VersionShort}} }} * Template reinstalled successfully: Reinstallation completed without issues. * Error during reinstall: Likely caused by connectivity problems or misconfiguration. Review the error message and retry. }} == Settings == {{mbox | image = [[File:Ambox_warning_pn.svg.png|40px]] | text = This step is mandatory. [https://github.com/QubesOS/qubes-issues/issues/3447 phase out manual use of qubes-dom0-update by user / replace it by salt] }} Use salt to configure dom0 settings. [[Dev/Qubes#salt]] {{CodeSelect|code= sudo qubesctl state.sls qvm.{{project_name_workstation_vm}} }} = Optional Steps = == {{project_name_short}} Disposable Template == {{Qubes_Install_DVM}} == Updates over Tor == {{Qubes Install Updates over Tor}} == Enable AppArmor == {{Qubes_AppArmor}} = Final Steps = == Restart App Qubes == Any VMs based on the reinstalled Template must be restarted to reflect the updated file system. == Update and Launch Applications == {{Qubes Install Update and Launch Applications}} == Done == The process of reinstalling {{q_project_name_short}} Templates is now complete. = Footnotes = {{reflist|close=1}} {{Footer}} [[Category:Documentation]]