From 64716d81f077423bad48e2f97c2c25743597bc3b Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Thu, 1 Feb 2018 13:39:47 +0000 Subject: [PATCH 1/4] reinstall-template 4.0 update add 4.0 clone template procedure because dummy template no longer works --- managing-os/reinstall-template.md | 61 ++++++++++++++++++++++++++++++- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 2ef65908..ac85dfc0 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -11,7 +11,10 @@ How to Reinstall a TemplateVM If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository. -Starting in Qubes 3.1, the process is greatly simplified. + +If you are running Qubes R4.0, see "Manual Reinstallation Method (R4.0)" below. +For Qubes R3.1 or R3.2, keep reading. +For R3.0 and earlier, see "Manual Reinstallation Method (R3.0 or earlier)" below. First, copy any files that you wish to keep from the TemplateVM's `/home` and `/rw` folders to a safe storage location. Then, in a dom0 terminal, run: @@ -38,7 +41,61 @@ repo, you must enable that repo. For example: restarted. -Manual Reinstallation Method +Manual Reinstallation Method (R4.0) +---------------------------- + +If you're using Qubes 4.0 or newer, you should use the manual reinstallation +method. + +In what follows, the term "target TemplateVM" refers to whichever TemplateVM you +want to reinstall. If you want to reinstall more than one TemplateVM, repeat +these instructions for each one. + +1. Clone the existing target TemplateVM. + + This can be a good idea if you've customized the existing template and want + to keep your customizations. On the other hand, if you suspect that this + template is broken, misconfigured, or compromised, be certain you do not + start any VMs using it in the below procedure. + +2. Temporarily change all VMs based on the target TemplateVM to the new clone + template, or remove them. + + This can be a good idea if you have user data in these VMs that you want to + keep. On the other hand, if you suspect that these VMs (or the templates on + which they are based) are broken, misconfigured, or compromised, you may + want to remove them instead. You can do this in Qubes Manager by + right-clicking on the VM and clicking **Remove VM**, or you can use the + command `qvm-remove ` in dom0. + +3. Uninstall the target TemplateVM from dom0: + + $ sudo dnf remove + + For example, to uninstall the `whonix-gw` template: + + $ sudo dnf remove qubes-template-whonix-gw + +4. Reinstall the target TemplateVM in dom0: + + $ sudo qubes-dom0-update --enablerepo= \ + + + For example, to install the `whonix-gw` template: + + $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ + qubes-template-whonix-gw + +5. If you temporarily changed all VMs based on the target TemplateVM to the + clone template in step 3, change them back to the new target TemplateVM now. + If you instead removed all VMs based on the old target TemplateVM, you can + recreate your desired VMs from the newly reinstalled target TemplateVM now. + +6. Delete the cloned template. You can do this in Qubes Manager by + right-clicking on the VM and clicking **Remove VM**, or you can use the + command `qvm-remove ` in dom0. + +Manual Reinstallation Method (R3.0 or earlier) ---------------------------- If you're using Qubes 3.0 or older, you should use the manual reinstallation From b9f742376398be054e78d44db721a8ced1dad191 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Mon, 5 Feb 2018 15:39:33 +0000 Subject: [PATCH 2/4] reorder sections more logically and fix line breaks while I'm at it --- managing-os/reinstall-template.md | 131 ++++++++++++------------------ 1 file changed, 54 insertions(+), 77 deletions(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index ac85dfc0..093e16ff 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -9,64 +9,29 @@ redirect_from: How to Reinstall a TemplateVM ============================= -If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you -can reinstall any TemplateVM that was installed from the Qubes repository. +If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository. -If you are running Qubes R4.0, see "Manual Reinstallation Method (R4.0)" below. -For Qubes R3.1 or R3.2, keep reading. -For R3.0 and earlier, see "Manual Reinstallation Method (R3.0 or earlier)" below. - -First, copy any files that you wish to keep from the TemplateVM's `/home` and -`/rw` folders to a safe storage location. Then, in a dom0 terminal, run: - - $ sudo qubes-dom0-update --action=reinstall qubes-template-package-name - -Replace `qubes-template-package-name` with the name of the *package* of the -template you wish to reinstall. For example, use `qubes-template-fedora-25` if -you wish to reinstall the `fedora-25` template. Only one template can be -reinstalled at a time. - -Note that Qubes may initially refuse to perform the reinstall if the exact revision of -the template package on your system is no longer in the Qubes online repository. In -this case, you can specify `upgrade` as the action instead and the newer version will be -used. The other `dnf` package actions that are now supported in addition to `reinstall` -and `upgrade` are `upgrade-to` and `downgrade`. - -**Reminder:** If you're trying to reinstall a template that is not in an enabled -repo, you must enable that repo. For example: - - $ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws - -**Note:** VMs that are using the reinstalled template will not be affected until they are -restarted. +The procedure varies by Qubes version; see the appropriate section below. Manual Reinstallation Method (R4.0) ---------------------------- -If you're using Qubes 4.0 or newer, you should use the manual reinstallation -method. +If you're using Qubes 4.0 or newer, you should use the manual reinstallation method. -In what follows, the term "target TemplateVM" refers to whichever TemplateVM you -want to reinstall. If you want to reinstall more than one TemplateVM, repeat -these instructions for each one. +In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall. +If you want to reinstall more than one TemplateVM, repeat these instructions for each one. 1. Clone the existing target TemplateVM. - This can be a good idea if you've customized the existing template and want - to keep your customizations. On the other hand, if you suspect that this - template is broken, misconfigured, or compromised, be certain you do not - start any VMs using it in the below procedure. + This can be a good idea if you've customized the existing template and want to keep your customizations. + On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure. -2. Temporarily change all VMs based on the target TemplateVM to the new clone - template, or remove them. +2. Temporarily change all VMs based on the target TemplateVM to the new clone template, or remove them. - This can be a good idea if you have user data in these VMs that you want to - keep. On the other hand, if you suspect that these VMs (or the templates on - which they are based) are broken, misconfigured, or compromised, you may - want to remove them instead. You can do this in Qubes Manager by - right-clicking on the VM and clicking **Remove VM**, or you can use the - command `qvm-remove ` in dom0. + This can be a good idea if you have user data in these VMs that you want to keep. + On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead. + You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove ` in dom0. 3. Uninstall the target TemplateVM from dom0: @@ -86,32 +51,51 @@ these instructions for each one. $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ qubes-template-whonix-gw -5. If you temporarily changed all VMs based on the target TemplateVM to the - clone template in step 3, change them back to the new target TemplateVM now. - If you instead removed all VMs based on the old target TemplateVM, you can - recreate your desired VMs from the newly reinstalled target TemplateVM now. +5. If you temporarily changed all VMs based on the target TemplateVM to the clone template in step 3, change them back to the new target TemplateVM now. + If you instead removed all VMs based on the old target TemplateVM, you can recreate your desired VMs from the newly reinstalled target TemplateVM now. -6. Delete the cloned template. You can do this in Qubes Manager by - right-clicking on the VM and clicking **Remove VM**, or you can use the +6. Delete the cloned template. + You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove ` in dom0. + +Manual Reinstallation Method (R3.1 - R3.2) +---------------------------- + +First, copy any files that you wish to keep from the TemplateVM's `/home` and `/rw` folders to a safe storage location. +Then, in a dom0 terminal, run: + + $ sudo qubes-dom0-update --action=reinstall qubes-template-package-name + +Replace `qubes-template-package-name` with the name of the *package* of the template you wish to reinstall. +For example, use `qubes-template-fedora-25` if you wish to reinstall the `fedora-25` template. +Only one template can be reinstalled at a time. + +Note that Qubes may initially refuse to perform the reinstall if the exact revision of the template package on your system is no longer in the Qubes online repository. +In this case, you can specify `upgrade` as the action instead and the newer version will be used. +The other `dnf` package actions that are supported in addition to `reinstall` and `upgrade` are `upgrade-to` and `downgrade`. + +**Reminder:** If you're trying to reinstall a template that is not in an enabled repo, you must enable that repo. +For example: + + $ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws + +**Note:** VMs that are using the reinstalled template will not be affected until they are restarted. + + Manual Reinstallation Method (R3.0 or earlier) ---------------------------- -If you're using Qubes 3.0 or older, you should use the manual reinstallation -method. You can also use this method on later Qubes versions if, for any reason, -you want to reinstall a template manually. +If you're using Qubes 3.0 or older, you should use the manual reinstallation method. +You can also use this method on later Qubes versions if, for any reason, you want to reinstall a template manually. -In what follows, the term "target TemplateVM" refers to whichever TemplateVM you -want to reinstall. If you want to reinstall more than one TemplateVM, repeat -these instructions for each one. +In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall. +If you want to reinstall more than one TemplateVM, repeat these instructions for each one. 1. (Optional) Clone the existing target TemplateVM. - This can be a good idea if you've customized the existing template and want - to keep your customizations. On the other hand, if you suspect that this - template is broken, misconfigured, or compromised, you may want to remove it - without cloning it. + This can be a good idea if you've customized the existing template and want to keep your customizations. + On the other hand, if you suspect that this template is broken, misconfigured, or compromised, you may want to remove it without cloning it. 2. Create a temporary dummy template: @@ -119,19 +103,14 @@ these instructions for each one. touch /var/lib/qubes/vm-templates/dummy/{root.img,private.img} qvm-add-template dummy -3. Temporarily change all VMs based on the target TemplateVM to the new dummy - template, or remove them. +3. Temporarily change all VMs based on the target TemplateVM to the new dummy template, or remove them. - This can be a good idea if you have user data in these VMs that you want to - keep. On the other hand, if you suspect that these VMs (or the templates on - which they are based) are broken, misconfigured, or compromised, you may - want to remove them instead. You can do this in Qubes Manager by - right-clicking on the VM and clicking **Remove VM**, or you can use the - command `qvm-remove ` in dom0. + This can be a good idea if you have user data in these VMs that you want to keep. + On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead. + You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove ` in dom0. - Using a dummy template as a temporary template is preferable to using another - real TemplateVM because you can't accidentally boot any VMs from the dummy - template. (There is no OS in the dummy template, so the boot will fail.) + Using a dummy template as a temporary template is preferable to using another real TemplateVM because you can't accidentally boot any VMs from the dummy template. + (There is no OS in the dummy template, so the boot will fail.) 4. Uninstall the target TemplateVM from dom0: @@ -151,10 +130,8 @@ these instructions for each one. $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ qubes-template-whonix-gw -6. If you temporarily changed all VMs based on the target TemplateVM to the - dummy template in step 3, change them back to the new target TemplateVM now. - If you instead removed all VMs based on the old target TemplateVM, you can - recreate your desired VMs from the newly reinstalled target TemplateVM now. +6. If you temporarily changed all VMs based on the target TemplateVM to the dummy template in step 3, change them back to the new target TemplateVM now. + If you instead removed all VMs based on the old target TemplateVM, you can recreate your desired VMs from the newly reinstalled target TemplateVM now. [TemplateVM]: /doc/templates/ From 5bdba98b23af7973a6e93094a53cb98573953d8a Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Fri, 9 Feb 2018 15:16:52 +0000 Subject: [PATCH 3/4] relabel sections by UpdateVM type and reorder --- managing-os/reinstall-template.md | 52 +++++++++++++++---------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 093e16ff..ee3657bd 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -11,13 +11,35 @@ How to Reinstall a TemplateVM If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository. -The procedure varies by Qubes version; see the appropriate section below. +The procedure varies by Qubes version and UpdateVM's distribution; see the appropriate section below. -Manual Reinstallation Method (R4.0) +Manual Reinstallation Method (Fedora based UpdateVM, R3.1+) ---------------------------- -If you're using Qubes 4.0 or newer, you should use the manual reinstallation method. +First, copy any files that you wish to keep from the TemplateVM's `/home` and `/rw` folders to a safe storage location. +Then, in a dom0 terminal, run: + + $ sudo qubes-dom0-update --action=reinstall qubes-template-package-name + +Replace `qubes-template-package-name` with the name of the *package* of the template you wish to reinstall. +For example, use `qubes-template-fedora-25` if you wish to reinstall the `fedora-25` template. +Only one template can be reinstalled at a time. + +Note that Qubes may initially refuse to perform the reinstall if the exact revision of the template package on your system is no longer in the Qubes online repository. +In this case, you can specify `upgrade` as the action instead and the newer version will be used. +The other `dnf` package actions that are supported in addition to `reinstall` and `upgrade` are `upgrade-to` and `downgrade`. + +**Reminder:** If you're trying to reinstall a template that is not in an enabled repo, you must enable that repo. +For example: + + $ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws + +**Note:** VMs that are using the reinstalled template will not be affected until they are restarted. + + +Manual Reinstallation Method (Debian based UpdateVM, R3.1+) +---------------------------- In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall. If you want to reinstall more than one TemplateVM, repeat these instructions for each one. @@ -59,30 +81,6 @@ If you want to reinstall more than one TemplateVM, repeat these instructions for command `qvm-remove ` in dom0. -Manual Reinstallation Method (R3.1 - R3.2) ----------------------------- - -First, copy any files that you wish to keep from the TemplateVM's `/home` and `/rw` folders to a safe storage location. -Then, in a dom0 terminal, run: - - $ sudo qubes-dom0-update --action=reinstall qubes-template-package-name - -Replace `qubes-template-package-name` with the name of the *package* of the template you wish to reinstall. -For example, use `qubes-template-fedora-25` if you wish to reinstall the `fedora-25` template. -Only one template can be reinstalled at a time. - -Note that Qubes may initially refuse to perform the reinstall if the exact revision of the template package on your system is no longer in the Qubes online repository. -In this case, you can specify `upgrade` as the action instead and the newer version will be used. -The other `dnf` package actions that are supported in addition to `reinstall` and `upgrade` are `upgrade-to` and `downgrade`. - -**Reminder:** If you're trying to reinstall a template that is not in an enabled repo, you must enable that repo. -For example: - - $ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinstall qubes-template-whonix-ws - -**Note:** VMs that are using the reinstalled template will not be affected until they are restarted. - - Manual Reinstallation Method (R3.0 or earlier) ---------------------------- From b7399481849517309be07fc10e947958c5e60b77 Mon Sep 17 00:00:00 2001 From: awokd <34515595+awokd@users.noreply.github.com> Date: Wed, 21 Feb 2018 07:37:34 +0000 Subject: [PATCH 4/4] add procedure to determine distro --- managing-os/reinstall-template.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index ee3657bd..fbc7e360 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -13,6 +13,15 @@ If you suspect your [TemplateVM] is broken, misconfigured, or compromised, you c The procedure varies by Qubes version and UpdateVM's distribution; see the appropriate section below. +To determine your UpdateVM's distribution: + +1. Go to a `dom0` terminal prompt. +2. Enter `qubes-prefs` and look for `updatevm`. +3. Enter `qvm-prefs ` and look for `template`. + +This will typically be either `debian-9`, `fedora-26`, or `whonix-gw`. +In the case of `whonix-gw`, refer to the Debian based UpdateVM method. + Manual Reinstallation Method (Fedora based UpdateVM, R3.1+) ----------------------------