{{Header}}
{{Title|title=
Reinstall {{q_project_name_long}} Templates
}}
{{#seo:
|description=How to Reinstall {{q_project_name_short}} Templates
|image=Qubesreinstall123123.png
}}
{{qubes_mininav}}
[[image:Qubesreinstall123123.png|250px|thumb]]
{{intro|
How to Reinstall {{q_project_name_short}} Templates
}}
{{mbox
| type    = notice
| image   = [[File:Ambox_warning_pn.svg.png|40px|alt=Warning]]
| text    = <u>Note</u>: Broken in Qubes R4.1 due to Qubes upstream bug [https://github.com/QubesOS/qubes-issues/issues/7250 qvm-template reinstall broken - qvm-template: error: Same version of template 'whonix-gateway-16' not found. #7250].

Functional in Qubes R4.2.
}}
= Introduction =
'''{{free}}'''

On occasion it is necessary to reinstall a {{project_name_long}} template from the Qubes repository. <ref>https://www.qubes-os.org/doc/how-to-reinstall-a-template/</ref>

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = <u>Note</u>: 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 [[Qubes/Install|Install {{q_project_name_short}}]] instructions instead because it is easier. <ref>
This is because the name of the Templates changed from:

* <code>whonix-gw-16</code> to <code>whonix-gateway-17</code>
* <code>whonix-workstation-16</code> to <code>whonix-workstation-17</code>
</ref>
}}

This chapter usually applies when the template is:

