From c813fd0f49eb4d715fb2c2bbe92ca24dd1eb9175 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Mon, 15 Jul 2019 05:12:50 +0530 Subject: [PATCH 001/141] Update https://www.qubes-os.org/doc/config-files/ --- user/advanced-configuration/config-files.md | 108 ++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index ca1fc3f0..66ef70c0 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -95,6 +95,43 @@ global: { #secure_paste_sequence = "Ctrl-Shift-v"; #windows_count_limit = 500; #audio_low_latency = false; + #screen + #root_win + #root_width + #root_height + #context + #frame_gc + #tray_gc + #tint_h + #inter_appviewer_lock_fd + #domid + #target_domid + #agent_version + #cmdline_color + #label_color_rgb + #cmdline_icon + #icon_data + #icon_data_len + #label_index + #screen_window + #clipboard_requested + #windows_count + #log_level + #nofork + #invisible + #kill_on_connect + #allow_utf8_titles + #allow_fullscreen + #copy_seq_mask + #paste_seq_mask + #qrexec_clipboard + #use_kdialog + #audio_low_latency + #prefix_titles + #trayicon_mode + #trayicon_border + #trayicon_tint_reduce_saturation + #trayicon_tint_whitehack }; # most of setting can be set per-VM basis @@ -127,3 +164,74 @@ Currently supported settings: - `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). Note that this will cause much higher CPU usage in dom0. +- `screen` - Points on default screen + +- `root_win` - Root attributes + +- `root_width` - Size of root window + +- `context` - context for pixmap operations + +- `frame_gc` - graphics context for painting window frame + +- `tray_gc` - graphic context for painting tray background, only in + TRAY_BACKGROUND mode + +- `tint_h` - precomputed H and S for tray coloring - only in TRAY_TINT mode + +- `inter_appviewer_lock_fd` - FD of lock file used to synchronize shared memory + access + +- `domid` - Xen domain id (GUI) + +- `target_domid` - Xen domain id (VM) - can differ from domid when GUI is + stubdom + +- `cmdline_color` - color of frame + +- `label_color_rgb` - color of the frame in RGB + +- `cmdline_icon` - icon hint for WM + +- `icon_data` - loaded icon image, ready for \_NEW\_WM\_ICON property + +- `icon_data_len` - size of icon\_data, in sizeof(\*icon\_data) units + +- `label_index` - label (frame color) hint for WM + +- `screen_window` - window of whole VM screen + +- `clipboard_requested` - if clippoard content was requested by dom0 + +- `clipboard_xevent_time` - timestamp of keypress which triggered last + copy/paste + +- `windows_count` - created window count + +- `nofork` - do not fork into background - used during guid restart + +- `invisible` - do not show any VM window + +- `kill_on_connect` - pid to kill when connection to gui agent is established + +- `allow_utf8_titles` - allow UTF-8 chars in window title + +- `copy_seq_mask` - modifiers mask for secure-copy key sequence + +- `paste_seq_mask` - modifiers mask for secure-paste key sequence + +- `qrexec_clipboard` - 0: use GUI protocol to fetch/put clipboard, 1: use qrexec + +- `use_kdialog` - use kdialog for prompts (default on KDE) or zenity (default on + non-KDE) + +- `trayicon_mode` - trayicon coloring mode + +- `trayicon_border` - position of trayicon border - 0 - no border, 1 - at the + edges, 2 - 1px from the edges + +- `trayicon_tint_reduce_saturation` - trayicon\_tint\_reduce\_saturation + +- `trayicon_tint_whitehack` - replace white pixels with almost-white 0xfefefe + (available only for "tint" mode) + From 46f681a2d05cd4267d87b7a4dbe490dbc48d8551 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Mon, 15 Jul 2019 05:44:13 +0530 Subject: [PATCH 002/141] Fix variables --- user/advanced-configuration/config-files.md | 115 +------------------- 1 file changed, 6 insertions(+), 109 deletions(-) diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index 66ef70c0..dc2957b7 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -95,43 +95,9 @@ global: { #secure_paste_sequence = "Ctrl-Shift-v"; #windows_count_limit = 500; #audio_low_latency = false; - #screen - #root_win - #root_width - #root_height - #context - #frame_gc - #tray_gc - #tint_h - #inter_appviewer_lock_fd - #domid - #target_domid - #agent_version - #cmdline_color - #label_color_rgb - #cmdline_icon - #icon_data - #icon_data_len - #label_index - #screen_window - #clipboard_requested - #windows_count - #log_level - #nofork - #invisible - #kill_on_connect - #allow_utf8_titles - #allow_fullscreen - #copy_seq_mask - #paste_seq_mask - #qrexec_clipboard - #use_kdialog - #audio_low_latency - #prefix_titles - #trayicon_mode - #trayicon_border - #trayicon_tint_reduce_saturation - #trayicon_tint_whitehack + #log_level = info; + #trayicon_mode = "border1"; + #startup_timeout = 91; }; # most of setting can be set per-VM basis @@ -159,79 +125,10 @@ Currently supported settings: - `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste. -- `windows_count_limit` - limit on concurrent windows. - -- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). - Note that this will cause much higher CPU usage in dom0. - -- `screen` - Points on default screen - -- `root_win` - Root attributes - -- `root_width` - Size of root window - -- `context` - context for pixmap operations - -- `frame_gc` - graphics context for painting window frame - -- `tray_gc` - graphic context for painting tray background, only in - TRAY_BACKGROUND mode - -- `tint_h` - precomputed H and S for tray coloring - only in TRAY_TINT mode - -- `inter_appviewer_lock_fd` - FD of lock file used to synchronize shared memory - access - -- `domid` - Xen domain id (GUI) - -- `target_domid` - Xen domain id (VM) - can differ from domid when GUI is - stubdom - -- `cmdline_color` - color of frame - -- `label_color_rgb` - color of the frame in RGB - -- `cmdline_icon` - icon hint for WM - -- `icon_data` - loaded icon image, ready for \_NEW\_WM\_ICON property - -- `icon_data_len` - size of icon\_data, in sizeof(\*icon\_data) units - -- `label_index` - label (frame color) hint for WM - -- `screen_window` - window of whole VM screen - -- `clipboard_requested` - if clippoard content was requested by dom0 - -- `clipboard_xevent_time` - timestamp of keypress which triggered last - copy/paste - -- `windows_count` - created window count - -- `nofork` - do not fork into background - used during guid restart - -- `invisible` - do not show any VM window - -- `kill_on_connect` - pid to kill when connection to gui agent is established - -- `allow_utf8_titles` - allow UTF-8 chars in window title - -- `copy_seq_mask` - modifiers mask for secure-copy key sequence - -- `paste_seq_mask` - modifiers mask for secure-paste key sequence - -- `qrexec_clipboard` - 0: use GUI protocol to fetch/put clipboard, 1: use qrexec - -- `use_kdialog` - use kdialog for prompts (default on KDE) or zenity (default on - non-KDE) - `trayicon_mode` - trayicon coloring mode -- `trayicon_border` - position of trayicon border - 0 - no border, 1 - at the - edges, 2 - 1px from the edges - -- `trayicon_tint_reduce_saturation` - trayicon\_tint\_reduce\_saturation - -- `trayicon_tint_whitehack` - replace white pixels with almost-white 0xfefefe - (available only for "tint" mode) +- `log level` - log level defines the log options log can take. This can be + `ERROR`, `WARN`, `INFO`, `DEBUG`, `LOG_LEVEL_MAX`. +- `startup_timeout` - The timeout for startup. From df0093d4f85d03f63a94ef62bab5591a3f6b44f2 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Tue, 16 Jul 2019 20:00:01 +0530 Subject: [PATCH 003/141] Add proper description for config parameters --- user/advanced-configuration/config-files.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index dc2957b7..28f75a22 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -126,9 +126,18 @@ Currently supported settings: - `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste. -- `trayicon_mode` - trayicon coloring mode +- `trayicon_mode` - defines the trayicon coloring mode. Options are + - `bg` - color full icon background to the VM color + - `border1` - add 1px border at the icon edges + - `border2` - add 1px border 1px from the icon edges + - `tint` - tinttint icon to the VM color, can be used with additional + modifiers (you can enable multiple of them) + - `tint+border1,tint+border2` - same as tint, but also add a border + - `tint+saturation50` - same as tint, but reduce icon saturation by 50% + - `tint+whitehack` - same as tint, but change white pixels (0xffffff) to + almost-white (0xfefefe) -- `log level` - log level defines the log options log can take. This can be - `ERROR`, `WARN`, `INFO`, `DEBUG`, `LOG_LEVEL_MAX`. +- `log level` - log level defines the log options log can take. log level can + have a value of 0(only errors), 1(some basic messages), 2(debug). - `startup_timeout` - The timeout for startup. From 4d2a8a4e9b5c15f27e4ba15127367686e61559e7 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Tue, 16 Jul 2019 20:10:14 +0530 Subject: [PATCH 004/141] Fix spaces issue --- user/advanced-configuration/config-files.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index 28f75a22..7a54714e 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -128,13 +128,13 @@ Currently supported settings: - `trayicon_mode` - defines the trayicon coloring mode. Options are - `bg` - color full icon background to the VM color - - `border1` - add 1px border at the icon edges - - `border2` - add 1px border 1px from the icon edges - - `tint` - tinttint icon to the VM color, can be used with additional + - `border1` - add 1px border at the icon edges + - `border2` - add 1px border 1px from the icon edges + - `tint` - tinttint icon to the VM color, can be used with additional modifiers (you can enable multiple of them) - - `tint+border1,tint+border2` - same as tint, but also add a border - - `tint+saturation50` - same as tint, but reduce icon saturation by 50% - - `tint+whitehack` - same as tint, but change white pixels (0xffffff) to + - `tint+border1,tint+border2` - same as tint, but also add a border + - `tint+saturation50` - same as tint, but reduce icon saturation by 50% + - `tint+whitehack` - same as tint, but change white pixels (0xffffff) to almost-white (0xfefefe) - `log level` - log level defines the log options log can take. log level can From f4e84c8eaf0044fbd24de349b130074375cee81a Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Thu, 18 Jul 2019 02:08:57 +0530 Subject: [PATCH 005/141] Fix Travis CI issue --- user/advanced-configuration/config-files.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index 7a54714e..3e10cc9b 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -127,15 +127,15 @@ Currently supported settings: - `trayicon_mode` - defines the trayicon coloring mode. Options are - - `bg` - color full icon background to the VM color - - `border1` - add 1px border at the icon edges - - `border2` - add 1px border 1px from the icon edges - - `tint` - tinttint icon to the VM color, can be used with additional - modifiers (you can enable multiple of them) - - `tint+border1,tint+border2` - same as tint, but also add a border - - `tint+saturation50` - same as tint, but reduce icon saturation by 50% - - `tint+whitehack` - same as tint, but change white pixels (0xffffff) to - almost-white (0xfefefe) + - `bg` - color full icon background to the VM color + - `border1` - add 1px border at the icon edges + - `border2` - add 1px border 1px from the icon edges + - `tint` - tinttint icon to the VM color, can be used with additional + modifiers (you can enable multiple of them) + - `tint+border1,tint+border2` - same as tint, but also add a border + - `tint+saturation50` - same as tint, but reduce icon saturation by 50% + - `tint+whitehack` - same as tint, but change white pixels (0xffffff) to + almost-white (0xfefefe) - `log level` - log level defines the log options log can take. log level can have a value of 0(only errors), 1(some basic messages), 2(debug). From 9427e1bb21c35b0ef4f322635af649a6898a15df Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Fri, 19 Jul 2019 13:02:51 +0530 Subject: [PATCH 006/141] Added audio_low_latency and dom0 line --- user/advanced-configuration/config-files.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index 3e10cc9b..5b2c6aef 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -125,6 +125,9 @@ Currently supported settings: - `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste. +- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). + Note that this will cause much higher CPU usage in dom0. It's enabled by + default, disabling it may save CPU in dom0. - `trayicon_mode` - defines the trayicon coloring mode. Options are - `bg` - color full icon background to the VM color From 88ac06094b704840d75eef0ff87d0d16ebdbd442 Mon Sep 17 00:00:00 2001 From: Tapasweni Pathak Date: Fri, 19 Jul 2019 13:03:56 +0530 Subject: [PATCH 007/141] Add log_level as 1 remove info --- user/advanced-configuration/config-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/advanced-configuration/config-files.md b/user/advanced-configuration/config-files.md index 5b2c6aef..aea1f614 100644 --- a/user/advanced-configuration/config-files.md +++ b/user/advanced-configuration/config-files.md @@ -95,7 +95,7 @@ global: { #secure_paste_sequence = "Ctrl-Shift-v"; #windows_count_limit = 500; #audio_low_latency = false; - #log_level = info; + #log_level = 1; #trayicon_mode = "border1"; #startup_timeout = 91; }; From 0afe62c1c0d1cfe3ae2568ae9224335cd8b787ab Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 1 Aug 2019 21:01:46 -0500 Subject: [PATCH 008/141] Create Hardware Testing page --- user/hardware/hardware-testing.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 user/hardware/hardware-testing.md diff --git a/user/hardware/hardware-testing.md b/user/hardware/hardware-testing.md new file mode 100644 index 00000000..e745e11e --- /dev/null +++ b/user/hardware/hardware-testing.md @@ -0,0 +1,28 @@ +--- +layout: doc +title: Hardware Testing +permalink: /doc/hardware-testing/ +--- + +# Hardware Testing + +The Qubes developers test Qubes OS on certain hardware models. + +## Tested Models + +These hardware models have been (and continue to be) tested and work well with Qubes OS: + + - Lenovo ThinkPad X1 Carbon Gen 5 + +Note: The Lenovo X and T series are similar enough to assume similar compatibility of the matching model from the other series. + +## Desired Models + +The Qubes devs would like to tese these models, but the hardware is not available to us. +If anyone is willing to lend or donate these models to us, we would be happy to test them: + + - Lenovo Thinkpad T or X series with Intel 8th Gen CPU and integrated graphics + - Dell Latitude with Intel 8th Gen CPU and integrated graphics + +Note: The Lenovo X and T series are similar enough to assume similar compatibility of the matching model from the other series. + From 532e66b52526ddec720814ee2c0670b67e69032c Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 1 Aug 2019 21:11:27 -0500 Subject: [PATCH 009/141] Link to Hardware Testing and Certified Hardware pages --- doc.md | 1 + user/hardware/certified-hardware.md | 4 ++++ user/hardware/hcl.html | 1 + user/hardware/hcl.md | 7 +++++++ user/hardware/system-requirements.md | 2 ++ 5 files changed, 15 insertions(+) diff --git a/doc.md b/doc.md index ef225308..2e5440fb 100644 --- a/doc.md +++ b/doc.md @@ -45,6 +45,7 @@ Core documentation for Qubes users. * [System Requirements](/doc/system-requirements/) * [Certified Hardware](/doc/certified-hardware/) * [Hardware Compatibility List (HCL)](/hcl/) + * [Hardware Testing](/doc/hardware-testing/) ### Downloading, Installing, and Upgrading Qubes diff --git a/user/hardware/certified-hardware.md b/user/hardware/certified-hardware.md index 374ba4ad..8f9d9c4c 100644 --- a/user/hardware/certified-hardware.md +++ b/user/hardware/certified-hardware.md @@ -15,6 +15,9 @@ We aim for these vendors to be as diverse as possible in terms of geography, cos Note, however, that we certify only that a particular hardware *configuration* is *supported* by Qubes. We take no responsibility for our partners' manufacturing or shipping processes, nor can we control whether physical hardware is modified (whether maliciously or otherwise) *en route* to the user. +There are also other hardware models on which we have tested Qubes OS. +See [Hardware Testing] for details. + ## Qubes-certified Laptop: Insurgo PrivacyBeast X230 @@ -84,6 +87,7 @@ While we are willing to troubleshoot simple issues, we will need to charge a con If you are interested in having your hardware certified, please [contact us]. +[Hardware Testing]: /doc/hardware-testing/ [stateless laptop]: https://blog.invisiblethings.org/2015/12/23/state_harmful.html [System Requirements]: /doc/system-requirements/ [Hardware Compatibility List]: /hcl/ diff --git a/user/hardware/hcl.html b/user/hardware/hcl.html index 3217c02d..216676a9 100644 --- a/user/hardware/hcl.html +++ b/user/hardware/hcl.html @@ -29,6 +29,7 @@ redirect_from: /compatible-hardware/
  • How do I Submit a Report?
  • Qubes OS System Requirements
  • Certified Hardware
    • +
  • Hardware Testing
    • diff --git a/user/hardware/hcl.md b/user/hardware/hcl.md index 758f3e5f..5b9b6562 100644 --- a/user/hardware/hcl.md +++ b/user/hardware/hcl.md @@ -29,6 +29,8 @@ If using the list to make a purchasing decision, we recommend that you choose ha - the best achievable Qubes security level (green columns in HVM, IOMMU, TPM) - and general machine compatibility (green columns in Qubes version, dom0 kernel, remarks). +Also see [Certified Hardware] and [Hardware Testing]. + Generating and Submitting New Reports ------------------------------------- @@ -44,3 +46,8 @@ Please consider sending the **HCL Support Files** `.cpio.gz` file as well. To ge **Please note:** The **HCL Support Files** may contain numerous hardware details, including serial numbers. If, for privacy or security reasons, you do not wish to make this information public, please **do not** send the `.cpio.gz` file to the public mailing list. + + +[Certified Hardware]: /doc/certified-hardware/ +[Hardware Testing]: /doc/hardware-testing/ + diff --git a/user/hardware/system-requirements.md b/user/hardware/system-requirements.md index 80aa357c..9149f114 100644 --- a/user/hardware/system-requirements.md +++ b/user/hardware/system-requirements.md @@ -65,6 +65,7 @@ redirect_from: * Please see the [Hardware Compatibility List] for a compilation of hardware reports generated and submitted by users across various Qubes versions. (For more information about the HCL itself, see [here][hcl-doc].) * See the [Certified Hardware] page. + * See the [Hardware Testing] page. ## Important Notes ## @@ -85,6 +86,7 @@ redirect_from: [nvidia]: /doc/install-nvidia-driver/ [hardware certification requirements for Qubes 4.x]: /news/2016/07/21/new-hw-certification-for-q4/ [Certified Hardware]: /doc/certified-hardware/ +[Hardware Testing]: /doc/hardware-testing/ [Hardware Compatibility List]: /hcl/ [hcl-doc]: /doc/hcl/ [hcl-report]: /doc/hcl/#generating-and-submitting-new-reports From 43fbc97fbaaf7721d1724aa1d8958861866c524d Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 2 Aug 2019 21:01:56 -0500 Subject: [PATCH 010/141] Explain relationship to certified hardware and HCL; fix typo --- user/hardware/hardware-testing.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/user/hardware/hardware-testing.md b/user/hardware/hardware-testing.md index e745e11e..02be9818 100644 --- a/user/hardware/hardware-testing.md +++ b/user/hardware/hardware-testing.md @@ -7,6 +7,17 @@ permalink: /doc/hardware-testing/ # Hardware Testing The Qubes developers test Qubes OS on certain hardware models. +The tested hardware described on this page differs from [Qubes Certified Hardware] in a few key ways: + + - Qubes Certified Hardware has to meet more demanding standards than hardware that is merely tested. + - All Qubes Certified Hardware is tested, but not all tested hardware is certified. + - A specific certified configuration is guaranteed to be supported on specific versions of Qubes OS, whereas hardware testing provides no guarantees. + +In general, you can think of tested hardware as "unofficial recommended" hardware: + + - [Qubes Certified Hardware] --- Qubes developer certified, officially recommended + - Hardware Testing (this page) --- Qubes developer tested, unofficially recommended + - [Hardware Compatibility List (HCL)] --- community test results, neither recommended nor disrecommended ## Tested Models @@ -18,7 +29,7 @@ Note: The Lenovo X and T series are similar enough to assume similar compatibili ## Desired Models -The Qubes devs would like to tese these models, but the hardware is not available to us. +The Qubes devs would like to test these models, but the hardware is not available to us. If anyone is willing to lend or donate these models to us, we would be happy to test them: - Lenovo Thinkpad T or X series with Intel 8th Gen CPU and integrated graphics @@ -26,3 +37,7 @@ If anyone is willing to lend or donate these models to us, we would be happy to Note: The Lenovo X and T series are similar enough to assume similar compatibility of the matching model from the other series. + +[Qubes Certified Hardware]: /doc/certified-hardware/ +[Hardware Compatibility List (HCL)]: /hcl/ + From af93a8a87085289181e6460ee72c28f121c8b198 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sat, 3 Aug 2019 17:19:05 -0500 Subject: [PATCH 011/141] Add explicit reminder to update qubes.UpdatesProxy --- user/advanced-configuration/disposablevm-customization.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/user/advanced-configuration/disposablevm-customization.md b/user/advanced-configuration/disposablevm-customization.md index bd06c585..581da8b3 100644 --- a/user/advanced-configuration/disposablevm-customization.md +++ b/user/advanced-configuration/disposablevm-customization.md @@ -106,6 +106,8 @@ qvm-prefs provides_network true ~~~ Next, set the old `sys-` VM's autostart to false, and update any references to the old one. +In particular, make sure to update `/etc/qubes-rpc/policy/qubes.UpdatesProxy` in dom0. + For example, `qvm-prefs sys-firewall netvm `. See below for a complete example of a `sys-net` replacement: From 296498ecc288d700a48565c11a798365fa00294f Mon Sep 17 00:00:00 2001 From: Patrick Schleizer Date: Tue, 6 Aug 2019 12:54:50 +0000 Subject: [PATCH 012/141] full path to log --- user/advanced-configuration/managing-vm-kernel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/advanced-configuration/managing-vm-kernel.md b/user/advanced-configuration/managing-vm-kernel.md index 10770d8a..d6cddacf 100644 --- a/user/advanced-configuration/managing-vm-kernel.md +++ b/user/advanced-configuration/managing-vm-kernel.md @@ -327,7 +327,7 @@ Booting to a kernel inside the template is not supported under `PVH`. In case of problems, you can access the VM console using `sudo xl console VMNAME` in dom0, then access the GRUB menu. You need to call it just after starting the VM (until `GRUB_TIMEOUT` expires); for example, in a separate dom0 terminal window. -In any case you can later access the VM's logs (especially the VM console log `guest-VMNAME.log`). +In any case you can later access the VM's logs (especially the VM console log `/var/log/xen/console/guest-VMNAME.log`). You can always set the kernel back to some dom0-provided value to fix a VM kernel installation. From 35e7f92bc7ceca6d45d3f867af1f2cce31453916 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Fri, 9 Aug 2019 22:01:50 -0500 Subject: [PATCH 013/141] Do not strictly require Atx-style headings on both sides Having the headings on both the left and right sides is more difficult to edit and maintain, and not much is gained from having them on both sides. It's still fine to have them on both sides, but this is a stylistic choice left to the author. --- developer/general/doc-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer/general/doc-guidelines.md b/developer/general/doc-guidelines.md index c3ae2e7a..bea00fec 100644 --- a/developer/general/doc-guidelines.md +++ b/developer/general/doc-guidelines.md @@ -246,7 +246,7 @@ When making contributions, please try to observe the following style conventions * Use hanging indentations where appropriate. * Use underline headings (`=====` and `-----`) if possible. - If this is not possible, use Atx-style headings on both the left and right sides (`### H3 ###`). + If this is not possible, use Atx-style headings: (`### H3 ###`). * When writing code blocks, use [syntax highlighting](https://github.github.com/gfm/#info-string) where [possible](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers) and use `[...]` for anything omitted. * When providing command line examples: * Tell the reader where to open a terminal (dom0 or a specific domU), and show the command along with its output (if any) in a code block, e.g.: From 30c2d9934ad8053151fb12156bb44cf542746472 Mon Sep 17 00:00:00 2001 From: Yukikoo Date: Sun, 11 Aug 2019 16:20:56 +0000 Subject: [PATCH 014/141] Add info about RPC policies for disposableVM Related to https://github.com/QubesOS/qubes-issues/issues/5235 --- user/common-tasks/disposablevm.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index ec8b855b..5a9f86d9 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -153,6 +153,15 @@ $ qvm-open-in-vm @dispvm:online-dvm-template https://www.qubes-os.org This will create a new DisposableVM based on `online-dvm-template`, open the default web browser in that DisposableVM, and navigate to `https://www.qubes-os.org`. +#### Example of RPC policies to allow this behavior + +In dom0, add the following line to `/etc/qubes-rpc/policy/qubes.OpenURL` +~~~ +$anyvm @dispvm:online-dvm-template allow +~~~ + +More information about RPC policies for disposableVM can be found here: `https://www.qubes-os.org/doc/qrexec3/#extra-keywords-available-in-qubes-40-and-later` + ## Customizing DisposableVMs ## From 77d629f6d92be6f8303ce6c68139e662496dc30f Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 11 Aug 2019 18:27:14 -0500 Subject: [PATCH 015/141] Fix link --- user/common-tasks/disposablevm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index 5a9f86d9..4c34b1b2 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -160,7 +160,7 @@ In dom0, add the following line to `/etc/qubes-rpc/policy/qubes.OpenURL` $anyvm @dispvm:online-dvm-template allow ~~~ -More information about RPC policies for disposableVM can be found here: `https://www.qubes-os.org/doc/qrexec3/#extra-keywords-available-in-qubes-40-and-later` +More information about RPC policies for disposableVM can be found [here][qrexec3-4.0]. ## Customizing DisposableVMs ## @@ -171,4 +171,4 @@ Full instructions can be found [here](/doc/disposablevm-customization/). [DisposableVM Template]: /doc/glossary/#disposablevm-template - +[qrexec3-4.0]: /doc/qrexec3/#extra-keywords-available-in-qubes-40-and-later From e4513cb5058b23d752a40435fdcc8881569ecb92 Mon Sep 17 00:00:00 2001 From: Yukikoo Date: Mon, 12 Aug 2019 17:19:53 +0000 Subject: [PATCH 016/141] Added a rule description for OpenURL RPC Policy --- user/common-tasks/disposablevm.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index 4c34b1b2..25b5f028 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -155,10 +155,14 @@ This will create a new DisposableVM based on `online-dvm-template`, open the def #### Example of RPC policies to allow this behavior -In dom0, add the following line to `/etc/qubes-rpc/policy/qubes.OpenURL` +In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL` ~~~ $anyvm @dispvm:online-dvm-template allow ~~~ +This line mean: +- FROM: Any VM +- TO: A DisposableVM based on the ``online-dvm-template`` Template +- WHAT: Allow to send a "Open URL" request More information about RPC policies for disposableVM can be found [here][qrexec3-4.0]. From 05124bb226342a0e5de9f3b026aef7b54bcd6fbe Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Mon, 12 Aug 2019 23:30:27 -0500 Subject: [PATCH 017/141] Clarify description --- user/common-tasks/disposablevm.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index 25b5f028..1c079c24 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -159,10 +159,12 @@ In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/pol ~~~ $anyvm @dispvm:online-dvm-template allow ~~~ -This line mean: +This line means: - FROM: Any VM -- TO: A DisposableVM based on the ``online-dvm-template`` Template -- WHAT: Allow to send a "Open URL" request +- TO: A DisposableVM based on the `online-dvm-template` TemplateVM +- WHAT: Allow sending an "Open URL" request + +In other words, any VM will be allowed to create a new DisposableVM based on `online-dvm-template` and open a URL inside of that DisposableVM. More information about RPC policies for disposableVM can be found [here][qrexec3-4.0]. From c9270a19419bfbbee4388d07f0fd54b991a9ca01 Mon Sep 17 00:00:00 2001 From: Yukikoo Date: Tue, 13 Aug 2019 18:27:36 +0000 Subject: [PATCH 018/141] update policy syntax ``$anyvm`` -> ``@anyvm`` --- user/common-tasks/disposablevm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index 1c079c24..973b3847 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -157,7 +157,7 @@ This will create a new DisposableVM based on `online-dvm-template`, open the def In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL` ~~~ -$anyvm @dispvm:online-dvm-template allow +@anyvm @dispvm:online-dvm-template allow ~~~ This line means: - FROM: Any VM From 1cd77c708d448172e1421c718fccbc5d6079946a Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 13 Aug 2019 23:24:07 -0500 Subject: [PATCH 019/141] Update Experts page --- introduction/experts.md | 35 +++++++++++++++++++++++++---------- 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/introduction/experts.md b/introduction/experts.md index efb79623..4d9d1f3a 100644 --- a/introduction/experts.md +++ b/introduction/experts.md @@ -58,15 +58,15 @@ permalink: /experts/
    - - + +
    - -
    "Donated a % of my consulting company's last year revenue to Qubes OS. I rely on it for all my work, and recommend it to clients too." + +
    "I am so much happier and less stressed out after switching to QubesOS. Can wholeheartedly recommend." -
    Peter Todd, Applied Cryptography Consultant
    +
    Christopher Soghoian, privacy researcher, activist, and principal technologist at the ACLU
    @@ -88,15 +88,15 @@ permalink: /experts/
    - - + +
    - -
    "I am so much happier and less stressed out after switching to QubesOS. Can wholeheartedly recommend." + +
    "Donated a % of my consulting company's last year revenue to Qubes OS. I rely on it for all my work, and recommend it to clients too." -
    Christopher Soghoian, privacy researcher, activist, and principal technologist at the ACLU
    +
    Peter Todd, Applied Cryptography Consultant
    @@ -131,6 +131,21 @@ permalink: /experts/
    +
    +
    + + + +
    +
    + +
    "Trying out Qubes OS (qubes-os.org) recently; linux distro designed around increased security by virtualizing everything and making it really convenient to hop between VMs. Surprisingly good user-friendliness!" + +
    Vitalik Buterin, creator of Ethereum
    +
    +     +
    +
    {% include footer.html %} From c61e0d7118423f18a406a982659cd7b2c6af8036 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 13 Aug 2019 23:43:03 -0500 Subject: [PATCH 020/141] Update links --- introduction/experts.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/introduction/experts.md b/introduction/experts.md index 4d9d1f3a..29ec32da 100644 --- a/introduction/experts.md +++ b/introduction/experts.md @@ -58,12 +58,12 @@ permalink: /experts/
    - +
    - +
    "I am so much happier and less stressed out after switching to QubesOS. Can wholeheartedly recommend."
    Christopher Soghoian, privacy researcher, activist, and principal technologist at the ACLU
    From f72d8bf69c1cb52035f18baab3e43412430b9ad6 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Wed, 14 Aug 2019 00:02:17 -0500 Subject: [PATCH 021/141] Fix orthography --- user/common-tasks/disposablevm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index 973b3847..8ea69512 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -166,7 +166,7 @@ This line means: In other words, any VM will be allowed to create a new DisposableVM based on `online-dvm-template` and open a URL inside of that DisposableVM. -More information about RPC policies for disposableVM can be found [here][qrexec3-4.0]. +More information about RPC policies for DisposableVMs can be found [here][qrexec3-4.0]. ## Customizing DisposableVMs ## From 64b9fae7483a27e9552346669417124c346c8406 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Thu, 15 Aug 2019 21:45:04 -0500 Subject: [PATCH 022/141] Update links to .rst domU man pages hosted on GitHub QubesOS/qubes-issues#5246 --- user/reference/tools.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/user/reference/tools.md b/user/reference/tools.md index aabcb1bd..939e7f8f 100644 --- a/user/reference/tools.md +++ b/user/reference/tools.md @@ -23,9 +23,9 @@ Dom0 DomU ---- - * [qrexec-client-vm](https://raw.githubusercontent.com/QubesOS/qubes-core-agent-linux/master/doc/vm-tools/qrexec-client-vm.rst) - * [qvm-copy-to-vm](https://raw.githubusercontent.com/QubesOS/qubes-core-agent-linux/master/doc/vm-tools/qvm-copy-to-vm.rst) - * [qvm-open-in-dvm](https://raw.githubusercontent.com/QubesOS/qubes-core-agent-linux/master/doc/vm-tools/qvm-open-in-dvm.rst) - * [qvm-open-in-vm](https://raw.githubusercontent.com/QubesOS/qubes-core-agent-linux/master/doc/vm-tools/qvm-open-in-vm.rst) - * [qvm-run-vm](https://raw.githubusercontent.com/QubesOS/qubes-core-agent-linux/master/doc/vm-tools/qvm-run-vm.rst) + * [qrexec-client-vm](https://github.com/QubesOS/qubes-core-qrexec/blob/blob/master/agent/qrexec-client-vm.rst) + * [qvm-copy-to-vm](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/doc/vm-tools/qvm-copy-to-vm.rst) + * [qvm-open-in-dvm](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/doc/vm-tools/qvm-open-in-dvm.rst) + * [qvm-open-in-vm](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/doc/vm-tools/qvm-open-in-vm.rst) + * [qvm-run-vm](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/doc/vm-tools/qvm-run-vm.rst) From b38990e6667f8415d90956688aa7830239d27a9f Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Sun, 18 Aug 2019 12:32:44 -0500 Subject: [PATCH 023/141] Point out that the QMSK is already in every Qubes domU QubesOS/qubes-issues#2544 --- project-security/verifying-signatures.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index e7677568..7699bc49 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -62,6 +62,10 @@ This Qubes Master Signing Key was generated on and is kept only on a dedicated, There are several ways to get the Qubes Master Signing Key. + - If you have access to an existing Qubes installation, it's available in every VM ([except dom0]): + + $ gpg --import /usr/share/qubes/qubes-master-key.asc + - Fetch it with GPG: $ gpg --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc @@ -448,4 +452,5 @@ If you still have a question, please address it to the [qubes-users mailing list [Qubes repositories]: https://github.com/QubesOS [GPG documentation]: https://www.gnupg.org/documentation/ [qubes-users mailing list]: /support/#qubes-users +[except dom0]: https://github.com/QubesOS/qubes-issues/issues/2544 From 9f72309772c3183e9a6b008959a6e4d01bbb7b37 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:33:36 -0500 Subject: [PATCH 024/141] Add semantic newlines for blockdevices.md --- user/common-tasks/block-devices.md | 35 ++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/user/common-tasks/block-devices.md b/user/common-tasks/block-devices.md index 1c58db63..460aa625 100644 --- a/user/common-tasks/block-devices.md +++ b/user/common-tasks/block-devices.md @@ -26,7 +26,9 @@ Qubes OS supports the ability to attach a USB drive (or just its partitions) to Attaching USB drives is integrated into the Devices Widget: ![device manager icon] Simply insert your USB drive and click on the widget. You will see multiple entries for your USB drive; typically, `sys-usb:sda`, `sys-usb:sda1`, and `sys-usb:2-1` for example. -Entries starting with a number (e.g. here `2-1`) are the [whole usb-device][USB]. Entries without a number (e.g. here `sda`) are the whole block-device. Other entries are partitions of that block-device (e.r. here `sda1`). +Entries starting with a number (e.g. here `2-1`) are the [whole usb-device][USB]. +Entries without a number (e.g. here `sda`) are the whole block-device. +Other entries are partitions of that block-device (e.r. here `sda1`). The simplest option is to attach the entire block drive. In our example, this is `sys-usb:sda`, so hover over it. @@ -40,7 +42,8 @@ See below for more detailed steps. ## Block Devices in VMs ## -If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: +If not specified otherwise, block devices will show up as `/dev/xvdi*` in a linux VM, where `*` may be the partition-number. +If a block device isn't automatically mounted after attaching, open a terminal in the VM and execute: cd ~ mkdir mnt @@ -60,9 +63,11 @@ To specify this device node name, you need to use the command line tool and its The command-line tool you may use to mount whole USB drives or their partitions is `qvm-block`, a shortcut for `qvm-device block`. -`qvm-block` won't recognise your device by any given name, but rather the device-node the sourceVM assigns. So make sure you have the drive available in the sourceVM, then list the available block devices (step 1.) to find the corresponding device-node. +`qvm-block` won't recognise your device by any given name, but rather the device-node the sourceVM assigns. +So make sure you have the drive available in the sourceVM, then list the available block devices (step 1.) to find the corresponding device-node. -In case of a USB-drive, make sure it's attached to your computer. If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) +In case of a USB-drive, make sure it's attached to your computer. +If you don't see anything that looks like your drive, run `sudo udevadm trigger --action=change` in your USB-qube (typically `sys-usb`) 1. In a dom0 console (running as a normal user), list all available block devices: @@ -154,13 +159,16 @@ To attach a file as block device to another qube, first turn it into a loopback sudo losetup -f --show /path/to/file - [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. Afterwards it prints the device-node-name it found. + [This command][losetup] will create the device node `/dev/loop0` or, if that is already in use, increase the trailing integer until that name is still available. + Afterwards it prints the device-node-name it found. - 2. If you want to use the GUI, you're done. Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube. + 2. If you want to use the GUI, you're done. + Click the Device Manager ![device manager icon] and select the `loop0`-device to attach it to another qube. If you rather use the command line, continue: - In dom0, run `qvm-block` to display known block devices. The newly created loop device should show up: + In dom0, run `qvm-block` to display known block devices. + The newly created loop device should show up: ~]$ qvm-block BACKEND:DEVID DESCRIPTION USED BY @@ -177,12 +185,15 @@ To attach a file as block device to another qube, first turn it into a loopback ## Additional Attach Options ## -Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option. (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) +Attaching a block device through the command line offers additional customisation options, specifiable via the `--option`/`-o` option. +(Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) ### frontend-dev ### -This option allows you to specify the name of the device node made available in the targetVM. This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order. (The next one tried will be `xvdj`, then `xvdk`, and so on ...) +This option allows you to specify the name of the device node made available in the targetVM. +This defaults to `xvdi` or, if already occupied, the first available device node name in alphabetical order. +(The next one tried will be `xvdj`, then `xvdk`, and so on ...) usage example: @@ -193,7 +204,8 @@ This command will attach the partition `sda1` to `work` as `/dev/xvdz`. ### read-only ### -Attach device in read-only mode. Protects the block device in case you don't trust the targetVM. +Attach device in read-only mode. +Protects the block device in case you don't trust the targetVM. If the device is a read-only device, this option is forced true. @@ -210,7 +222,8 @@ The two commands are equivalent. ### devtype ### -Usually, a block device is attached as disk. In case you need to attach a block device as cdrom, this option allows that. +Usually, a block device is attached as disk. +In case you need to attach a block device as cdrom, this option allows that. usage example: From ca66379727780003fbcb202654693ea856683b79 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:35:06 -0500 Subject: [PATCH 025/141] Add semantic newlines for copy-paste.md --- user/common-tasks/copy-paste.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/user/common-tasks/copy-paste.md b/user/common-tasks/copy-paste.md index b58646f7..6cf31c9d 100644 --- a/user/common-tasks/copy-paste.md +++ b/user/common-tasks/copy-paste.md @@ -11,23 +11,34 @@ redirect_from: Copy and Paste between domains ============================== -Qubes fully supports secure copy and paste operation between domains. In order to copy a clipboard from domain A to domain B, follow those steps: +Qubes fully supports secure copy and paste operation between domains. +In order to copy a clipboard from domain A to domain B, follow those steps: -1. Click on the application window in domain A where you have selected text for copying. Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C). -2. Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key. This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains. -3. Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B. This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system. +1. Click on the application window in domain A where you have selected text for copying. + Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C). +2. Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key. + This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains. +3. Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B. + This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system. 4. Now, in the destination app use the app-specific key combination (usually Ctrl-V) for pasting the clipboard. Note that the global clipboard will be cleared after step \#3, to prevent accidental leakage to another domain, if the user accidentally pressed Ctrl-Shift-V later. -This 4-step process might look complex, but after some little practice it really is very easy and fast. At the same time it provides the user with full control over who has access to the clipboard. +This 4-step process might look complex, but after some little practice it really is very easy and fast. +At the same time it provides the user with full control over who has access to the clipboard. -Note that only simple plain text copy/paste is supported between AppVMs. This is discussed in a bit more detail in [this message](https://groups.google.com/group/qubes-devel/msg/57fe6695eb8ec8cd). +Note that only simple plain text copy/paste is supported between AppVMs. +This is discussed in a bit more detail in [this message](https://groups.google.com/group/qubes-devel/msg/57fe6695eb8ec8cd). On Copy/Paste Security ---------------------- -The scheme is *secure* because it doesn't allow other VMs to steal the content of the clipboard. However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g. the seemingly innocent link that we copy from untrusted domain, might turn out to be, in fact, a large buffer of junk that, when pasted into the destination VM's word processor could exploit a hypothetical bug in the undo buffer). This is a general problem and applies to any data transfer between *less trusted to more trusted* domains. It even applies to copying files between physically separate machines (air-gapped) systems. So, you should always copy clipboard and data only from *more trusted* to *less trusted* domains. +The scheme is *secure* because it doesn't allow other VMs to steal the content of the clipboard. +However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g. +the seemingly innocent link that we copy from untrusted domain, might turn out to be, in fact, a large buffer of junk that, when pasted into the destination VM's word processor could exploit a hypothetical bug in the undo buffer). +This is a general problem and applies to any data transfer between *less trusted to more trusted* domains. +It even applies to copying files between physically separate machines (air-gapped) systems. +So, you should always copy clipboard and data only from *more trusted* to *less trusted* domains. See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes. @@ -47,7 +58,8 @@ The Qubes clipboard [RPC policy] is configurable in: /etc/qubes-rpc/policy/qubes.ClipboardPaste ~~~ -You may wish to configure this policy in order to prevent user error. For example, if you are certain that you never wish to paste *into* your "vault" AppVM (and it is highly recommended that you do not), then you should edit the policy as follows: +You may wish to configure this policy in order to prevent user error. +For example, if you are certain that you never wish to paste *into* your "vault" AppVM (and it is highly recommended that you do not), then you should edit the policy as follows: ~~~ $anyvm vault deny From 2b1145fece4c4813cd39086a594332400f591669 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:36:12 -0500 Subject: [PATCH 026/141] Add semantic newlines for copying-files.md --- user/common-tasks/copying-files.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/user/common-tasks/copying-files.md b/user/common-tasks/copying-files.md index 9babf209..ea8ddb49 100644 --- a/user/common-tasks/copying-files.md +++ b/user/common-tasks/copying-files.md @@ -23,7 +23,8 @@ GUI 2. A dialog box will appear asking for the name of the destination qube (qube B). -3. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent). After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B: +3. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent). + After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B: `/home/user/QubesIncoming/` @@ -45,9 +46,15 @@ qvm-move [--without-progress] file [file]+ On inter-qube file copy security ---------------------------------- -The scheme is *secure* because it doesn't allow other qubes to steal the files that are being copied, and also doesn't allow the source qube to overwrite arbitrary files on the destination qube. Also, Qubes's file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data. For example, the receiving qube is *not* forced to parse untrusted partitions or file systems. In this respect our file copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines! +The scheme is *secure* because it doesn't allow other qubes to steal the files that are being copied, and also doesn't allow the source qube to overwrite arbitrary files on the destination qube. +Also, Qubes's file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data. +For example, the receiving qube is *not* forced to parse untrusted partitions or file systems. +In this respect our file copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines! -However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination qube (e.g. a seemingly innocent JPEG that we copy from an untrusted qube might contain a specially crafted exploit for a bug in JPEG parsing application in the destination qube). This is a general problem and applies to any data transfer between *less trusted to more trusted* qubes. It even applies to the scenario of copying files between air-gapped machines. So, you should always copy data only from *more trusted* to *less trusted* qubes. +However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination qube (e.g. a seemingly innocent JPEG that we copy from an untrusted qube might contain a specially crafted exploit for a bug in JPEG parsing application in the destination qube). +This is a general problem and applies to any data transfer between *less trusted to more trusted* qubes. +It even applies to the scenario of copying files between air-gapped machines. +So, you should always copy data only from *more trusted* to *less trusted* qubes. See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes. From 6a981959d42231a12a772ba4994c06734568e8b1 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:37:33 -0500 Subject: [PATCH 027/141] Add semantic newlines for device-handling.md --- user/common-tasks/device-handling.md | 61 ++++++++++++++++++++-------- 1 file changed, 44 insertions(+), 17 deletions(-) diff --git a/user/common-tasks/device-handling.md b/user/common-tasks/device-handling.md index a85922cf..b882c1e1 100644 --- a/user/common-tasks/device-handling.md +++ b/user/common-tasks/device-handling.md @@ -11,14 +11,18 @@ redirect_from: # Device Handling # -This is an overview of device handling in Qubes OS. For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages. +This is an overview of device handling in Qubes OS. +For specific devices ([block], [USB] and [PCI] devices), please visit their respective pages. -**Important security warning:** Device handling comes with many security implications. Please make sure you carefully read and understand the **[security considerations]**. +**Important security warning:** Device handling comes with many security implications. +Please make sure you carefully read and understand the **[security considerations]**. ## Introduction ## -The interface to deal with devices of all sorts was unified in Qubes 4.0 with the `qvm-device` command and the Qubes Devices Widget. In Qubes 3.X, the Qubes VM Manager dealt with attachment as well. This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default. +The interface to deal with devices of all sorts was unified in Qubes 4.0 with the `qvm-device` command and the Qubes Devices Widget. +In Qubes 3.X, the Qubes VM Manager dealt with attachment as well. +This functionality was moved to the Qubes Device Widget, the tool tray icon with a yellow square located in the top right of your screen by default. There are currently four categories of devices Qubes understands: - Microphones @@ -26,31 +30,41 @@ There are currently four categories of devices Qubes understands: - USB devices - PCI devices -Microphones, block devices and USB devices can be attached with the GUI-tool. PCI devices can be attached using the Qube Settings, but require a VM reboot. +Microphones, block devices and USB devices can be attached with the GUI-tool. +PCI devices can be attached using the Qube Settings, but require a VM reboot. ## General Qubes Device Widget Behavior And Handling ## -When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive][device manager icon] several device-classes separated by lines are displayed as tooltip. Block devices are displayed on top, microphones one below and USB-devices at the bottom. +When clicking on the tray icon (which looks similar to this): ![SD card and thumbdrive][device manager icon] several device-classes separated by lines are displayed as tooltip. +Block devices are displayed on top, microphones one below and USB-devices at the bottom. On most laptops, integrated hardware such as cameras and fingerprint-readers are implemented as USB-devices and can be found here. ### Attaching Using The Widget ### -Click the tray icon. Hover on a device you want to attach to a VM. A list of running VMs (except dom0) appears. Click on one and your device will be attached! +Click the tray icon. +Hover on a device you want to attach to a VM. +A list of running VMs (except dom0) appears. +Click on one and your device will be attached! ### Detaching Using The Widget ### -To detach a device, click the Qubes Devices Widget icon again. Attached devices are displayed in bold. Hover the one you want to detach. A list of VMs appears, one showing the eject symbol: ![eject icon] +To detach a device, click the Qubes Devices Widget icon again. +Attached devices are displayed in bold. +Hover the one you want to detach. +A list of VMs appears, one showing the eject symbol: ![eject icon] ### Attaching a Device to Several VMs ### -Only `mic` should be attached to more than one running VM. You may *assign* a device to more than one VM (using the [`--persistent`][#attaching-devices] option), however, only one of them can be started at the same time. +Only `mic` should be attached to more than one running VM. +You may *assign* a device to more than one VM (using the [`--persistent`][#attaching-devices] option), however, only one of them can be started at the same time. -But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs. Don't do that! +But be careful: There is a [bug in `qvm-device block` or `qvm-block`][i4692] which will allow you to *attach* a block device to two running VMs. +Don't do that! ## General `qvm-device` Command Line Tool Behavior ## @@ -60,7 +74,8 @@ All devices, including PCI-devices, may be attached from the commandline using t ### Device Classes ### -`qvm-device` expects DEVICE_CLASS as first argument. DEVICE_CLASS can be one of +`qvm-device` expects DEVICE_CLASS as first argument. +DEVICE_CLASS can be one of - `pci` - `usb` @@ -85,7 +100,9 @@ These three options are always available: - `--verbose`, `-v` - increase verbosity - `--quiet`, `-q` - decrease verbosity -A full command consists of one DEVICE_CLASS and one action. If no action is given, list is implied. DEVICE_CLASS however is required. +A full command consists of one DEVICE_CLASS and one action. +If no action is given, list is implied. +DEVICE_CLASS however is required. **SYNOPSIS**: `qvm-device DEVICE_CLASS {action} [action-specific arguments] [options]` @@ -98,12 +115,16 @@ Actions are applicable to every DEVICE_CLASS and expose some additional options. ### Listing Devices ### -The `list` action lists known devices in the system. `list` accepts VM-names to narrow down listed devices. Devices available in, as well as attached to the named VMs will be listed. +The `list` action lists known devices in the system. +`list` accepts VM-names to narrow down listed devices. +Devices available in, as well as attached to the named VMs will be listed. `list` accepts two options: - - `--all` - equivalent to specifying every VM name after `list`. No VM-name implies `--all`. - - `--exclude` - exclude VMs from `--all`. Requires `--all`. + - `--all` - equivalent to specifying every VM name after `list`. +No VM-name implies `--all`. + - `--exclude` - exclude VMs from `--all`. +Requires `--all`. **SYNOPSIS** `qvm-device DEVICE_CLASS {list|ls|l} [--all [--exclude VM [VM [...]]] | VM [VM [...]]]` @@ -111,11 +132,15 @@ The `list` action lists known devices in the system. `list` accepts VM-names to ### Attaching Devices ### -The `attach` action assigns an exposed device to a VM. This makes the device available in the VM it's attached to. Required argument are targetVM and sourceVM:deviceID. (sourceVM:deviceID can be determined from `list` output) +The `attach` action assigns an exposed device to a VM. +This makes the device available in the VM it's attached to. +Required argument are targetVM and sourceVM:deviceID. +(sourceVM:deviceID can be determined from `list` output) `attach` accepts two options: - - `--persistent` - attach device on targetVM-boot. If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails. + - `--persistent` - attach device on targetVM-boot. +If the device is unavailable (physically missing or sourceVM not started), booting the targetVM fails. - `--option`, `-o` - set additional options specific to DEVICE_CLASS. **SYNOPSIS** @@ -124,7 +149,9 @@ The `attach` action assigns an exposed device to a VM. This makes the device ava ### Detaching Devices ### -The `detach` action removes an assigned device from a targetVM. It won't be available afterwards anymore. Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device! +The `detach` action removes an assigned device from a targetVM. +It won't be available afterwards anymore. +Though it tries to do so gracefully, beware that data-connections might be broken unexpectedly, so close any transaction before detaching a device! If no specific `sourceVM:deviceID` combination is given, *all devices of that DEVICE_CLASS will be detached.* From cac27027a3b0997d27602e0d3ab903a16150133e Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:38:23 -0500 Subject: [PATCH 028/141] Add semantic newlines for disposablevm.md --- user/common-tasks/disposablevm.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/user/common-tasks/disposablevm.md b/user/common-tasks/disposablevm.md index 8ea69512..981144f5 100644 --- a/user/common-tasks/disposablevm.md +++ b/user/common-tasks/disposablevm.md @@ -68,7 +68,8 @@ This is a change in behaviour from R3.2, where DisposableVMs would inherit the s Therefore, launching a DisposableVM from an AppVM will result in it using the network/firewall settings of the DisposableVM Template on which it is based. For example, if an AppVM uses sys-net as its NetVM, but the default system DisposableVM uses sys-whonix, any DisposableVM launched from this AppVM will have sys-whonix as its NetVM. -**Warning:** The opposite is also true. This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DisposableVM uses sys-net, launching a DisposableVM from inside anon-whonix will result in the DisposableVM using sys-net. +**Warning:** The opposite is also true. +This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DisposableVM uses sys-net, launching a DisposableVM from inside anon-whonix will result in the DisposableVM using sys-net. A DisposableVM launched from the Start Menu inherits the NetVM and firewall settings of the DisposableVM Template on which it is based. Note that changing the "NetVM" setting for the system default DisposableVM Template *does* affect the NetVM of DisposableVMs launched from the Start Menu. @@ -118,7 +119,8 @@ Note that the `qvm-open-in-dvm` process will not exit until you close the applic ## Starting an arbitrary program in a DisposableVM from an AppVM ## -Sometimes it can be useful to start an arbitrary program in a DisposableVM. This can be done from an AppVM by running +Sometimes it can be useful to start an arbitrary program in a DisposableVM. +This can be done from an AppVM by running ~~~ [user@vault ~]$ qvm-run '$dispvm' xterm From 6f5c584b5d224f3051be20717038a3720f9a4486 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:39:23 -0500 Subject: [PATCH 029/141] Add semantic newlines for full-screen-mode.md --- user/common-tasks/full-screen-mode.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/user/common-tasks/full-screen-mode.md b/user/common-tasks/full-screen-mode.md index 3ebd6a94..1ec7f8fa 100644 --- a/user/common-tasks/full-screen-mode.md +++ b/user/common-tasks/full-screen-mode.md @@ -14,7 +14,9 @@ Enabling Full Screen Mode for select VMs What is full screen mode? ------------------------- -Normally Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, ensuring that there are always clearly marked decorations drawn by the trusted Window Manager around each of the VMs window. This allows the user to easily realize to which domain a specific window belongs. See the [screenshots](/doc/QubesScreenshots/) for better understanding. +Normally Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, ensuring that there are always clearly marked decorations drawn by the trusted Window Manager around each of the VMs window. +This allows the user to easily realize to which domain a specific window belongs. +See the [screenshots](/doc/QubesScreenshots/) for better understanding. Why is full screen mode potentially dangerous? ---------------------------------------------- @@ -24,8 +26,12 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on Secure use of full screen mode ------------------------------ -However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts. -Another option is to use Alt+Tab for switching windows. This shortcut is also handled by dom0. +However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM. +An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those. +Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway. +By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts. +Another option is to use Alt+Tab for switching windows. +This shortcut is also handled by dom0. Enabling full screen mode for select VMs ---------------------------------------- @@ -60,11 +66,8 @@ global: { Be sure to restart the VM(s) after modifying this file, for the changes to take effect. -**Note:** Regardless of the settings above, you can always put a window into -fullscreen mode in Xfce4 using the trusted window manager by right-clicking on -a window's title bar and selecting "Fullscreen". This functionality should still -be considered safe, since a VM window still can't voluntarily enter fullscreen -mode. The user must select this option from the trusted window manager in dom0. -To exit fullscreen mode from here, press `alt` + `space` to bring up the title -bar menu again, then select "Leave Fullscreen". +**Note:** Regardless of the settings above, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen". +This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode. +The user must select this option from the trusted window manager in dom0. +To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen". For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4. From f816cea0da2b9acb8c99a496028e09bd783405a8 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:40:10 -0500 Subject: [PATCH 030/141] Add semantic newlines for optical-discs.md --- user/common-tasks/optical-discs.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/user/common-tasks/optical-discs.md b/user/common-tasks/optical-discs.md index 5b11024c..d8fb6f91 100644 --- a/user/common-tasks/optical-discs.md +++ b/user/common-tasks/optical-discs.md @@ -18,5 +18,8 @@ Currently, the only options for reading and recording optical discs (e.g., CDs, 3. Use a SATA optical drive attached to dom0. (**Caution:** This option is [potentially dangerous](/doc/security-guidelines/#dom0-precautions).) -To access an optical disc via USB follow the [typical procedure for attaching a USB device](/doc/usb-devices/#with-the-command-line-tool), then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to. Typically this would be `sr0`. For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`. You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`. +To access an optical disc via USB follow the [typical procedure for attaching a USB device](/doc/usb-devices/#with-the-command-line-tool), then check with the **Qubes Devices** widget to see what device in the target qube the USB optical drive was attached to. +Typically this would be `sr0`. +For example, if `sys-usb` has device `3-2` attached to the `work` qube's `sr0`, you would mount it with `mount /dev/sr0 /mnt/removable`. +You could also write to a disc with `wodim -v dev=/dev/sr0 -eject /home/user/Qubes.iso`. From c7e8a45bc8a894f4b8c5e4fbddb1af59d05121c0 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:44:04 -0500 Subject: [PATCH 031/141] Add semantic newlines for pci-devices.md --- user/common-tasks/pci-devices.md | 37 +++++++++++++++++++++----------- 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/user/common-tasks/pci-devices.md b/user/common-tasks/pci-devices.md index 91e42924..cc1f74d4 100644 --- a/user/common-tasks/pci-devices.md +++ b/user/common-tasks/pci-devices.md @@ -13,19 +13,24 @@ redirect_from: *This page is part of [device handling in qubes].* -**Warning:** Only dom0 exposes PCI devices. Some of them are strictly required in dom0 (e.g., the host bridge). +**Warning:** Only dom0 exposes PCI devices. +Some of them are strictly required in dom0 (e.g., the host bridge). You may end up with an unusable system by attaching the wrong PCI device to a VM. -PCI passthrough should be safe by default, but non-default options may be required. Please make sure you carefully read and understand the **[security considerations]** before deviating from default behavior. +PCI passthrough should be safe by default, but non-default options may be required. +Please make sure you carefully read and understand the **[security considerations]** before deviating from default behavior. ## Introduction ## -Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup. Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported. +Unlike other devices ([USB], [block], mic), PCI devices need to be attached on VM-bootup. +Similar to how you can't attach a new sound-card after your computer booted (and expect it to work properly), attaching PCI devices to already booted VMs isn't supported. The Qubes installer attaches all network class controllers to `sys-net` and all USB controllers to `sys-usb` by default, if you chose to create the network and USB qube during install. While this covers most use cases, there are some occasions when you may want to manually attach one NIC to `sys-net` and another to a custom NetVM, or have some other type of PCI controller you want to manually attach. -Some devices expose multiple functions with distinct BDF-numbers. Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM. This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations]. +Some devices expose multiple functions with distinct BDF-numbers. +Limits imposed by the PC and VT-d architectures may require all functions belonging to the same device to be attached to the same VM. +This requirement can be dropped with the `no-strict-reset` option during attachment, bearing in mind the aforementioned [security considerations]. In the steps below, you can tell if this is needed if you see the BDF for the same device listed multiple times with only the number after the "." changing. While PCI device can only be used by one powered on VM at a time, it *is* possible to *assign* the same device to more than one VM at a time. @@ -35,7 +40,8 @@ This can be useful if, for example, you have only one USB controller, but you ha ## Attaching Devices Using the GUI ## -The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-devices to a qube. +The qube settings for a VM offers the "Devices"-tab. +There you can attach PCI-devices to a qube. 1. To reach the settings of any qube either @@ -45,13 +51,16 @@ The qube settings for a VM offers the "Devices"-tab. There you can attach PCI-de 2. Select the "Devices" tab on the top bar. 3. Select a device you want to attach to the qube and click the single arrow right! (`>`) - 4. You're done. If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached. - 5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab). If that doesn't help, read on to learn how to disable the strict reset requirement! + 4. You're done. + If everything worked out, once the qube boots (or reboots if it's running) it will start with the pci device attached. + 5. In case it doesn't work out, first try disabling memory-balancing in the settings ("Advanced" tab). + If that doesn't help, read on to learn how to disable the strict reset requirement! ## `qvm-pci` Usage ## -The `qvm-pci` tool allows PCI attachment and detachment. It's a shortcut for [`qvm-device pci`][qvm-device]. +The `qvm-pci` tool allows PCI attachment and detachment. +It's a shortcut for [`qvm-device pci`][qvm-device]. To figure out what device to attach, first list the available PCI devices by running (as user) in dom0: @@ -99,14 +108,17 @@ Both can be achieved during attachment with `qvm-pci` as described below. ## Additional Attach Options ## -Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option. (Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) +Attaching a PCI device through the commandline offers additional options, specifiable via the `--option`/`-o` option. +(Yes, confusing wording, there's an [issue for that](https://github.com/QubesOS/qubes-issues/issues/4530).) -`qvm-pci` exposes two additional options. Both are intended to fix device or driver specific issues, but both come with [heavy security implications][security considerations]! **Make sure you understand them before continuing!** +`qvm-pci` exposes two additional options. +Both are intended to fix device or driver specific issues, but both come with [heavy security implications][security considerations]! **Make sure you understand them before continuing!** ### no-strict-reset ### -Do not require PCI device to be reset before attaching it to another VM. This may leak usage data even without malicious intent! +Do not require PCI device to be reset before attaching it to another VM. +This may leak usage data even without malicious intent! usage example: @@ -115,7 +127,8 @@ usage example: ### permissive ### -Allow write access to full PCI config space instead of whitelisted registers. This increases attack surface and possibility of [side channel attacks]. +Allow write access to full PCI config space instead of whitelisted registers. +This increases attack surface and possibility of [side channel attacks]. usage example: From 2dae132dfcf98eeab9178d79345f978f1b9d5347 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:45:27 -0500 Subject: [PATCH 032/141] Add semantic newlines for software-update-dom0.md --- user/common-tasks/software-update-dom0.md | 41 ++++++++++++++++------- 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/user/common-tasks/software-update-dom0.md b/user/common-tasks/software-update-dom0.md index 02bb71c5..5cb56110 100644 --- a/user/common-tasks/software-update-dom0.md +++ b/user/common-tasks/software-update-dom0.md @@ -14,7 +14,10 @@ Installing and updating software in dom0 Why would one want to install or update software in dom0? --------------------------------------------------------- -Normally, there should be few reasons for installing or updating software in dom0. This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. (We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching. +Normally, there should be few reasons for installing or updating software in dom0. +This is because there is no networking in dom0, which means that even if some bugs are discovered e.g. in the dom0 Desktop Manager, this really is not a problem for Qubes, because none of the third-party software running in dom0 is accessible from VMs or the network in any way. +Some exceptions to this include: Qubes GUI daemon, Xen store daemon, and disk back-ends. +(We plan move the disk backends to an untrusted domain in a future Qubes release.) Of course, we believe this software is reasonably secure, and we hope it will not need patching. However, we anticipate some other situations in which installing or updating dom0 software might be necessary or desirable: @@ -25,18 +28,25 @@ However, we anticipate some other situations in which installing or updating dom How is software installed and updated securely in dom0? ------------------------------------------------------- -The install/update process is split into two phases: "resolve and download" and "verify and install." The "resolve and download" phase is handled by the "UpdateVM." (The role of UpdateVM can be assigned to any VM in the Qubes VM Manager, and there are no significant security implications in this choice. By default, this role is assigned to the firewallvm.) After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed. This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB. +The install/update process is split into two phases: "resolve and download" and "verify and install." The "resolve and download" phase is handled by the "UpdateVM." (The role of UpdateVM can be assigned to any VM in the Qubes VM Manager, and there are no significant security implications in this choice. +By default, this role is assigned to the firewallvm.) After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed. +This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB. -Although this update scheme is far more secure than directly downloading updates in dom0, it is not invulnerable. For example, there is nothing that the Qubes project can feasibly do to prevent a malicious RPM from exploiting a hypothetical bug in GPG's `--verify` operation. At best, we could switch to a different distro or package manager, but any of them could be vulnerable to the same (or a similar) attack. While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular TemplateVM distro's updates, and this would be far too costly for us to maintain. +Although this update scheme is far more secure than directly downloading updates in dom0, it is not invulnerable. +For example, there is nothing that the Qubes project can feasibly do to prevent a malicious RPM from exploiting a hypothetical bug in GPG's `--verify` operation. +At best, we could switch to a different distro or package manager, but any of them could be vulnerable to the same (or a similar) attack. +While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular TemplateVM distro's updates, and this would be far too costly for us to maintain. How to install and update software in dom0 ------------------------------------------ ### How to update dom0 -In the Qube Manager, simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click. +In the Qube Manager, simply select dom0 in the VM list, then click the **Update VM system** button (the blue, downward-pointing arrow). +In addition, updating dom0 has been made more convenient: You will be prompted on the desktop whenever new dom0 updates are available and given the choice to run the update with a single click. -Alternatively, command-line tools are available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager). In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands: +Alternatively, command-line tools are available for accomplishing various update-related tasks (some of which are not available via Qubes VM Manager). +In order to update dom0 from the command line, start a console in dom0 and then run one of the following commands: To check and install updates for dom0 software: @@ -48,7 +58,8 @@ To install additional packages in dom0 (usually not recommended): $ sudo qubes-dom0-update anti-evil-maid -You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). However, this is only for advanced users who really understand what they are doing. +You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0). +However, this is only for advanced users who really understand what they are doing. You can also pass commands to `dnf` using `--action=...`. ### How to downgrade a specific package @@ -87,7 +98,8 @@ You can re-install in a similar fashion to downgrading. sudo dnf reinstall package ~~~ - Note that `dnf` will only re-install if the installed and downloaded versions match. You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. + Note that `dnf` will only re-install if the installed and downloaded versions match. + You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`. ### How to uninstall a package @@ -106,8 +118,8 @@ There are three Qubes dom0 testing repositories: * `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=` -option. Example commands: +To temporarily enable any of these repos, use the `--enablerepo=` option. +Example commands: ~~~ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing @@ -120,8 +132,10 @@ To enable or disable any of these repos permanently, change the corresponding `e ### Kernel Upgrade ### -Install newer kernel for dom0 and VMs. The package `kernel` is for dom0 and the package `kernel-qubes-vm` -is needed for the VMs. (Note that the following example enables the unstable repo.) +Install newer kernel for dom0 and VMs. +The package `kernel` is for dom0 and the package `kernel-qubes-vm` +is needed for the VMs. +(Note that the following example enables the unstable repo.) ~~~ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm @@ -151,7 +165,10 @@ to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoy Requires installed [Whonix](/doc/privacy/whonix/). -Go to Qubes VM Manager -> System -> Global Settings. See the UpdateVM setting. Choose your desired Whonix-Gateway ProxyVM from the list. For example: sys-whonix. +Go to Qubes VM Manager -> System -> Global Settings. +See the UpdateVM setting. +Choose your desired Whonix-Gateway ProxyVM from the list. +For example: sys-whonix. Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix From 0555eb932645313c3798aa6a42dc591b529379e1 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 18 Aug 2019 12:46:25 -0500 Subject: [PATCH 033/141] Add semantic newlines for software-update-vm.md --- user/common-tasks/software-update-vm.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/user/common-tasks/software-update-vm.md b/user/common-tasks/software-update-vm.md index e3d4c72e..4f149671 100644 --- a/user/common-tasks/software-update-vm.md +++ b/user/common-tasks/software-update-vm.md @@ -157,7 +157,8 @@ qvm-create --class StandaloneVM --label