From a8d09e79f22ba6fae188f60354247e725bb08004 Mon Sep 17 00:00:00 2001 From: Will Morrison Date: Sun, 12 Jun 2016 08:50:34 -0400 Subject: [PATCH 01/13] Spelling and grammatical changes in live-usb.md --- installing/live-usb.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/installing/live-usb.md b/installing/live-usb.md index ad630bfb..c3b25227 100644 --- a/installing/live-usb.md +++ b/installing/live-usb.md @@ -16,8 +16,8 @@ can continue to improve it. Introduction ------------ -We have faced several challenges when making this Live USB edition of Qubes OS, -which traditional Linux distros don't have to bother with: +When making this Live USB edition of Qubes OS, we faced several challenges which +traditional Linux distros don't have to bother with: 1. We needed to ensure Xen is properly started when booting the stick. In fact we still don't support UEFI boot for the stick for this reason, even though @@ -39,20 +39,20 @@ few tens of MBs per VM, sometimes even more. Also, each VM's private image, which essentially holds just the user home directory, typically starts with a few tens of MBs for an "empty VM". Now, while these represent rather insignificant numbers on a disk-basked system, in the case of a live USB all -these files must be stored in RAM, which is a scare resource on any OS, but +these files must be stored in RAM, which is a scarce resource on any OS, but especially on Qubes. We have implemented some quick optimizations in order to minimize the above problem, but this is still far from a proper solution. We're planning to work more on this next. -Now, there are three directions in how we want to work further on this Qubes +There are three directions in which we want to do further work on this Qubes Live USB variant: 1. Introduce an easy, clickable "install to disk" option, merging this with the Qubes installation ISO. So, e.g. make it possible to first see if the given - hardware is compatible with Qubes (run the HCL reporting tool) and only then - install on the main disk. Also, ensure UEFI boot works well. + hardware is compatible with Qubes (by running the HCL reporting tool) and + only then install on the main disk. Also, ensure UEFI boot works well. 2. Introduce options for persistence while still running this out of a USB stick. This would be achieved by allowing (select) VMs' private images to be @@ -74,7 +74,7 @@ Live USB variant: Current limitations ------------------- -(Remember that Qubes Live USB is currently in alpha, so please meter your +(Remember that Qubes Live USB is currently in alpha, so please meter your expectations accordingly.) 1. Currently just the 3 example VMs (untrusted, personal, work), plus the @@ -90,10 +90,10 @@ expectations accordingly.) from a large Qubes backup blob. 5. It's easy to generate Out Of Memory (OOM) in Dom0 by creating lots of VMs which are writing a lot into the VMs filesystem. -6. There is no DispVM savefile, so if one starts one the savefile must be - regenerated which takes about 1-2 minutes. -7. UEFI boot doesn't work, and if you try booting it via UEFI Xen will not be - started, rendering the whole experiment unusable. +6. There is no DispVM savefile, so if you start a DispVM the savefile must be + regenerated, which takes about 1-2 minutes. +7. UEFI boot doesn't work, and if you try booting Qubes Live USB via UEFI, Xen + will not be started, rendering the whole experiment unusable. Downloading and burning From 8741932d5936323a1fcbd7e4e20d44e14305b127 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 06:26:58 -0700 Subject: [PATCH 02/13] Generalize whonix-reinstall to apply to all templates --- managing-os/reinstall-template.md | 74 +++++++++++++++++++++++++++++++ privacy/whonix-reinstall.md | 54 ---------------------- 2 files changed, 74 insertions(+), 54 deletions(-) create mode 100644 managing-os/reinstall-template.md delete mode 100644 privacy/whonix-reinstall.md diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md new file mode 100644 index 00000000..98c72bfc --- /dev/null +++ b/managing-os/reinstall-template.md @@ -0,0 +1,74 @@ +--- +layout: doc +title: How to Reinstall a TemplateVM +permalink: +redirect_from: +- /doc/whonix/reinstall/ +--- + +How to Reinstall a TemplateVM +============================= + +If you suspect your [TemplateVM] is broken, misconfigured, or compromised, +or if you wish to do a clean reinstall in order to upgrade to a new version, you +can reinstall any TemplateVM from the Qubes repository. In what follows, the +phrase "target TemplateVM" refers to whichever TemplateVM you want to reinsatll. +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. + +2. Create a temporary dummy template: + + mkdir /var/lib/qubes/vm-templates/dummy + 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. + + 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.) + +4. Uninstall the target TemplateVM from dom0: + + $ sudo yum remove + + For example, to uninstall the `whonix-gw` template: + + $ sudo yum remove qubes-template-whonix-gw + +5. 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 + +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. + + At a minimum, you'll want a ProxyVM (conventionally called `sys-whonix`) + based on `whonix-gw` and an AppVM based on `whonix-ws` that uses `sys-whonix` + as its NetVM. + +[TemplateVM]: /doc/templates/ + diff --git a/privacy/whonix-reinstall.md b/privacy/whonix-reinstall.md deleted file mode 100644 index ba755a37..00000000 --- a/privacy/whonix-reinstall.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: doc -title: Reinstall Whonix in Qubes -permalink: /doc/whonix/reinstall/ ---- - -Reinstall Whonix in Qubes -=========================== - -If you suspect your Whonix templates are broken, misconfigured, or compromised, -or if you wish to do a clean reinstall in order to upgrade to a new version, you -can reinstall the Whonix templates from the Qubes repository. This procedure -involves [uninstalling] your Whonix templates, then [installing] them again. - -1. (Optional) Clone your existing `whonix-gw` and `whonix-ws` templates. - - This can be a good idea if you've customized the existing templates and want - to keep them. On the other hand, if you suspect that these templates are - broken, misconfigured, or compromised, you may want to remove them - without cloning them. - -2. (Optional) Temporarily change all VMs based on `whonix-gw` and `whonix-ws` to - another template (e.g., the ones created in the previous step). - - 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 Whonix templates from dom0: - - $ sudo yum remove qubes-template-whonix-gw - $ sudo yum remove qubes-template-whonix-ws - -4. Reinstall the Whonix templates in dom0: - - $ sudo qubes-dom0-update --enablerepo=qubes-templates-community \ - qubes-template-whonix-gw qubes-template-whonix-ws - -5. If you followed step 2, change the VMs from step 2 back to the new - `whonix-gw` and `whonix-ws`. If you instead removed all VMs based on the old - `whonix-gw` and `whonix-ws`, simply create your desired VMs from the new - templates. - - At a minimum, you'll want a ProxyVM (conventionally called `sys-whonix`) - based on `whonix-gw` and an AppVM based on `whonix-ws` that uses `sys-whonix` - as its NetVM. - - -[uninstalling]: /doc/whonix/uninstall/ -[installing]: /doc/whonix/install/ - From 85c5eda80c0b61795fa75516f68948ceef1a62f7 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 07:45:37 -0700 Subject: [PATCH 03/13] Update manual USB qube creation instructions Also: Fix broken link to Assigning Devices page This commit updates the manual USB qube creation instructions based on user feedback from this discussion thread: https://groups.google.com/d/topic/qubes-users/mPPZy57kw0w/discussion --- common-tasks/usb.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/common-tasks/usb.md b/common-tasks/usb.md index d6e7ec4c..be2a4b6f 100644 --- a/common-tasks/usb.md +++ b/common-tasks/usb.md @@ -28,7 +28,7 @@ Qubes OS supports the ability to attach a USB drive (or just one or more of its partitions) to any qube easily, no matter which qube actually handles the USB controller. (The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the -[qvm-pci][assigning-devices] command. For guidance on finding the correct USB +[qvm-pci][Assigning Devices] command. For guidance on finding the correct USB controller, see [here][usb-controller].) USB drive mounting is integrated into the Qubes VM Manager GUI. Simply insert @@ -182,13 +182,25 @@ steps as root in dom0: Alternatively, you can create a USB qube manually as follows: - 1. In a dom0 terminal, type `lsusb` to check if you have a USB controller free - of input devices or programmable devices. If you find such free controller, - note its name and proceed to step 2. + 1. Read the [Assigning Devices] page to learn how to list and identify your + USB controllers. Carefully check whether you have a USB controller that + would be appropriate to assign to a USB qube. Note that it should be free + of input devices, programmable devices, and any other devices that must be + directly available to dom0. If you find a free controller, note its name + and proceed to step 2. 2. Create a new qube. Give it an appropriate name and color label - (recommended: `sys-usb`, red). - 3. In the qube's settings, go to the "Devices" tab. Find your USB controller - in the "Available" list. Move it to the "Selected" list. + (recommended: `sys-usb`, red). If you need to attach a networking device, + it might make sense to create a NetVM. If not, an AppVM might make more + sense. (The default `sys-usb` is a NetVM.) + 3. In the qube's settings, go to the "Devices" tab. Find the USB controller + that you identified in step 1 in the "Available" list. Move it to the + "Selected" list. + + **Caution:** By assigning a USB controller to a USB qube, it will no longer + be available to dom0. This can make your system unusable if, for example, + you have only one USB controller, and you are running Qubes off of a USB + drive. + 4. Click "OK." Restart the qube. 5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot." (This will help to mitigate attacks in which @@ -242,7 +254,7 @@ You can now use your USB keyboard. [mass-storage]: https://en.wikipedia.org/wiki/USB_mass_storage_device_class -[devices]: /doc/assigning-devices/ +[Assigning Devices]: /doc/assigning-devices/ [usb-controller]: /doc/assigning-devices/#finding-the-right-usb-controller [623]: https://github.com/QubesOS/qubes-issues/issues/623 [1072-comm1]: https://github.com/QubesOS/qubes-issues/issues/1072#issuecomment-124270051 From b633b720337f83d3c2731433b54b03705a16cde4 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:47:43 -0700 Subject: [PATCH 04/13] Remove old Whonix-specific sentence --- managing-os/reinstall-template.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 98c72bfc..8479a71f 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -66,9 +66,5 @@ each one. 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. - At a minimum, you'll want a ProxyVM (conventionally called `sys-whonix`) - based on `whonix-gw` and an AppVM based on `whonix-ws` that uses `sys-whonix` - as its NetVM. - [TemplateVM]: /doc/templates/ From 61407aec0a2a479383e17093ee08e42947d64430 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:53:03 -0700 Subject: [PATCH 05/13] Set permalink --- managing-os/reinstall-template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/managing-os/reinstall-template.md b/managing-os/reinstall-template.md index 8479a71f..975cbd39 100644 --- a/managing-os/reinstall-template.md +++ b/managing-os/reinstall-template.md @@ -1,7 +1,7 @@ --- layout: doc title: How to Reinstall a TemplateVM -permalink: +permalink: /doc/reinstall-template/ redirect_from: - /doc/whonix/reinstall/ --- From 967765281085c70d64ce7ec5900f5b9569b3948e Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:53:28 -0700 Subject: [PATCH 06/13] Add link to Reinstall page --- managing-os/templates.md | 1 + 1 file changed, 1 insertion(+) diff --git a/managing-os/templates.md b/managing-os/templates.md index 6837e739..39c09d60 100644 --- a/managing-os/templates.md +++ b/managing-os/templates.md @@ -27,6 +27,7 @@ available only as source code, which can be built using are available in source code form only. Take a look at the [Qubes Builder documentation](/doc/qubes-builder/) for instructions on how to compile them. +To reinstall a currently installed TemplateVM, see [here](/doc/reinstall-template/). ITL Supported templates ----------------------- From 485bd1d7f7ae3554495aa9ecf32c3b04017dbe12 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:53:51 -0700 Subject: [PATCH 07/13] Remove link to old Reinstall page --- privacy/whonix.md | 1 - 1 file changed, 1 deletion(-) diff --git a/privacy/whonix.md b/privacy/whonix.md index dd60d58c..06565e86 100644 --- a/privacy/whonix.md +++ b/privacy/whonix.md @@ -32,7 +32,6 @@ To install Whonix, you must have a working Qubes machine already. ## Customizing, Reinstalling, & Uninstalling Whonix * [Customizing Whonix](/doc/whonix/customize/) -* [Reinstall Whonix in Qubes](/doc/whonix/reinstall/) * [Uninstall Whonix from Qubes](/doc/whonix/uninstall/) *The following links are on Whonix's website and are technical.* From 4a50b0179ef715c51869644ed1dc482da3be7b27 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 10:54:07 -0700 Subject: [PATCH 08/13] Add ToC entry for new Reinstall page --- doc.md | 1 + 1 file changed, 1 insertion(+) diff --git a/doc.md b/doc.md index 4060e4c1..cbfdcbd8 100644 --- a/doc.md +++ b/doc.md @@ -63,6 +63,7 @@ Managing Operating Systems within Qubes * [Templates: Archlinux](/doc/templates/archlinux/) * [Templates: Ubuntu](/doc/templates/ubuntu/) * [Templates: Whonix](/doc/whonix/) + * [How to Reinstall a TemplateVM](/doc/reinstall-template) * [Installing and Using Windows-based AppVMs (Qubes R2 Beta 3 and later)](/doc/windows-appvms/) * [Creating and Using HVM and Windows Domains (Qubes R2+)](/doc/hvm/) * [Advanced options and troubleshooting of Qubes Tools for Windows (R3)](/doc/windows-tools-3/) From c664629e4b053f93ce41a0e7358846555a141ad9 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:31:52 -0700 Subject: [PATCH 09/13] Create section on dom0 testing repos --- common-tasks/software-update-dom0.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 7490ba43..2f22d011 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -94,6 +94,29 @@ If you've installed a package such as anti-evil-maid, you can remove it with the sudo yum remove anti-evil-maid ~~~ +### Testing repositories + +There are three Qubes dom0 testing repoistories: + +* `current-testing` -- testing packages that will eventually land in the stable + (`current`) repository +* `security-testing` -- a subset of `current-testing` that contains packages + that qualify as security fixes +* `unstable` -- packages that are not intended to land in the stable (`current`) + repository; mostly experimental debugging packages + +To temporarily enable any of these repos, use the `--enablerepo=` +option. Example commands: + +~~~ +sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing +sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing +sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable +~~~ + +To enable any of these repos permanently, change the corresponding boolean in +`/etc/yum.repos.d/qubes-dom0.repo`. + ### Kernel Upgrade ### Install newer kernel. The following example installs kernel 3.19 and was tested on Qubes R3 RC1. From 1585c5cc6729ef971e01c806d447feda1a25ac52 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:32:25 -0700 Subject: [PATCH 10/13] Fix formatting --- common-tasks/software-update-dom0.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 2f22d011..a3dd7e45 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -90,9 +90,7 @@ You can re-install in a similar fashion to downgrading. If you've installed a package such as anti-evil-maid, you can remove it with the following command: - ~~~ sudo yum remove anti-evil-maid - ~~~ ### Testing repositories From 3abcd5776e008ac727f84fb9de8fbdf5c029c754 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:35:23 -0700 Subject: [PATCH 11/13] Use full repo names --- common-tasks/software-update-dom0.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index a3dd7e45..27857056 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -96,11 +96,11 @@ If you've installed a package such as anti-evil-maid, you can remove it with the There are three Qubes dom0 testing repoistories: -* `current-testing` -- testing packages that will eventually land in the stable +* `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable (`current`) repository -* `security-testing` -- a subset of `current-testing` that contains packages +* `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages that qualify as security fixes -* `unstable` -- packages that are not intended to land in the stable (`current`) +* `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`) repository; mostly experimental debugging packages To temporarily enable any of these repos, use the `--enablerepo=` From 4f0aad927024dbcafff437c6e5e5b08adeccac6a Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:39:09 -0700 Subject: [PATCH 12/13] Create section on VM testing repos --- common-tasks/software-update-vm.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/common-tasks/software-update-vm.md b/common-tasks/software-update-vm.md index b6878d9d..12e8866b 100644 --- a/common-tasks/software-update-vm.md +++ b/common-tasks/software-update-vm.md @@ -35,6 +35,30 @@ In order to permanently install new software, you should: - You will see now that all the AppVMs based on this template (by default all your VMs) will be marked as "outdated" in the manager. This is because their fielsystems have not been yet updated -- in order to do that, you must restart each VM. You don't need to restart all of them at the same time -- e.g. if you just need the newly installed software to be available in your 'personal' domain, then restart only this VM. You will restart others whenever this will be convenient to you. +Testing repositories +-------------------- + +There are three Qubes VM testing repoistories (where `*` denotes the Release): + +* `qubes-vm-*-current-testing` -- testing packages that will eventually land in the stable + (`current`) repository +* `qubes-vm-*-security-testing` -- a subset of `qubes-vm-*-current-testing` that contains packages + that qualify as security fixes +* `qubes-vm-*-unstable` -- packages that are not intended to land in the stable (`qubes-vm-*-current`) + repository; mostly experimental debugging packages + +To temporarily enable any of these repos, use the `--enablerepo=` +option. Example commands: + +~~~ +sudo dnf upgrade --enablerepo=qubes-vm-*-current-testing +sudo dnf upgrade --enablerepo=qubes-vm-*-security-testing +sudo dnf upgrade --enablerepo=qubes-vm-*-unstable +~~~ + +To enable or disable any of these repos permanently, change the corresponding boolean in +`/etc/yum.repos.d/qubes-*.repo`. + Reverting changes to a TemplateVM --------------------------------- From 5189bb00394d762922196848ac07083829cb9fde Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 12 Jun 2016 11:41:36 -0700 Subject: [PATCH 13/13] Clarify that testing repos can be enabled or disabled --- common-tasks/software-update-dom0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common-tasks/software-update-dom0.md b/common-tasks/software-update-dom0.md index 27857056..1f806b15 100644 --- a/common-tasks/software-update-dom0.md +++ b/common-tasks/software-update-dom0.md @@ -112,7 +112,7 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable ~~~ -To enable any of these repos permanently, change the corresponding boolean in +To enable or disable any of these repos permanently, change the corresponding boolean in `/etc/yum.repos.d/qubes-dom0.repo`. ### Kernel Upgrade ###