*<u>Outdated</u>: To upgrade to a newer [[Point Release]] or testers-only version of {{project_name_short}}.
*<u>Broken</u>: Templates can become broken and/or unbootable for a number of reasons, like 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.
*<u>Misconfigured</u>: Not all Template modifications are easily reversible. In some cases it may be necessary to reinstall the Template.
*<u>Compromised</u>: 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]].
*<u>Testing</u>: To ensure a 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 obvious reason is any App Qubes that are 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 <code>{{project_name_gateway_vm}}</code> forcing all traffic through Tor or blocking it. If <code>{{project_name_gateway_vm}}</code> was based on a Template with a misconfigured or broken firewall, the {{project_name_short}} security model would be broken. <ref>[[Dev/Technical_Introduction#With_more_technical_terms|Technical Introduction: With more technical terms]]</ref>

== 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 for re-installation of [[Qubes|{{q_project_name_short}}]]. The reason is this guide is Whonix-specific and contains instructions on how to properly configure all settings. <ref>
Using salt.
</ref>

{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = <u>Note</u>: The root file system of the affected Template will be lost during the reinstallation process. It is recommended to create a backup of any important files first.
}}

Use <u>one</u> of the following methods:

* '''A)''' [[Qubes/Uninstall|Uninstall {{q_project_name_short}}]] and then [[Qubes/Install|Install {{q_project_name_short}}]]; <u>OR</u>
* '''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 <code>--action=upgrade</code> option for reinstalling the Template, it is recommended to create a dedicated Qubes <code>dom0</code> UpdateVM based on Qubes' Fedora template. Forcing <code>dom0</code> updates over Tor is still possible by setting <code>{{project_name_gateway_vm}}</code> as the NetVM for the UpdateVM. <ref>
* <code>sys-net</code> &rarr; <code>sys-firewall</code> &rarr; <code>{{project_name_gateway_vm}}</code> &rarr; <code>UpdateVM</code>
* <code>UpdateVM</code> &rarr; <code>{{project_name_gateway_vm}}</code> &rarr; <code>sys-firewall</code> &rarr; <code>sys-net</code>
</ref>

{{Box|text=
'''1.''' Create a new VM named <code>dom0-updatevm</code>.

<code>Qubes VM Manager</code> &rarr; <code>VM</code> &rarr; <code>Create App Qube</code>
* <u>Name and label</u>: Name the App Qube. Do not include any personal information (if the App Qube is compromised, the attacker could run <code>qubesdb-read /name</code> to reveal the VM name). Name the App Qube something generic, for example: <code>dom0-updatevm</code>.
* <u>Color</u>: Choose a color label for the UpdateVM.
* <u>Use this template</u>: Choose the <u>Fedora</u>-based Template. For example: <code>fedora-34</code>. (There may or may not be a higher version number than <code>34</code> than there was at time of writing.)
* <u>Standalone</u>: Leave the Standalone field unchecked.
* <u>Type</u>: Choose the type <code>App Qube</code>.
* <u>Allow networking</u>: Choose the desired NetVM from the list. For example: <code>{{project_name_gateway_vm}}</code>.
* <u>Press</u>: <code>OK</code>.

'''2.''' Configure the NetVM setting of <code>dom0-updatevm</code>.

* <u>'''Option A'''</u>: If non-torified, clearnet Qubes <code>dom0</code> updates are preferred, set the NetVM of <code>dom0-updatevm</code> for example to <code>sys-firewall</code>.

<code>Qube Manager</code> &rarr; <code>dom0-updatevm</code> &rarr; <code>Qube s<u>e</u>ttings</code> &rarr; <code>Networking: sys-firewall</code> &rarr; <code>OK</code> <ref>
{{CodeSelect|code=
qvm-prefs updatevm-name netvm {{project_name_gateway_vm}}
}}
</ref>

* <u>'''Option B'''</u>: If torified Qubes <code>dom0</code> updates are preferred, set the NetVM of <code>dom0-updatevm</code> to {{project_name_gateway_long}}.

<code>Qube Manager</code> &rarr; <code>dom0-updatevm</code> &rarr; <code>Qube s<u>e</u>ttings</code> &rarr; <code>Networking: {{project_name_gateway_vm}}</code> &rarr; <code>OK</code> <ref>
{{CodeSelect|code=
qvm-prefs updatevm-name netvm {{project_name_gateway_vm}}
}}
</ref>

'''3.''' The process of configuring the UpdateVM is now complete.

<ref>
If the <code>dom0</code> 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 (<code>{{project_name_gateway_template}}</code>) and/or its {{project_name_gateway_short}} ProxyVM (<code>{{project_name_gateway_vm}}</code>) are no longer trusted, then configure Qubes <code>dom0</code> to use a different UpdateVM by applying the following steps.

TODO
</ref>
}}

== Update dom0 ==
{{Qubes_upgrade_dom0}}

== Configure salt using Qubes dom0 Community Testing Repository ==
{{Qubes_testing}}

== Adjust {{project_name_short}} Version Number ==
{{Qubes_Adjust_Project_Version_Number}}

== Reinstall ==

In the instructions below, a check is first made for a newer version of the Template.

* If a newer Template version exists, install it (<code>upgrade</code>).
* If no newer Template version is available, reinstall the existing version (<code>reinstall</code>).

Unfortunately there is no combined upgrade and reinstall command. <ref>
[https://github.com/QubesOS/qubes-issues/issues/4518 qubes-dom0-update combined upgrade reinstall command]
</ref>

{{Box|text=
'''1.''' {{Qubes_Terminal}}

'''2.''' First try <u>upgrading</u> the Template.

This will only work if there is a new [[Point Release]] of the Template.

Execute the following command.

<u>Notes:</u>

* <u>Template choice:</u> Replace <code>qubes-template-package</code> with either: <code>qubes-template-whonix-workstation-{{VersionShort}}</code> or <code>qubes-template-whonix-gateway-{{VersionShort}}</code>, respectively.
* <u>Testers-Only:</u> Testers should replace <code>--enablerepo=qubes-templates-community</code> with <code>--enablerepo=qubes-templates-community-testing</code>.

Syntax:

<pre>
qvm-template --enablerepo=qubes-templates-community upgrade <qubes-template-package>
</pre>

For example, to reinstall and upgrade <code>whonix-gateway-{{VersionShort}}</code> Template.

{{CodeSelect|code=
qvm-template --enablerepo=qubes-templates-community upgrade whonix-gateway-{{VersionShort}}
}}

For example, to reinstall and upgrade <code>whonix-workstation-{{VersionShort}}</code> Template.

{{CodeSelect|code=
qvm-template --enablerepo=qubes-templates-community upgrade whonix-workstation-{{VersionShort}}
}}

'''3.''' Read the output of the above command. The following outcomes are possible, either:

* '''A)''' The Template is upgraded. In that case, skip step four below ("Reinstall the Template"); OR
* '''B)''' The commands above might finish relatively quickly and state <code>No new updates available</code>. In that case, proceed with step four below ("Reinstall the Template"); OR
* '''C)''' A Template upgrade is unsupported. This might happen if a non-Fedora based UpdateVM is used in conjunction with the <code>upgrade</code> option. See: [[Qubes/Reinstall#UpdateVM_Setting|UpdateVM Setting]] for further information; OR
* '''D)''' An error has occurred, such as a networking issue.

'''4.''' ''Optional:'' <u>Reinstall</u> the Template.

If <code>upgrade</code> at step two did not actually reinstall the Template, this means there is no new [[Point Release]] available at present. This also means the Template has not been actually reinstalled and further action is required (see below).

If unsure, the commands below are safe in any case because if you already have the latest Template version, then it will simply be reinstalled again.

Execute the following command.

<u>Notes:</u> Same notes as above apply.

Syntax:

<pre>
qvm-template --enablerepo=qubes-templates-community reinstall <qubes-template-package>
</pre>

For example, to reinstall <code>whonix-gateway-{{VersionShort}}</code> Template.

{{CodeSelect|code=
qvm-template --enablerepo=qubes-templates-community reinstall qubes-template-whonix-gateway-{{VersionShort}}
}}

For example, to reinstall <code>whonix-workstation-{{VersionShort}}</code> Template.

{{CodeSelect|code=
qvm-template --enablerepo=qubes-templates-community reinstall qubes-template-whonix-workstation-{{VersionShort}}
}}

Read the output of the above command. There are two possible outcomes, either:

* '''A)''' The Template was reinstalled; OR
* '''B)''' An error has occurred, such as a networking issue.
}}

== Settings ==

{{mbox
| image   = [[File:Ambox_warning_pn.svg.png|40px]]
| text    = This step is mandatory. <ref>
[https://github.com/QubesOS/qubes-issues/issues/3447 phase out manual use of qubes-dom0-update by user / replace it by salt]
</ref>
}}

Use <code>salt</code> to configure <code>dom0</code> settings. <ref>
[[Dev/Qubes#salt]]
</ref>

{{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]]