diff --git a/developer/code/code-signing.md b/developer/code/code-signing.md index c94b9e1bb..8074840d8 100644 --- a/developer/code/code-signing.md +++ b/developer/code/code-signing.md @@ -144,9 +144,11 @@ Although GitHub adds a little green `Verified` button next to the commit, the [s 1. Is the commit signed? If the commit is not signed, you can see the message + > policy/qubesos/code-signing — No signature found 2. If the commit is signed, the key is downloaded from a GPG key server. If you can see the following error message, please check if you have uploaded the key to a key server. + > policy/qubesos/code-signing — Unable to verify (no valid key found) ### No Signature Found diff --git a/developer/code/source-code.md b/developer/code/source-code.md index 85e5cf13a..83173e6c2 100644 --- a/developer/code/source-code.md +++ b/developer/code/source-code.md @@ -60,6 +60,7 @@ method you choose, you must [sign your code](/doc/code-signing/) before it can b * **Preferred**: Use GitHub's [fork & pull requests](https://guides.github.com/activities/forking/). + Opening a pull request on GitHub greatly eases the code review and tracking process. In addition, especially for bigger changes, it's a good idea to send a message to the [qubes-devel mailing list](/support/#qubes-devel) in order to notify people who diff --git a/developer/debugging/automated-tests.md b/developer/debugging/automated-tests.md index 38e4aca27..8082ac358 100644 --- a/developer/debugging/automated-tests.md +++ b/developer/debugging/automated-tests.md @@ -267,11 +267,13 @@ It feeds off of the openQA test data to make graph plots. Here is an example: ![openqa-investigator-splitgpg-example.png](/attachment/doc/openqa-investigator-splitgpg-example.png) Some outputs: + - plot by tests - plot by errors - markdown Some filters: + - filter by error - filter by test name diff --git a/developer/general/gsoc.md b/developer/general/gsoc.md index e49d66d97..05ad37286 100644 --- a/developer/general/gsoc.md +++ b/developer/general/gsoc.md @@ -174,45 +174,6 @@ If applicable, links to more information or discussions **Mentor**: [Frédéric Pierret](/team/) - ### Qubes Live USB @@ -252,26 +213,6 @@ details: [#1552](https://github.com/QubesOS/qubes-issues/issues/1552), **Mentor**: [Frédéric Pierret](/team/) - - ### LogVM(s) **Project**: LogVM(s) @@ -461,44 +402,6 @@ Some related discussion: **Mentor**: [Marek Marczykowski-Górecki](/team/) - - ### Android development in Qubes **Project**: Research running Android in Qubes VM (probably HVM) and connecting it to Android Studio @@ -538,12 +441,14 @@ Since the Admin API is continuously growing and changing, continuous security as A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of these assessments. **Expected results**: + - fully automated & extensible Fuzzer for parts of the Admin API - user & developer documentation **Difficulty**: medium **Prerequisites**: + - basic Python understanding - some knowledge about fuzzing & existing fuzzing frameworks (e.g. [oss-fuzz](https://github.com/google/oss-fuzz/tree/master/projects/qubes-os)) - a hacker's curiosity @@ -560,6 +465,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of **Brief explanation**: Since recently, Xen supports "unified EFI boot" which allows to sign not only Xen binary itself, but also dom0 kernel and their parameters. While the base technology is there, enabling it is a painful and complex process. The goal of this project is to integrate configuration of this feature into Qubes, automating as much as possible. See discussion in [issue #4371](https://github.com/QubesOS/qubes-issues/issues/4371) **Expected results**: + - a tool to prepare relevant boot files for unified Xen EFI boot - this includes collecting Xen, dom0 kernel, initramfs, config file, and possibly few more (ucode update?); the tool should then sign the file with user provided key (preferably propose to generate it too) - integrate it with updates mechanism, so new Xen or dom0 kernel will be picked up automatically - include a fallback configuration that can be used for troubleshooting (main unified Xen EFI intentionally does not allow to manipulate parameters at boot time) @@ -567,6 +473,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of **Difficulty**: hard **Knowledge prerequisite**: + - basic understanding of Secure Boot - Bash and Python scripting @@ -586,6 +493,7 @@ A [Fuzzer](https://en.wikipedia.org/wiki/Fuzzing) would help to automate part of **Difficulty**: medium **Knowledge prerequisite**: + - Python scripting - Basic knowledge of Linux system services management (systemd, syslog etc) diff --git a/developer/releases/4_2/release-notes.md b/developer/releases/4_2/release-notes.md index 2590f55b3..b5a34b80c 100644 --- a/developer/releases/4_2/release-notes.md +++ b/developer/releases/4_2/release-notes.md @@ -56,17 +56,17 @@ We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after - Qubes 4.2.2 includes a fix for [#8332: File-copy qrexec service is overly restrictive](https://github.com/QubesOS/qubes-issues/issues/8332). As explained in the issue comments, we introduced a change in Qubes 4.2.0 that caused inter-qube file-copy/move actions to reject filenames containing, e.g., non-Latin characters and certain symbols. The rationale for this change was to mitigate the security risks associated with unusual unicode characters and invalid encoding in filenames, which some software might handle in an unsafe manner and which might cause confusion for users. Such a change represents a trade-off between security and usability. - After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place. + - After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place. - Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service. + - Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service. - Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules: + - Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules: - ``` - qubes.Filecopy +allow-all-names @anyvm @anyvm deny - ``` + ``` + qubes.Filecopy +allow-all-names @anyvm @anyvm deny + ``` - For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc). + - For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc). ## Download diff --git a/developer/services/admin-api.md b/developer/services/admin-api.md index 0087bcaff..495d95769 100644 --- a/developer/services/admin-api.md +++ b/developer/services/admin-api.md @@ -13,8 +13,7 @@ ref: 36 title: Admin API --- -_You may also be interested in the article -[Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)._ +_You may also be interested in the article [Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)._ ## Goals diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 8f0a10ac7..4c7fdf409 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -122,25 +122,25 @@ Details of all possible use cases and the messages involved are described below. qrexec-client -d domX [-l local_program] user:cmd - (If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.) + - (If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.) - `qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port also set to 0 (allocate a port). + - `qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port also set to 0 (allocate a port). - **dom0**: `qrexec-daemon` allocates a free port (in this case 513), and sends a `MSG_EXEC_CMDLINE` back to the client with connection parameters (**domX** and 513) and with command field empty. - `qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection. + - `qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection. - Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513. + - Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513. - **domX**: `qrexec-agent` receives `MSG_EXEC_CMDLINE`, and starts the command (`user:cmd`, or `cmd` as user `user`). If possible, this is actually delegated to a separate server (`qrexec-fork-server`) also running on domX. - After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513. + - After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513. - Data is forwarded between the `qrexec-client` in **dom0** and the command executed in **domX** using `MSG_DATA_STDIN`, `MSG_DATA_STDOUT` and `MSG_DATA_STDERR`. - Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe. + - Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe. - When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**). + - When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**). ### domX: request execution of service `admin.Service` in dom0 @@ -150,41 +150,41 @@ Details of all possible use cases and the messages involved are described below. qrexec-client-vm dom0 admin.Service [local_program] [params] - (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout). + - (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout). - `qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**. + - `qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**. - `qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`. + - `qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`. - `qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0. + - `qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0. - **dom0**: `qrexec-daemon` receives the request and triggers `qrexec-policy` program, passing all necessary parameters: source domain **domX**, target domain **dom0**, service `admin.Service` and identifier `SOCKET11`. - `qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt. + - `qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt. - (If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back). + - (If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back). - **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command: qrexec-client -d dom0 -c domX,X,SOCKET11 "QUBESRPC admin.Service domX name dom0" - The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output. + - The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output. - The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0. + - The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0. - `qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`). + - `qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`). - `qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513). + - `qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513). - `qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513. + - `qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513. - Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`). + - Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`). - **dom0**: Because the command has the form `QUBESRPC: ...`, it is started through the `qubes-rpc-multiplexer` program with the provided parameters (`admin.Service domX name dom0`). That program finds and executes the necessary script in `/etc/qubes-rpc/`. - **domX**: `qrexec-agent` receives the `MSG_SERVICE_CONNECT` and passes the connection parameters back to the connected `qrexec-client-vm`. It identifies the `qrexec-client-vm` by the request identifier (`SOCKET11` means file descriptor 11). - `qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`. + - `qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`. - Data is forwarded between **dom0** and **domX** as in the previous example (dom0-VM). @@ -196,37 +196,37 @@ Details of all possible use cases and the messages involved are described below. qrexec-client-vm domY qubes.Service [local_program] [params] - (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout). + - (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout). - The request is forwarded as `MSG_TRIGGER_SERVICE3` to `qrexec-daemon` running in **dom0**, then to `qrexec-policy`, then (if allowed) to `qrexec-client`. - This is the same as in the previous example (VM-dom0). + - This is the same as in the previous example (VM-dom0). - **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command: qrexec-client -d domY -c domX,X,SOCKET11 user:cmd "DEFAULT:QUBESRPC qubes.Service domX" - The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output. + - The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output. - The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`). + - The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`). - `qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation. + - `qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation. - `qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username). + - `qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username). - Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513. + - Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513. - Having notified both domains about a connection, `qrexec-client` now exits. + - Having notified both domains about a connection, `qrexec-client` now exits. - **domX**: `qrexec-agent` receives a `MSG_SERVICE_CONNECT` with connection parameters (**domY** port 513) and request identifier (`SOCKET11`). It sends the connection parameters back to the right `qrexec-client-vm`. - `qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client. + - `qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client. - **domY**: `qrexec-agent` receives a `MSG_EXEC_CMDLINE` with the command to execute (`user:QUBESRPC...`) and connection parameters (**domX** port 513). - It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port. + - It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port. - Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`. + - Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`. - After that, the data is passed between **domX** and **domY** as in the previous examples (dom0-VM, VM-dom0). diff --git a/developer/services/qrexec-socket-services.md b/developer/services/qrexec-socket-services.md index 1dfd9d2d7..677cd2c9b 100644 --- a/developer/services/qrexec-socket-services.md +++ b/developer/services/qrexec-socket-services.md @@ -62,6 +62,7 @@ See the below example. `qrexec-policy-agent` is the program that handles "ask" prompts for Qubes RPC calls. It is a good example of an application that: + * Uses Python and asyncio. * Runs as a daemon, to save some overhead on starting process. * Runs as a normal user. diff --git a/developer/services/qrexec.md b/developer/services/qrexec.md index fbdc73275..4ee41d98b 100644 --- a/developer/services/qrexec.md +++ b/developer/services/qrexec.md @@ -238,7 +238,6 @@ This means it is possible to install a different script for a particular service See [below](#rpc-service-with-argument-file-reader) for an example of an RPC service using an argument. - ## Qubes RPC examples diff --git a/developer/services/qrexec2.md b/developer/services/qrexec2.md index 33d0f2193..8bbffb341 100644 --- a/developer/services/qrexec2.md +++ b/developer/services/qrexec2.md @@ -17,7 +17,7 @@ Qubes **qrexec** is a framework for implementing inter-VM (incl. Dom0-VM) services. It offers a mechanism to start programs in VMs, redirect their stdin/stdout, and a policy framework to control this all. -## Qrexec basics ## +## Qrexec basics During each domain creation a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM. They are @@ -56,7 +56,7 @@ There is a similar command line utility available inside Linux AppVMs (note the `-vm` suffix): `qrexec-client-vm` that will be described in subsequent sections. -## Qubes RPC services ## +## Qubes RPC services Apart from simple Dom0-\>VM command executions, as discussed above, it is also useful to have more advanced infrastructure for controlled inter-VM @@ -90,7 +90,7 @@ themselves. Qrexec framework is careful about connecting the stdin/stdout of the server process with the corresponding stdin/stdout of the requesting process in the requesting VM (see example Hello World service described below). -## Qubes RPC administration ## +## Qubes RPC administration Besides each VM needing to provide explicit programs to serve each supported service, the inter-VM service RPC is also governed by a central policy in Dom0. @@ -135,7 +135,7 @@ if still there is no policy file after prompting, the action is denied. On the target VM, the `/etc/qubes-rpc/XYZ` must exist, containing the file name of the program that will be invoked. -### Requesting VM-VM (and VM-Dom0) services execution ### +### Requesting VM-VM (and VM-Dom0) services execution In a src VM, one should invoke the qrexec client via the following command: @@ -161,7 +161,7 @@ If requesting VM-VM (and VM-Dom0) services execution *without cmdline helper*, connect directly to `/var/run/qubes/qrexec-agent-fdpass` socket as described [below](#all-the-pieces-together-at-work). -### Revoking "Yes to All" authorization ### +### Revoking "Yes to All" authorization Qubes RPC policy supports an "ask" action, that will prompt the user whether a given RPC call should be allowed. It is set as default for services such @@ -184,7 +184,7 @@ A user might also want to set their own policies in this section. This may mostly serve to prevent the user from mistakenly copying files or text from a trusted to untrusted domain, or vice-versa. -### Qubes RPC "Hello World" service ### +### Qubes RPC "Hello World" service We will show the necessary files to create a simple RPC call that adds two integers on the target VM and returns back the result to the invoking VM. @@ -232,7 +232,7 @@ be allowed. **Note:** For a real world example of writing a qrexec service, see this [blog post](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html). -### More high-level RPCs? ### +### More high-level RPCs? As previously noted, Qubes aims to provide mechanisms that are very simple and thus with very small attack surface. This is the reason why the inter-VM @@ -242,14 +242,14 @@ users/app developers are always free to run more high-level RPC protocols on top of qrexec. Care should be taken, however, to consider potential attack surfaces that are exposed to untrusted or less trusted VMs in that case. -# Qubes RPC internals # +## Qubes RPC internals (*This is about the implementation of qrexec v2. For the implementation of qrexec v3, see [here](/doc/qrexec-internals/). Note that the user API in v3 is backward compatible: qrexec apps written for Qubes R2 should run without modification on Qubes R3.*) -## Dom0 tools implementation ## +## Dom0 tools implementation Players: @@ -262,7 +262,7 @@ Players: **Note:** None of the above tools are designed to be used by users. -## Linux VMs implementation ## +## Linux VMs implementation Players: @@ -275,7 +275,7 @@ Players: **Note:** None of the above tools are designed to be used by users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps. -## Windows VMs implementation ## +## Windows VMs implementation `%QUBES_DIR%` is the installation path (`c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools` by default). @@ -291,7 +291,7 @@ Lab\Qubes OS Windows Tools` by default). **Note:** None of the above tools are designed to be used by users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps. -## All the pieces together at work ## +## All the pieces together at work **Note:** This section is not needed to use qrexec for writing Qubes apps. Also note the [qrexec framework implemention in Qubes R3](/doc/qrexec3/) diff --git a/developer/system/gui.md b/developer/system/gui.md index dfd04801d..e2b8c1eea 100644 --- a/developer/system/gui.md +++ b/developer/system/gui.md @@ -16,8 +16,8 @@ title: GUI virtualization All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers: -- *`dummyqsb_drv`* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware -- *`qubes_drv`* - it provides a virtual keyboard and mouse (in fact, more, see below) +- `dummyqsb_drv` - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware +- `qubes_drv` - it provides a virtual keyboard and mouse (in fact, more, see below) For each AppVM, there is a pair of `qubes-gui` (running in AppVM) and `qubes-guid` (running in the AppVM’s GuiVM, dom0 by default) processes connected over vchan. The main responsibilities of `qubes-gui` are: diff --git a/introduction/faq.md b/introduction/faq.md index 2258ee1b5..dd34b5114 100644 --- a/introduction/faq.md +++ b/introduction/faq.md @@ -144,7 +144,7 @@ Briefly, here are some of the main pros and cons of this approach relative to Qu (For example, you might find it natural to lock your secure laptop in a safe when you take your unsecure laptop out with you.)
- Cons + Cons
- Physical separation can be cumbersome and expensive, since we may have to obtain and set up a separate physical machine for each security level we need. diff --git a/introduction/getting-started.md b/introduction/getting-started.md index 93833e454..4c06d62ab 100644 --- a/introduction/getting-started.md +++ b/introduction/getting-started.md @@ -150,7 +150,7 @@ All aspects of Qubes OS can be controlled using command-line tools. Opening a terminal emulator in dom0 can be done in several ways: - Go to the App Menu and select **Terminal Emulator** at the top. -- Press `Alt`+`F3` and search for `xfce terminal`. +- Press `Alt` + `F3` and search for `xfce terminal`. - Right-click on the desktop and select **Open Terminal Here**. Terminal emulators can also be run in other qubes as normal programs. Various diff --git a/introduction/issue-tracking.md b/introduction/issue-tracking.md index 3296210ee..d628b3d42 100644 --- a/introduction/issue-tracking.md +++ b/introduction/issue-tracking.md @@ -95,11 +95,13 @@ Meta-issues must abide by the following rules: - Only members of the core team may create meta-issues (or convert existing issues into meta-issues). - Rationale: The purpose of meta-issues is to track the development of certain features that fit into the overall goals of the Qubes OS Project, which requires making informed project-management decisions with the approval of the project lead. + + - Rationale: The purpose of meta-issues is to track the development of certain features that fit into the overall goals of the Qubes OS Project, which requires making informed project-management decisions with the approval of the project lead. - Meta-issues must be [locked](https://docs.github.com/en/communities/moderating-comments-and-conversations/locking-conversations). - Rationale: One of the historical problems we've experienced with meta-issues (and one of the reasons they were discouraged for a long time) is that each meta-issue tends to turn into a discussion thread that becomes hopelessly long to the point where the person who is supposed to work on it has no idea what is supposed to be done or where to start, and it eventually just gets closed. Locking is intended to prevent that from happening again. + + - Rationale: One of the historical problems we've experienced with meta-issues (and one of the reasons they were discouraged for a long time) is that each meta-issue tends to turn into a discussion thread that becomes hopelessly long to the point where the person who is supposed to work on it has no idea what is supposed to be done or where to start, and it eventually just gets closed. Locking is intended to prevent that from happening again. - Meta-issues must have informative descriptions, not just lists of issues. In particular, each meta-issue should explain its goal, what is in scope, and what the relevant categories and priorities are. diff --git a/introduction/screenshots.md b/introduction/screenshots.md index 1f4b04d0f..36aea7f37 100644 --- a/introduction/screenshots.md +++ b/introduction/screenshots.md @@ -61,6 +61,7 @@ Qubes is all about seamless integration from the user’s point of view. Here yo [![r4.0-manager-and-sysnet-network-prompt.png](/attachment/doc/r4.0-manager-and-sysnet-network-prompt.png)](/attachment/doc/r4.0-manager-and-sysnet-network-prompt.png) All the networking runs in a special, unprivileged NetVM. (Notice the red frame around the Network Manager dialog box on the screen above.) This means that in the event that your network card driver, Wi-Fi stack, or DHCP client is compromised, the integrity of the rest of the system will not be affected! This feature requires Intel VT-d or AMD IOMMU hardware (e.g., Core i5/i7 systems) + * * * * * [![r4.0-software-update.png](/attachment/doc/r4.0-software-update.png)](/attachment/doc/r4.0-software-update.png) diff --git a/introduction/support.md b/introduction/support.md index b12bb55fb..b41765dad 100644 --- a/introduction/support.md +++ b/introduction/support.md @@ -499,11 +499,11 @@ too](https://forum.qubes-os.org/t/using-the-forum-via-email/533)!) The Qubes OS Project has a presence on the following social media platforms: -- Twitter -- Mastodon -- Reddit -- Facebook -- LinkedIn +- [Twitter](https://twitter.com/QubesOS) +- [Mastodon](https://mastodon.social/@QubesOS) +- [Reddit](https://www.reddit.com/r/Qubes/) +- [Facebook](https://www.facebook.com/QubesOS/) +- [LinkedIn](https://www.linkedin.com/company/qubes-os/) Generally speaking, these are not intended to be primary support venues. (Those would be [qubes-users](#qubes-users) and the [forum](#forum).) Rather, these @@ -515,6 +515,7 @@ news. ## Chat If you'd like to chat, join us on + - the `#qubes` channel on `irc.libera.chat` or - the `#qubes:invisiblethingslab.com` matrix channel. diff --git a/project-security/verifying-signatures.md b/project-security/verifying-signatures.md index 54e230e83..2a483f01c 100644 --- a/project-security/verifying-signatures.md +++ b/project-security/verifying-signatures.md @@ -833,6 +833,7 @@ the arguments to `gpg2`. (The signature file goes first.) ### Why am I getting "WARNING: This key is not certified with a trusted signature! There is no indication that the signature belongs to the owner."? There are several possibilities: + - You don't have the [Qubes Master Signing Key](#how-to-import-and-authenticate-the-qubes-master-signing-key). - You have not [set the Qubes Master Signing Key's trust level diff --git a/user/advanced-topics/bind-dirs.md b/user/advanced-topics/bind-dirs.md index acdc515d2..210eb3830 100644 --- a/user/advanced-topics/bind-dirs.md +++ b/user/advanced-topics/bind-dirs.md @@ -8,21 +8,20 @@ ref: 186 title: How to make any file persistent (bind-dirs) --- -## What are bind-dirs? ## +## What are bind-dirs? With [bind-dirs](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh) any arbitrary files or folders can be made persistent in app qubes. -## What is it useful for? ## +## What is it useful for? In an app qube all of the file system comes from the template except `/home`, `/usr/local`, and `/rw`. This means that changes in the rest of the filesystem are lost when the app qube is shutdown. bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots. -For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5) -In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a standalone. +For example, in Whonix, Tor's data dir `/var/lib/tor` [has been made persistent](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5) in the TemplateBased ProxyVM sys-whonix. In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a standalone. -## How to use bind-dirs.sh? ## +## How to use bind-dirs.sh? In this example, we want to make `/var/lib/tor` persistent. Enter all of the following commands in your app qube. @@ -68,13 +67,13 @@ binds+=( '/var/lib/tor' ) binds+=( '/etc/tor/torrc' ) ``` -## Other Configuration Folders ## +## Other Configuration Folders * `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages) * `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration) * `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration) -## How does it work? ## +## How does it work? bind-dirs.sh is called at startup of an app qube, and configuration files in the above configuration folders are parsed to build a bash array. Files or folders identified in the array are copied to `/rw/bind-dirs` if they do not already exist there, and are then bind mounted over the original files/folders. @@ -84,7 +83,7 @@ Creation of the files and folders in `/rw/bind-dirs` should be automatic the fir If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot. Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor` -## Limitations ## +## Limitations * Files that exist in the template root image cannot be deleted in the app qubes root image using bind-dirs.sh. * Re-running `sudo /usr/lib/qubes/init/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/init/bind-dirs.sh umount` does not work. @@ -95,7 +94,7 @@ Any changes you make will not survive a reboot. If you think it likely you will If you try to use bind-dirs on such files you may break your qube in unpredictable ways. You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files) -## How to remove binds from bind-dirs.sh? ## +## How to remove binds from bind-dirs.sh? `binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are sourced as bash snippets in lexical order. Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file. diff --git a/user/advanced-topics/gui-configuration.md b/user/advanced-topics/gui-configuration.md index 2f02bbe86..b622ac999 100644 --- a/user/advanced-topics/gui-configuration.md +++ b/user/advanced-topics/gui-configuration.md @@ -31,6 +31,7 @@ qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e ``` The amount of memory allocated per qube is the maximum of: + - `gui-videoram-min` - current display + `gui-videoram-overhead` diff --git a/user/advanced-topics/managing-vm-kernels.md b/user/advanced-topics/managing-vm-kernels.md index 1dab8a44a..bf0745eca 100644 --- a/user/advanced-topics/managing-vm-kernels.md +++ b/user/advanced-topics/managing-vm-kernels.md @@ -154,6 +154,7 @@ The newly installed package is set as the default VM kernel. It is possible to package a kernel installed in dom0 as a VM kernel. This makes it possible to use a VM kernel which is not packaged by Qubes team. This includes: + * using a Fedora kernel package * using a manually compiled kernel diff --git a/user/advanced-topics/mount-from-other-os.md b/user/advanced-topics/mount-from-other-os.md index 864416661..e930cf8e5 100644 --- a/user/advanced-topics/mount-from-other-os.md +++ b/user/advanced-topics/mount-from-other-os.md @@ -13,6 +13,7 @@ title: How to mount a Qubes partition from another OS When a Qubes OS install is unbootable or booting it is otherwise undesirable, this process allows for the recovery of files stored within the system. These functions are manual and do not require any Qubes specific tools. All steps assume the default Qubes install with the following components: + - LUKS encrypted disk - LVM based VM storage diff --git a/user/advanced-topics/salt.md b/user/advanced-topics/salt.md index 2aa2c1242..0b5633deb 100644 --- a/user/advanced-topics/salt.md +++ b/user/advanced-topics/salt.md @@ -588,6 +588,7 @@ qube which provides network to the given qube The output for each qube is logged in `/var/log/qubes/mgmt-VM_NAME.log`. If the log does not contain useful information: + 1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.apply` 2. When your qube is being started (yellow) press Ctrl-z on qubesctl. 3. Open terminal in disp-mgmt-qube_NAME. @@ -595,10 +596,10 @@ If the log does not contain useful information: executed in the management qube. 5. Get the last two lines: - ```shell_session - $ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH" - $ salt-ssh "$target_vm" $salt_command - ``` +```shell_session +$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH" +$ salt-ssh "$target_vm" $salt_command +``` Adjust $target_vm (VM_NAME) and $salt_command (state.apply). 6. Execute them, fix problems, repeat. diff --git a/user/advanced-topics/standalones-and-hvms.md b/user/advanced-topics/standalones-and-hvms.md index 198dab421..35c4f9cff 100644 --- a/user/advanced-topics/standalones-and-hvms.md +++ b/user/advanced-topics/standalones-and-hvms.md @@ -68,6 +68,7 @@ qvm-create --class StandaloneVM --label --property virt_mode=hvm -- ``` Notes: + - Technically, `virt_mode=hvm` is not necessary for every standalone. However, it is needed if you want to use a kernel from within the qube. - If you want to make software installed in a template available in your standalone, pass in the name of the template using the `--template` option. diff --git a/user/downloading-installing-upgrading/installation-guide.md b/user/downloading-installing-upgrading/installation-guide.md index c38cbc355..6e3a07d95 100644 --- a/user/downloading-installing-upgrading/installation-guide.md +++ b/user/downloading-installing-upgrading/installation-guide.md @@ -172,6 +172,8 @@ You can have as many keyboard layout and languages as you want. Post-install, yo Don't forget to select your time and date by clicking on the Time & Date entry. [![Time and date](/attachment/doc/time-and-date.png)](/attachment/doc/time-and-date.png) + + ### Installation destination Under the System section, you must choose the installation destination. Select the storage device on which you would like to install Qubes OS. diff --git a/user/downloading-installing-upgrading/upgrade/3_1.md b/user/downloading-installing-upgrading/upgrade/3_1.md index 40aff3651..09b67956d 100644 --- a/user/downloading-installing-upgrading/upgrade/3_1.md +++ b/user/downloading-installing-upgrading/upgrade/3_1.md @@ -98,11 +98,11 @@ complete. 4. Reboot dom0. - The system may hang during the reboot. If that happens, do not panic. All - the filesystems will have already been unmounted at this stage, so you can - simply perform a hard reboot (e.g., hold the physical power button down - until the machine shuts off, wait a moment, then press it again to start it - back up). + - The system may hang during the reboot. If that happens, do not panic. All + the filesystems will have already been unmounted at this stage, so you can + simply perform a hard reboot (e.g., hold the physical power button down + until the machine shuts off, wait a moment, then press it again to start it + back up). Please note that if you use [Anti Evil Maid](/doc/anti-evil-maid), it won't be able to unseal the passphrase the first time the system boots after performing diff --git a/user/hardware/system-requirements.md b/user/hardware/system-requirements.md index ffe39f7c4..63aabd509 100644 --- a/user/hardware/system-requirements.md +++ b/user/hardware/system-requirements.md @@ -122,7 +122,7 @@ We recommend consulting these resources when selecting hardware for Qubes OS: 2. The user's OEM, ODM, or MB to provide a suitable BIOS or (U)EFI update for the user's system. - Historically, AMD has often been slow to complete step (1), at least for its + - Historically, AMD has often been slow to complete step (1), at least for its client (as opposed to server) platforms. In some cases, AMD has made fixes available for its server platforms very shortly after a security embargo was lifted, but it did not make fixes available for client platforms facing the @@ -132,10 +132,10 @@ We recommend consulting these resources when selecting hardware for Qubes OS: new CPU vulnerabilities across its supported platforms very shortly after security embargoes have been lifted. - Step (2) varies by vendor. Many vendors fail to complete step (2) at all, + - Step (2) varies by vendor. Many vendors fail to complete step (2) at all, while some others take a very long time to complete it. - The bottom line is that Qubes OS **can** run on AMD systems, and the Qubes and + - The bottom line is that Qubes OS **can** run on AMD systems, and the Qubes and Xen security teams do their best to provide security support for AMD systems. However, without the ability to ship microcode updates, there is only so much they can do. diff --git a/user/how-to-guides/backup-emergency-restore-v3.md b/user/how-to-guides/backup-emergency-restore-v3.md index 2b54406f2..efa42c2ae 100644 --- a/user/how-to-guides/backup-emergency-restore-v3.md +++ b/user/how-to-guides/backup-emergency-restore-v3.md @@ -52,11 +52,11 @@ any GNU/Linux system with the following procedure. [user@restore ~]$ cat backup-header.hmac (stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c - **Note:** The hash values should match. If they do not match, then the + - **Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error. - **Note:** If your backup was hashed with a message digest algorithm other + - **Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 4), however it is not recommended to open this file until its integrity and @@ -86,11 +86,11 @@ any GNU/Linux system with the following procedure. [user@restore vm1]$ cat private.img.000.hmac (stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e - **Note:** The hash values should match. If they do not match, then the + - **Note:** The hash values should match. If they do not match, then the backup file may have been tampered with, or there may have been a storage error. - **Note:** If your backup was hashed with a message digest algorithm other + - **Note:** If your backup was hashed with a message digest algorithm other than `sha512`, you must substitute the correct message digest command. This information is contained in the `backup-header` file (see step 4). A complete list of supported message digest algorithms can be found with @@ -135,7 +135,7 @@ any GNU/Linux system with the following procedure. 10. Success! If you wish to recover data from more than one VM in your backup, simply repeat steps 5--9 for each additional VM. - **Note:** You may wish to store a copy of these instructions with your + - **Note:** You may wish to store a copy of these instructions with your Qubes backups in the event that you fail to recall the above procedure while this web page is inaccessible. All Qubes documentation, including this page, is available in plain text format in the following Git diff --git a/user/how-to-guides/backup-emergency-restore-v4.md b/user/how-to-guides/backup-emergency-restore-v4.md index 19367a246..fe9d44213 100644 --- a/user/how-to-guides/backup-emergency-restore-v4.md +++ b/user/how-to-guides/backup-emergency-restore-v4.md @@ -152,10 +152,10 @@ Emergency Recovery Instructions done | gzip -d | tar -xv vm1/private.img - If this pipeline fails, it is likely that the backup is corrupted or has + - If this pipeline fails, it is likely that the backup is corrupted or has been tampered with. - **Note:** If your backup was compressed with a program other than `gzip`, + - **Note:** If your backup was compressed with a program other than `gzip`, you must substitute the correct compression program in the command above. This information is contained in `backup-header` (see step 4). For example, if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the @@ -171,7 +171,7 @@ Emergency Recovery Instructions 8. Success! If you wish to recover data from more than one VM in your backup, simply repeat steps 6 and 7 for each additional VM. - **Note:** You may wish to store a copy of these instructions with your + - **Note:** You may wish to store a copy of these instructions with your Qubes backups in the event that you fail to recall the above procedure while this web page is inaccessible. All Qubes documentation, including this page, is available in plain text format in the following Git diff --git a/user/how-to-guides/how-to-back-up-restore-and-migrate.md b/user/how-to-guides/how-to-back-up-restore-and-migrate.md index fa33d83ec..0cb0ef5af 100644 --- a/user/how-to-guides/how-to-back-up-restore-and-migrate.md +++ b/user/how-to-guides/how-to-back-up-restore-and-migrate.md @@ -53,44 +53,44 @@ fresh installation. 2. Move the VMs that you want to back up to the right-hand **Selected** column. VMs in the left-hand **Available** column will not be backed up. - You may choose whether to compress backups by checking or unchecking the - **Compress the backup** box. Normally this should be left on unless you have - a specific reason otherwise. + - You may choose whether to compress backups by checking or unchecking the + **Compress the backup** box. Normally this should be left on unless you have + a specific reason otherwise. - Once you have selected all desired VMs, click **Next**. + - Once you have selected all desired VMs, click **Next**. 3. Select the destination for the backup: - If you wish to send your backup to a (currently running) VM, select the VM - in the drop-down box next to **Target app qube**. If you wish to send your - backup to a [USB mass storage device](/doc/usb/), you can use the directory - selection widget to mount a connected device (under "Other locations" item - on the left); or first mount the device in a VM, then select the mount point - inside that VM as the backup destination. - - You must also specify a directory on the device or in the VM, or a command - to be executed in the VM as a destination for your backup. For example, if - you wish to send your backup to the `~/backups` folder in the target VM, you - would simply browse to it using the convenient directory selection dialog - (`...`) at the right. This destination directory must already exist. If it - does not exist, you must create it manually prior to backing up. - - By specifying the appropriate directory as the destination in a VM, it is - possible to send the backup directly to, e.g., a USB mass storage device - attached to the VM. Likewise, it is possible to enter any command as a - backup target by specifying the command as the destination in the VM. This - can be used to send your backup directly to, e.g., a remote server using - SSH. - - **Note:** The supplied passphrase is used for **both** encryption/decryption - and integrity verification. - - At this point, you may also choose whether to save your settings by checking - or unchecking the **Save settings as default backup profile** box. - - **Warning: Saving the settings will result in your backup passphrase being - saved in plaintext in dom0, so consider your threat model before checking - this box.** + - If you wish to send your backup to a (currently running) VM, select the VM + in the drop-down box next to **Target app qube**. If you wish to send your + backup to a [USB mass storage device](/doc/usb/), you can use the directory + selection widget to mount a connected device (under "Other locations" item + on the left); or first mount the device in a VM, then select the mount point + inside that VM as the backup destination. + + - You must also specify a directory on the device or in the VM, or a command + to be executed in the VM as a destination for your backup. For example, if + you wish to send your backup to the `~/backups` folder in the target VM, you + would simply browse to it using the convenient directory selection dialog + (`...`) at the right. This destination directory must already exist. If it + does not exist, you must create it manually prior to backing up. + + - By specifying the appropriate directory as the destination in a VM, it is + possible to send the backup directly to, e.g., a USB mass storage device + attached to the VM. Likewise, it is possible to enter any command as a + backup target by specifying the command as the destination in the VM. This + can be used to send your backup directly to, e.g., a remote server using + SSH. + + - **Note:** The supplied passphrase is used for **both** encryption/decryption + and integrity verification. + + - At this point, you may also choose whether to save your settings by checking + or unchecking the **Save settings as default backup profile** box. + + - **Warning: Saving the settings will result in your backup passphrase being + saved in plaintext in dom0, so consider your threat model before checking + this box.** 4. You will now see the summary of VMs to be backed up. If there are any issues preventing the backup, they will be listed here and the **Next** button @@ -148,10 +148,10 @@ fresh installation. a passphrase was supplied during the creation of your backup (regardless of whether it is encrypted), then you must supply it here. - **Note:** The passphrase which was supplied when the backup was created is - used for **both** encryption/decryption and integrity verification. If the - backup was not encrypted, the supplied passphrase is used only for integrity - verification. All backups made from a Qubes R4.0 system will be encrypted. + - **Note:** The passphrase which was supplied when the backup was created is + used for **both** encryption/decryption and integrity verification. If the + backup was not encrypted, the supplied passphrase is used only for integrity + verification. All backups made from a Qubes R4.0 system will be encrypted. 5. You will now see the summary of VMs to be restored. If there are any issues preventing the restore, they will be listed here and the **Next** button grayed diff --git a/user/how-to-guides/how-to-copy-from-dom0.md b/user/how-to-guides/how-to-copy-from-dom0.md index 0aacfcbb3..321bc6801 100644 --- a/user/how-to-guides/how-to-copy-from-dom0.md +++ b/user/how-to-guides/how-to-copy-from-dom0.md @@ -15,7 +15,7 @@ title: How to copy from dom0 This page covers copying files and clipboard text between [dom0](/doc/glossary/#dom0) and [domUs](/doc/glossary/#domu). Since dom0 is special, the processes are different from [copying and pasting text between qubes](/doc/how-to-copy-and-paste-text/) and [copying and moving files between qubes](/doc/how-to-copy-and-move-files/). -## Copying **from** dom0 +## Copying *from* dom0 ### Copying files from dom0 @@ -61,7 +61,7 @@ In order to easily copy/paste the contents of logs from dom0 to the inter-VM cli You may now paste the log contents in qube as you normally would (e.g., Ctrl+Shift+V, then Ctrl+V). -## Copying **to** dom0 +## Copying *to* dom0 Copying anything into dom0 is not advised, since doing so can compromise the security of your Qubes system. For this reason, there is no simple means of copying anything into dom0, unlike [copying from dom0](#copying-from-dom0). diff --git a/user/how-to-guides/how-to-install-software.md b/user/how-to-guides/how-to-install-software.md index da7aae0e4..9a156b936 100644 --- a/user/how-to-guides/how-to-install-software.md +++ b/user/how-to-guides/how-to-install-software.md @@ -432,10 +432,10 @@ these in an app qube you need to take the following steps: **app qube*** launch the Qube Settings. Then go to the Applications tab and click "Refresh Applications" - The refresh will take a few minutes; after it's complete the Snap app will - appear in the app qube's list of available applications. At this point the - snap will be persistent within the app qube and will receive updates when - the app qube is running. + - The refresh will take a few minutes; after it's complete the Snap app will + appear in the app qube's list of available applications. At this point the + snap will be persistent within the app qube and will receive updates when + the app qube is running. ### Autostarting Installed Applications diff --git a/user/how-to-guides/how-to-reinstall-a-template.md b/user/how-to-guides/how-to-reinstall-a-template.md index cc7cce67a..f7d803bf0 100644 --- a/user/how-to-guides/how-to-reinstall-a-template.md +++ b/user/how-to-guides/how-to-reinstall-a-template.md @@ -48,14 +48,16 @@ If you want to reinstall more than one template, repeat these instructions for e 1. Clone the existing target template. - This can be a good idea if you've customized the existing template and want to keep your customizations. - On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure. + + - This can be a good idea if you've customized the existing template and want to keep your customizations. + On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure. 2. Temporarily change all VMs based on the target template to the new clone template, or remove them. - This can be a good idea if you have user data in these VMs that you want to keep. - On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead. - You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove ` in dom0. + + - This can be a good idea if you have user data in these VMs that you want to keep. + On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead. + You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove ` in dom0. 3. Uninstall the target template from dom0: diff --git a/user/how-to-guides/how-to-use-block-storage-devices.md b/user/how-to-guides/how-to-use-block-storage-devices.md index 5658682af..a46f1a8ed 100644 --- a/user/how-to-guides/how-to-use-block-storage-devices.md +++ b/user/how-to-guides/how-to-use-block-storage-devices.md @@ -90,9 +90,9 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger qvm-block attach work sys-usb:sdb ``` - This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. + - This will attach the device to the qube as `/dev/xvdi` if that name is not already taken by another attached device, or `/dev/xvdj`, etc. - You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. + - You may also mount one partition at a time by using the same command with the partition number, e.g. `sdb1`. 3. The block device is now attached to the qube. If using a default qube, you may open the Nautilus file manager in the qube, and your drive should be visible in the **Devices** panel on the left. @@ -106,7 +106,7 @@ If you don't see anything that looks like your drive, run `sudo udevadm trigger 4. When you finish using the block device, click the eject button or right-click and select **Unmount**. - If you've manually mounted a single partition in the above step, use: + - If you've manually mounted a single partition in the above step, use: ``` sudo umount mnt @@ -179,10 +179,10 @@ To attach a file as block device to another qube, first turn it into a loopback 2. If you want to use the GUI, you're done. Click the Device Manager ![device manager icon](/attachment/doc/media-removable.png) and select the `loop0`-device to attach it to another qube. - If you rather use the command line, continue: + - 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: ```shell_session ~]$ qvm-block diff --git a/user/how-to-guides/how-to-use-devices.md b/user/how-to-guides/how-to-use-devices.md index 3b65f1e6a..c8d2c0ebe 100644 --- a/user/how-to-guides/how-to-use-devices.md +++ b/user/how-to-guides/how-to-use-devices.md @@ -26,6 +26,7 @@ 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 - Block devices - USB devices diff --git a/user/how-to-guides/how-to-use-disposables.md b/user/how-to-guides/how-to-use-disposables.md index 2a0f7eaaa..25c1d43ac 100644 --- a/user/how-to-guides/how-to-use-disposables.md +++ b/user/how-to-guides/how-to-use-disposables.md @@ -171,6 +171,7 @@ In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/pol ~~~ This line means: + - FROM: Any qube - TO: A disposable based on `` - WHAT: Allow sending an "Open URL" request diff --git a/user/security-in-qubes/data-leaks.md b/user/security-in-qubes/data-leaks.md index 51c81201d..a341143e4 100644 --- a/user/security-in-qubes/data-leaks.md +++ b/user/security-in-qubes/data-leaks.md @@ -48,9 +48,9 @@ Such attacks have been described in the academic literature, but it is doubtful 3. **Unintentional leaks.** Non-malicious software which is either buggy or doesn't maintain the privacy of user data, whether by design or accident. For example, software which automatically sends error reports to a remote server, where these reports contain details about the system which the user did not want to share. - Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3. - However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2. - There are few effective, practical policy measures available to end-users today to stop the leaks of type 1. - It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation). +Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3. +However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2. +There are few effective, practical policy measures available to end-users today to stop the leaks of type 1. +It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation). For further discussion, see [this thread](https://groups.google.com/d/topic/qubes-users/t0cmNfuVduw/discussion). diff --git a/user/security-in-qubes/firewall.md b/user/security-in-qubes/firewall.md index a94f087a4..558a34aaa 100644 --- a/user/security-in-qubes/firewall.md +++ b/user/security-in-qubes/firewall.md @@ -165,7 +165,7 @@ Consider the following example. `mytcp-service` qube has a TCP service running o [user@untrusted #]$ qvm-connect-tcp 444:@default:444 ~~~ -> Note: The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port. +- **Note:** The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port. The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:444`. @@ -263,9 +263,9 @@ In order to allow a service present in a qube to be exposed to the outside world As an example we can take the use case of qube QubeDest running a web server listening on port 443 that we want to expose on our physical interface ens6, but only to our local network 192.168.x.y/24. -> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running +- **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running -> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port. +- **Note:** [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port. **1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.** @@ -278,7 +278,7 @@ You can get this information using various methods, but only the first one can b Note the IP addresses you will need, they will be required in the next steps. -> Note: The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface. +- **Note:** The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface. **2. Route packets from the outside world to the FirewallVM** @@ -290,9 +290,9 @@ In the sys-net VM's Terminal, the first step is to define an ntables chain that nft add chain qubes custom-dnat-qubeDEST '{ type nat hook prerouting priority filter +1 ; policy accept; }' ``` -> Note: the name `custom-dnat-qubeDST` is arbitrary +- **Note:** the name `custom-dnat-qubeDST` is arbitrary -> Note: while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes +- **Note:** while we use a DNAT chain for a single qube, it's totally possible to have a single DNAT chain for multiple qubes Second step, code a natting firewall rule to route traffic on the outside interface for the service to the sys-firewall VM @@ -306,9 +306,9 @@ Third step, code the appropriate new filtering firewall rule to allow new connec nft add rule qubes custom-forward iif == "ens6" ip saddr 192.168.x.y/24 ip daddr 10.137.1.z tcp dport 443 ct state new,established,related counter accept ``` -> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules +- **Note:** If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules -> If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely. +- If you want to expose the service on multiple interfaces, repeat the steps 2 and 3 described above, for each interface. Alternatively, you can leave out the interface completely. Verify the rules on sys-net firewall correctly match the packets you want by looking at its counters, check for the counter lines in the chains `custom-forward` and `custom-dnat-qubeDEST`: @@ -380,7 +380,7 @@ Third step, code the appropriate new filtering firewall rule to allow new connec nft add rule qubes custom-forward iif == "eth0" ip saddr 192.168.x.y/24 ip daddr 10.137.0.xx tcp dport 443 ct state new,established,related counter accept ``` -> Note: If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules +- **Note:** If you do not wish to limit the IP addresses connecting to the service, remove `ip saddr 192.168.x.y/24` from the rules Once you have confirmed that the counters increase, store these commands in the script `/rw/config/qubes-firewall-user-script` diff --git a/user/security-in-qubes/firewall_4.1.md b/user/security-in-qubes/firewall_4.1.md index 5c00c9f90..7c5e2769c 100644 --- a/user/security-in-qubes/firewall_4.1.md +++ b/user/security-in-qubes/firewall_4.1.md @@ -155,11 +155,10 @@ Consider the following example. `mytcp-service` qube has a TCP service running o - In untrusted, use the Qubes tool `qvm-connect-tcp`: - ~~~ + ``` [user@untrusted #]$ qvm-connect-tcp 444:@default:444 - ~~~ - -> Note: The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port. + ``` +- **Note:** The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port. The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:444`. @@ -257,15 +256,16 @@ In order to allow a service present in a qube to be exposed to the outside world As an example we can take the use case of a web server listening on port 443 that we want to expose on our physical interface eth0, but only to our local network 192.168.x.0/24. -> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running + - **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running -> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port. + - **Note:** [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port. **1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.** You can get this information from the Settings Window for the qube, or by running this command in each qube: `ifconfig | grep -i cast ` Note the IP addresses you will need. + > Note: The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface. **2. Route packets from the outside world to the FirewallVM** @@ -280,23 +280,23 @@ iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j DNAT Code the appropriate new filtering firewall rule to allow new connections for the service -``` -iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT -``` + ``` + iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT + ``` -> If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface. -> In Qubes R4, at the moment ([QubesOS/qubes-issues#3644](https://github.com/QubesOS/qubes-issues/issues/3644)), nftables is also used which imply that additional rules need to be set in a `qubes-firewall` nft table with a forward chain. + - If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface. + - In Qubes R4, at the moment ([QubesOS/qubes-issues#3644](https://github.com/QubesOS/qubes-issues/issues/3644)), nftables is also used which imply that additional rules need to be set in a `qubes-firewall` nft table with a forward chain. `nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.1.z tcp dport 443 ct state new counter accept` Verify you are cutting through the sys-net VM firewall by looking at its counters (column 2) -``` -iptables -t nat -L -v -n -iptables -L -v -n -``` + ``` + iptables -t nat -L -v -n + iptables -L -v -n + ``` + - **Note:** On Qubes R4, you can also check the nft counters -> Note: On Qubes R4, you can also check the nft counters ``` nft list table ip qubes-firewall @@ -358,7 +358,9 @@ if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then fi ~~~ -> Note: Again in R4 the following needs to be added: + + - **Note:** Again in R4 the following needs to be added: + ~~~ ############# @@ -389,9 +391,9 @@ Code the appropriate new filtering firewall rule to allow new connections for th iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT ``` -> Note: If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 ` + - **Note:** If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 ` -> Note: On Qubes R4 + - **Note:** On Qubes R4 ``` nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept diff --git a/user/security-in-qubes/mfa.md b/user/security-in-qubes/mfa.md index 62a72e173..ec436f5a7 100644 --- a/user/security-in-qubes/mfa.md +++ b/user/security-in-qubes/mfa.md @@ -60,7 +60,7 @@ and then use it as an additional factor to login to your Qubes system. > **Warning**: in the next session if incorrectly performed, there is the risk of locking yourself out. Before procedding ensure that you have an up-to-date backup. > -> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do ctrl+alt+F2 and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with ctrl+alt+F1. +> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do `ctrl` + `alt` + `F2` and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with `ctrl` + `alt` + `F1`. Now we are going to add the authenticator as a login requirement: @@ -89,7 +89,7 @@ Now we are going to add the authenticator as a login requirement: sudo authselect select custom/mfa ``` -Now you can test by locking the screen with ctrl+alt+l. If it was successful and you are pleased with the results, restart your computer. +Now you can test by locking the screen with `ctrl` + `alt` + `l` . If it was successful and you are pleased with the results, restart your computer. **Note**: When logging in. the first thing you put is the TOTP secret and then the password. This is true in the screen locker and as well as the session manager (the login window that shows right after you put the disk encryption passphrase). @@ -99,12 +99,12 @@ After this is done, its recommended to do a backup. This is because as long as y The following assumes you haven't restarted your computer since setting up TOTP secret. -1. Switch to TTY2 with ctrl+alt+F2. +1. Switch to TTY2 with `ctrl` + `alt` + `F2` . 2. Revert to the original policy with: ``` sudo authselect select sssd ``` -3. Switch back to the graphical desktop with ctrl+alt+F1. You should be able to login normally (without multi-factor authentication). +3. Switch back to the graphical desktop with `ctrl` + `alt` + `F1` . You should be able to login normally (without multi-factor authentication). 4. Change the mfa custom policy and apply it again. #### Lost TOTP / authentication device? @@ -157,26 +157,28 @@ Note that setting up both a YubiKey and a NitroKey3 is not supported. 1. Install YubiKey / NitroKey3 software in the template on which your USB VM is based. Without this software the challenge-response / HOTP mechanism won't work. - **YubiKey** + - **YubiKey** - For Fedora. + - For Fedora. - ``` - sudo dnf install ykpers - ``` + ``` + sudo dnf install ykpers + ``` - For Debian. + - For Debian. - ``` - sudo apt-get install yubikey-personalization - ``` + ``` + sudo apt-get install yubikey-personalization + ``` - **NitroKey3** + - **NitroKey3** - Follow the installation instructions on the official [NitroKey + + - Follow the installation instructions on the official [NitroKey website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation). + - **WARNING**: *as of April 2024 the official instructions involve using pipx to + - **WARNING**: *as of April 2024 the official instructions involve using pipx to install the pynitrokey package and its dependencies without any GPG verification! This is not a recommended practice, but will soon be fixed by NitroKey when they start providing release artifacts with @@ -184,10 +186,12 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation). Proper packaging and distribution for Debian and perhaps Fedora is also planned for the mid-long term.* **Installing packages using pip or pipx is not recommended!** - - **both** - Shut down your template. Then, either reboot your USB VM (so changes inside + + - **both** + + + - Shut down your template. Then, either reboot your USB VM (so changes inside the template take effect in your USB app qube) or install the packages inside your USB VM as well if you would like to avoid rebooting it. @@ -199,64 +203,72 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation). ``` 3. Configure your YubiKey / NitroKey3: + - **YubiKey** + - **YubiKey** + - Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be + - Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be done on any qube, e.g. a disposable (you need to [attach the YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube -though) or directly on the sys-usb vm. - - You need to (temporarily) install the package "yubikey-personalization-gui" and +though) or directly on the sys-usb vm. You need to (temporarily) install the package "yubikey-personalization-gui" and run it by typing `yubikey-personalization-gui` in the command line. - - In the program go to `Challenge-Response`, - - select `HMAC-SHA1`, - - choose `Configuration Slot 2`, - - optional: enable `Require user input (button press)` (recommended), - - use `fixed 64 bit input` for `HMAC-SHA1 mode`, - - insert the YubiKey (if not done already) and make sure that it is attached - to the vm, - - press `Write Configuration` once you are ready. + - In the program go to `Challenge-Response`, + - select `HMAC-SHA1`, + - choose `Configuration Slot 2`, + - optional: enable `Require user input (button press)` (recommended), + - use `fixed 64 bit input` for `HMAC-SHA1 mode`, + - insert the YubiKey (if not done already) and make sure that it is attached + to the vm, + - press `Write Configuration` once you are ready. + + - **NitroKey3** - **NitroKey3** - Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your + - Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your USB qube and running the following commands in it: - ``` - AESKEY=$(echo -n "your-20-digit-secret" | base32) - nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY - ``` - Note that the 20 digit sequence can contain any printable ASCII character, + + ``` + AESKEY=$(echo -n "your-20-digit-secret" | base32) + nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY + ``` + + - Note that the 20 digit sequence can contain any printable ASCII character, e.g. letters, numbers, punctuation marks. The actual `Secret Key (base 32)` is the base32 encoded form of that sequence. - **both** - We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `AESKEY`. + - **both** + - - It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault. - - Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place. - - If you have multiple YubiKeys for backup purposes (in case one gets - lost, stolen or breaks) you can write the same settings into other -YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program; - make sure to select `Same secret for all keys` in this case. For NitroKeys you can set up -the secret for multiple of them, but you must always use the same NitroKey, because the -HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use -of this method. If you want to switch to a different NitroKey later, delete the file -`/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3. -Do the same if for some reason your counters get desynchronized (it stops working), e.g. due -to connectivity issues (NitroKey3A Minis are known to wear out quickly). + - We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `AESKEY`. + + - It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault. + - Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place. + - If you have multiple YubiKeys for backup purposes (in case one gets + lost, stolen or breaks) you can write the same settings into other + YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program; + make sure to select `Same secret for all keys` in this case. For NitroKeys you can set up + the secret for multiple of them, but you must always use the same NitroKey, because the + HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use + of this method. If you want to switch to a different NitroKey later, delete the file + `/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3. + Do the same if for some reason your counters get desynchronized (it stops working), e.g. due + to connectivity issues (NitroKey3A Minis are known to wear out quickly). 4. **YubiKey** - Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0. + + - Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0. Note that if you had previously used a NitroKey3 with this package, you *must* delete the file `/etc/qubes/yk-keys/nk-hotp-secret` or its content! - **NitroKey3** - Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY` + - **NitroKey3** + + + - Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY` (in base 32 format) into it. 5. As mentioned before, you need to define a new password that is only used in @@ -264,22 +276,24 @@ to connectivity issues (NitroKey3A Minis are known to wear out quickly). `/etc/qubes/yk-keys/login-pass` in dom0. This is considered safe as dom0 is ultimately trusted anyway. - However, if you prefer you can paste a hashed password instead into + + - However, if you prefer you can paste a hashed password instead into `/etc/qubes/yk-keys/login-pass-hashed.hex` in dom0. - You can calculate your hashed password using the following two commands. + + - You can calculate your hashed password using the following two commands. First run the following command to store your password in a temporary variable `password`. (This way your password will not leak to the terminal command history file.) - ``` - read -r password - ``` + ``` + read -r password + ``` - Now run the following command to calculate your hashed password. + - Now run the following command to calculate your hashed password. - ``` - echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' ' - ``` + ``` + echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' ' + ``` 6. To enable multi-factor authentication for a service, you need to add @@ -353,7 +367,7 @@ In dom0: In your USB VM: -3. Create udev hook. +1. Create udev hook. Store it in `/rw/config` to have it persist across VM restarts. For example name the file `/rw/config/yubikey.rules`. Add the following line: @@ -362,7 +376,7 @@ In your USB VM: ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SECURITY_TOKEN}=="1", RUN+="/usr/bin/qrexec-client-vm dom0 custom.LockScreen" ``` -4. Ensure that the udev hook is placed in the right place after VM restart. +2. Ensure that the udev hook is placed in the right place after VM restart. Append to `/rw/config/rc.local`: ``` @@ -370,13 +384,13 @@ In your USB VM: udevadm control --reload ``` -5. Then make `/rw/config/rc.local` executable. +3. Then make `/rw/config/rc.local` executable. ``` sudo chmod +x /rw/config/rc.local ``` -6. For changes to take effect, you need to call this script manually for the first time. +4. For changes to take effect, you need to call this script manually for the first time. ``` sudo /rw/config/rc.local diff --git a/user/security-in-qubes/split-gpg.md b/user/security-in-qubes/split-gpg.md index 637b068fd..b81b94edd 100644 --- a/user/security-in-qubes/split-gpg.md +++ b/user/security-in-qubes/split-gpg.md @@ -152,7 +152,7 @@ Note that, because this makes it easier to accept Split GPG's qrexec authorizati ### Thunderbird 78 and higher -Starting with version 78, Thunderbird has a built-in PGP feature and no longer requires the Enigmail extension. For users coming from the Enigmail extension, the built-in functionality is more limited currently, including that **public keys must live in your `work-email` qube with Thunderbird rather than your offline `work-gpg` qube**. +Starting with version 78, Thunderbird has a built-in PGP feature and no longer requires the Enigmail extension. For users coming from the Enigmail extension, the built-in functionality is more limited currently, including that **public keys must live in your** `work-email` **qube with Thunderbird rather than your offline** `work-gpg` **qube**. In `work-email`, use the Thunderbird config editor (found at the bottom of preferences/options), and search for `mail.openpgp.allow_external_gnupg`. Switch the value to true. Still in config editor, search for `mail.openpgp.alternative_gpg_path`. Set its value to `/usr/bin/qubes-gpg-client-wrapper`. Restart Thunderbird after this change. @@ -295,61 +295,61 @@ In this example, the following keys are stored in the following locations (see b | `ssb` | `work-gpg` | | `pub` | `work-email` | -* `sec` (master secret key) +- `sec` (master secret key) - Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys. - This key may be created *without* an expiration date. - This is for two reasons. - First, the master secret key is never to leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below). - Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key (if one is used) or does not. - An adversary who *does* possess the passphrase can simply use it to legally extend the expiration date of the key (or remove it entirely). - An adversary who does *not* possess the passphrase cannot use the key at all. - In either case, an expiration date provides no additional benefit. + * Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys. + This key may be created *without* an expiration date. + This is for two reasons. + First, the master secret key is never to leave the `vault` VM, so it is extremely unlikely ever to be obtained by an adversary (see below). + Second, an adversary who *does* manage to obtain the master secret key either possesses the passphrase to unlock the key (if one is used) or does not. + An adversary who *does* possess the passphrase can simply use it to legally extend the expiration date of the key (or remove it entirely). + An adversary who does *not* possess the passphrase cannot use the key at all. + In either case, an expiration date provides no additional benefit. - By the same token, however, having a passphrase on the key is of little value. - An adversary who is capable of stealing the key from your `vault` would almost certainly also be capable of stealing the passphrase as you enter it. - An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key. - Therefore, using a passphrase at all should be considered optional. - It is, however, recommended that a **revocation certificate** be created and safely stored in multiple locations so that the master keypair can be revoked in the (exceedingly unlikely) event that it is ever compromised. + * By the same token, however, having a passphrase on the key is of little value. + An adversary who is capable of stealing the key from your `vault` would almost certainly also be capable of stealing the passphrase as you enter it. + An adversary who obtains the passphrase can then use it in order to change or remove the passphrase from the key. + Therefore, using a passphrase at all should be considered optional. + It is, however, recommended that a **revocation certificate** be created and safely stored in multiple locations so that the master keypair can be revoked in the (exceedingly unlikely) event that it is ever compromised. -* `ssb` (secret subkey) +- `ssb` (secret subkey) - Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**. - You may also wish to give these subkeys reasonable expiration dates (e.g., one year). - Once these keys expire, it is up to you whether to *renew* these keys by extending the expiration dates or to create *new* subkeys when the existing set expires. + * Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**. + You may also wish to give these subkeys reasonable expiration dates (e.g., one year). + Once these keys expire, it is up to you whether to *renew* these keys by extending the expiration dates or to create *new* subkeys when the existing set expires. - On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey. - If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the `work-gpg` VM being compromised; see below) in order to decrypt *all* of the user's emails. - If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails. + * On the one hand, an adversary who obtains any existing encryption subkey (for example) will be able to use it in order to decrypt all emails (for example) which were encrypted to that subkey. + If the same subkey were to continue to be used--and its expiration date continually extended--only that one key would need to be stolen (e.g., as a result of the `work-gpg` VM being compromised; see below) in order to decrypt *all* of the user's emails. + If, on the other hand, each encryption subkey is used for at most approximately one year, then an adversary who obtains the secret subkey will be capable of decrypting at most approximately one year's worth of emails. - On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them. - This can be problematic, since there is no consensus on how expired signatures should be handled. - Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys. + * On the other hand, creating a new signing subkey each year without renewing (i.e., extending the expiration dates of) existing signing subkeys would mean that all of your old signatures would eventually read as "EXPIRED" whenever someone attempts to verify them. + This can be problematic, since there is no consensus on how expired signatures should be handled. + Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys. -* `pub` (public key) +- `pub` (public key) - This is the complement of the master secret key. - It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others. + * This is the complement of the master secret key. + It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others. -* `vault` +- `vault` - This is a network-isolated VM. - The initial master keypair and subkeys are generated in this VM. - The master secret key *never* leaves this VM under *any* circumstances. - No files or text is *ever* [copied](/doc/how-to-copy-and-move-files/#security) or [pasted](/doc/how-to-copy-and-paste-text/#security) into this VM under *any* circumstances. + * This is a network-isolated VM. + The initial master keypair and subkeys are generated in this VM. + The master secret key *never* leaves this VM under *any* circumstances. + No files or text is *ever* [copied](/doc/how-to-copy-and-move-files/#security) or [pasted](/doc/how-to-copy-and-paste-text/#security) into this VM under *any* circumstances. -* `work-gpg` +- `work-gpg` - This is a network-isolated VM. - This VM is used *only* as the GPG backend for `work-email`. - The secret subkeys (but *not* the master secret key) are [copied](/doc/how-to-copy-and-move-files/#security) from the `vault` VM to this VM. - Files from less trusted VMs are *never* [copied](/doc/how-to-copy-and-move-files/#security) into this VM under *any* circumstances. + * This is a network-isolated VM. + This VM is used *only* as the GPG backend for `work-email`. + The secret subkeys (but *not* the master secret key) are [copied](/doc/how-to-copy-and-move-files/#security) from the `vault` VM to this VM. + Files from less trusted VMs are *never* [copied](/doc/how-to-copy-and-move-files/#security) into this VM under *any* circumstances. -* `work-email` +- `work-email` - This VM has access to the mail server. - It accesses the `work-gpg` VM via the Split GPG protocol. - The public key may be stored in this VM so that it can be attached to emails and for other such purposes. + * This VM has access to the mail server. + It accesses the `work-gpg` VM via the Split GPG protocol. + The public key may be stored in this VM so that it can be attached to emails and for other such purposes. ### Security Benefits diff --git a/user/templates/debian/debian-upgrade.md b/user/templates/debian/debian-upgrade.md index 12552f220..dd626566d 100644 --- a/user/templates/debian/debian-upgrade.md +++ b/user/templates/debian/debian-upgrade.md @@ -189,13 +189,11 @@ instructions](https://www.debian.org/releases/buster/amd64/release-notes/ch-upgr * If sound is not working, you may need to enable the Qubes testing repository to get the testing version of `qubes-gui-agent`. This can be done by editing - the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes - Updates Candidates` repo. + the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes Updates Candidates` repo. * User-initiated updates/upgrades may not run when a template first starts. This is due to a new Debian config setting that attempts to update - automatically; it should be disabled with `sudo systemctl disable - apt-daily.{service,timer}`. + automatically; it should be disabled with `sudo systemctl disable apt-daily.{service,timer}`. Relevant discussions: diff --git a/user/templates/templates.md b/user/templates/templates.md index d12e55850..74d73b9a1 100644 --- a/user/templates/templates.md +++ b/user/templates/templates.md @@ -107,6 +107,7 @@ when you wish to install a fresh template from the Qubes repositories, e.g.: You can use a command line tool - `qvm-template` - or a GUI - `qvm-template-gui`. At the command line in dom0, `qvm-template list --available` will show available templates. To install a template, use: + ``` $ qvm-template install ``` @@ -116,9 +117,11 @@ You can also use `qvm-template` to upgrade or reinstall templates. Repo definitions are stored in `/etc/qubes/repo-templates` and associated keys in `/etc/qubes/repo-templates/keys`. There are additional repos for testing releases and community templates. To temporarily enable any of these repos, use the `--enablerepo=` option. E.g. : + ``` $ qvm-template --enablerepo qubes-templates-community install ``` + To permanently enable a repo, set the line `enabled = 1` in the repo definition in `/etc/qubes/repo-templates`. To permanently disable, set the line to `enabled = 0`. diff --git a/user/templates/windows/migrate-to-4-1.md b/user/templates/windows/migrate-to-4-1.md index d80f65d55..bfa9a3f5b 100644 --- a/user/templates/windows/migrate-to-4-1.md +++ b/user/templates/windows/migrate-to-4-1.md @@ -33,6 +33,7 @@ While this is somewhat straightforward, things get difficult if QWT 4.0.1.3 was ## Preparation for Windows 10 and 11 If there is a drive `D:` from this earlier installation of Qubes Windows Tools, it will probably contain incomplete private data; especially the folder `AppData` containing program configuration data will be missing. In this situation, it may be better to perform a new Windows installation, because repair may be difficult and trouble-prone. + - First, be sure that the automatic repair function is disabled. In a command window, execute `bcdedit /set recoveryenabled NO`, and check that this worked by issuing the command `bcdedit`, without parameters, again. - Now, uninstall QWT 4.0.1.3, using the Apps and Features function of Windows. This will most likely result in a crash. - Restart Windows again, possibly two or three times, until repair options are offered. By hitting the F8 key, select the restart menu, and there select a start in safe mode (in German, it's option number 4). @@ -51,4 +52,7 @@ The PV disk drivers used for migration can be removed after successful installat After successful uninstallation of the PV disk drivers, the disks will appear as QEMU ATA disks. -:warning: **Caution:** This change may lead Windows to declare that the hardware has changed and that in consequence, the activation is no longer valid, possibly complaining that the use of the software is no longer lawful. It should be possible to reactivate the software if a valid product key is provided. + diff --git a/user/templates/windows/qubes-windows-tools-4-0.md b/user/templates/windows/qubes-windows-tools-4-0.md index 830020c74..84470d0d3 100644 --- a/user/templates/windows/qubes-windows-tools-4-0.md +++ b/user/templates/windows/qubes-windows-tools-4-0.md @@ -32,16 +32,16 @@ Below is a breakdown of the feature availability depending on the windows versio | Feature | Windows 7 x64 | Windows 10 x64 | | ------------------------------------ | :------------: | :------------: | -| Qubes Video Driver | + | - | -| Qubes Network Setup | + | + | -| Private Volume Setup (move profiles) | + | + | -| File sender/receiver | + | + | -| Clipboard Copy/Paste | + | + | -| Application shortcuts | + | + | -| Copy/Edit in Disposable VM | + | + | -| Block device | + | + | -| USB device | + | + | -| Audio | - | - | +| Qubes Video Driver | y | n | +| Qubes Network Setup | y | y | +| Private Volume Setup (move profiles) | y | y | +| File sender/receiver | y | y | +| Clipboard Copy/Paste | y | y | +| Application shortcuts | y | y | +| Copy/Edit in Disposable VM | y | y | +| Block device | y | y | +| USB device | y | y | +| Audio | n | n | Qubes Windows Tools are open source and are distributed under a GPL license. @@ -79,9 +79,9 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256 - And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support. + - And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support. - **Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken. + - **Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken. 7. Install Qubes Windows Tools 4.0.1.3 by starting `qubes-tools-4.0.1.3.exe`, not selecting the `Xen PV disk drivers` and the `Move user profiles` (which would probably lead to problems in Windows, anyhow). If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later. @@ -98,7 +98,9 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S 12. Lastly to enable file copy operations to a Windows 10 VM the `default_user` property should be set the `` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `` is the name of your Windows 10 VM)* - `qvm-prefs default_user ` + ``` + qvm-prefs default_user + ``` **Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder @@ -165,6 +167,7 @@ Installing Xen's PV drivers in the VM will lower its resources usage when using 2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers. Notes about using Xen's VBD (storage) PV driver: + - **Windows 7:** installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above). - the option to install the storage PV driver is disabled by default in Qubes Windows Tools - in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar). @@ -317,8 +320,8 @@ To override global settings for a specific component, create a new key under the Component-specific settings currently available: -|**Component**|**Setting**|**Type**|**Description**|**Default value**| -|:------------|:----------|:-------|:--------------|:----------------| +| Component | Setting | Type | Description | Default value | +|:--------------|:------------|:-----------|:------------------------------------------------|:------------------| |qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1| Troubleshooting @@ -332,11 +335,12 @@ If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functi Safe Mode should at least give you access to logs (see above). **Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QWT version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from `c:\Windows`. -Xen logs (/var/log/xen/console/guest-*) are also useful as they contain pvdrivers diagnostic output. +Xen logs (`/var/log/xen/console/guest-*`) are also useful as they contain pvdrivers diagnostic output. If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components: -|| +| Component | Description | +|:-----------|:-----------------------------------------------------------------------------------------------------------------------| |qrexec-agent|Responsible for most communication with Qubes (dom0 and other domains), secure clipboard, file copying, qrexec services.| |qrexec-wrapper|Helper executable that's responsible for launching qrexec services, handling their I/O and vchan communication.| |qrexec-client-vm|Used for communications by the qrexec protocol.| diff --git a/user/templates/windows/qubes-windows-tools-4-1.md b/user/templates/windows/qubes-windows-tools-4-1.md index d02f2dbf7..8bf828416 100644 --- a/user/templates/windows/qubes-windows-tools-4-1.md +++ b/user/templates/windows/qubes-windows-tools-4-1.md @@ -48,20 +48,21 @@ Below is a breakdown of the feature availability depending on the windows versio | Feature | Windows 7 x64 | Windows 8.1/10/11 x64 | | ------------------------------------ | :------------: | :-------------------: | -| Qubes Video Driver | + | - | -| Qubes Network Setup | + | + | -| Private Volume Setup (move profiles) | + | + | -| File sender/receiver | + | + | -| Clipboard Copy/Paste | + | + | -| Application shortcuts | + | + | -| Copy/Edit in Disposable VM | + | + | -| Block device | + | + | -| USB device | + | + | -| Audio | + | + | +| Qubes Video Driver | y | n | +| Qubes Network Setup | y | y | +| Private Volume Setup (move profiles) | y | y | +| File sender/receiver | y | y | +| Clipboard Copy/Paste | y | y | +| Application shortcuts | y | y | +| Copy/Edit in Disposable VM | y | y | +| Block device | y | y | +| USB device | y | y | +| Audio | y | y | Qubes Windows Tools are open source and are distributed under a GPL license. **Notes:** + - Currently only 64-bit versions of Windows 7, 8.1, 10 and 11 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough). - This page documents the process of installing Qubes Windows Tools in version **R4.1**. - *In testing VMs only* it's probably a good idea to install a VNC server before installing QWT. If something goes very wrong with the Qubes gui agent, a VNC server should still allow access to the OS. @@ -79,7 +80,7 @@ In the future this step will not be necessary anymore, because we will sign our The Xen PV Drivers bundled with QWT are signed by a Linux Foundation certificate. Thus Windows 10 and 11 do not require this security mitigation. -**Warning:** it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles and, later on, updating a Windows installation, is performed in an early boot phase when `qrexec` is not yet running, so timeout may occur with the default value. To change the property use this command in `dom0`: *(where `` is the name of your Windows VM)* +**Warning:** it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles and, later on, updating a Windows installation, is performed in an early boot phase when `qrexec` is not yet running, so timeout may occur with the default value. To change the property use this command in `dom0`: *(where* `` *is the name of your Windows VM)* [user@dom0 ~] $ qvm-prefs qrexec_timeout 7200 @@ -137,7 +138,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa 5. After successful installation, the Windows VM must be shut down and started again, possibly a couple of times. On each shutdown, wait until the VM is really stopped, i.e. Qubes shows no more activity. - 6. Qubes will automatically detect that the tools have been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using the `qvm-prefs` command *(where `` is the name of your Windows VM)*: + 6. Qubes will automatically detect that the tools have been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using the `qvm-prefs` command *(where* `` *is the name of your Windows VM)*: [user@dom0 ~] $ qvm-prefs @@ -173,7 +174,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa If Windows is used in a TemplateVM / AppVM combination, this registry fix has to be applied to the TemplateVM, as the `HKLM` registry key belongs to the template-based part of the registry. - 10. Lastly to enable file copy operations to a Windows VM, the `default_user` property of this VM should be set to the `` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `` is the name of your Windows VM)* + 10. Lastly to enable file copy operations to a Windows VM, the `default_user` property of this VM should be set to the `` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where* `` *is the name of your Windows VM)* `[user@dom0 ~] $ qvm-prefs default_user ` @@ -188,6 +189,7 @@ Installing the Qubes Windows Tools on Windows 7, 8.1, 10 and 11 both as a Standa Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Windows VM are usually very stable). They can be installed as an optional part of Qubes Windows Tools (QWT), which bundles Xen's PV drivers. **Notes** about using Xen's VBD (storage) PV driver: + - **Windows 7:** Installing the driver requires a fully updated VM or else you'll likely get a BSOD ("Blue Screen Of Death") and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps or attach block devices. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools. Installing the driver will probably cause Windows 7 activation to become invalid, but the activation can be restored using the Microsoft telephone activation method. - The option to install the storage PV driver is disabled by default in Qubes Windows Tools - In case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver by again starting the QWT installer and selecting the change option. @@ -267,7 +269,7 @@ Windows qubes can be used as disposables, like any other Linux-based qubes. On c - Name the link, e.g. as `Command Prompt`. - Close the Window with `OK`. - Shut down this AppVM. -- In the Qube Manager, refresh the applications of the newly created AppVM and select those applications that you want to make available from the disposable. Alternatively, in dom0 execute the command `qvm-sync-appmenus `, *where `` is the name of your windows qube*. +- In the Qube Manager, refresh the applications of the newly created AppVM and select those applications that you want to make available from the disposable. Alternatively, in dom0 execute the command `qvm-sync-appmenus `, *where* `` *is the name of your windows qube*. - In the Qube Manager, go to the "Advanced" tab and enable the option `Disposable template` for your Windows qube. Alternatively, in dom0 execute the commands `qvm-prefs template_for_dispvms True` and `qvm-features appmenus-dispvm 1`. - Click `Apply`. - Still in the Advanced tab, select your Windows qube as its own `Default disposable template`. Alternatively, in dom0 execute the command `qvm-prefs default_dispvm `. @@ -277,7 +279,7 @@ Now you should have a menu `Disposable: ` containing the applications th For further information on usage of disposables, see [How to use disposables](/doc/how-to-use-disposables/). -**Caution:** *If a Windows-based disposable is used from another qube via the `Open/Edit in DisposableVM` command, this disposable may not close automatically, due to the command prompt window still running in this dispvm. In this case, the disposable has to be shut down manually.* +**Caution:** *If a Windows-based disposable is used from another qube via the* `Open/Edit in DisposableVM` *command, this disposable may not close automatically, due to the command prompt window still running in this dispvm. In this case, the disposable has to be shut down manually.* ## Installation logs @@ -311,8 +313,8 @@ To override global settings for a specific component, create a new key under the Component-specific settings currently available: -|**Component**|**Setting**|**Type**|**Description**|**Default value**| -|:------------|:----------|:-------|:--------------|:----------------| +| Component | Setting | Type | Description | Default value | +|:--------------|:------------|:-----------|:------------------------------------------------|:------------------| |qga|DisableCursor|DWORD|Disable cursor in the VM. Useful for integration with Qubes desktop so you don't see two cursors. Can be disabled if you plan to use the VM through a remote desktop connection of some sort. Needs gui agent restart to apply change (locking OS/logoff should be enough since qga is restarted on desktop change).|1| ## Troubleshooting diff --git a/user/templates/windows/windows-qubes-4-0.md b/user/templates/windows/windows-qubes-4-0.md index e1844e18b..919655ff2 100644 --- a/user/templates/windows/windows-qubes-4-0.md +++ b/user/templates/windows/windows-qubes-4-0.md @@ -16,11 +16,13 @@ title: How to install Windows qubes in Qubes OS 4.0 If you just want something simple and you can live without some features. Works: + - display (1440x900 or 1280x1024 are a nice fit onto FHD hw display) - keyboard (incl. correct mapping), pointing device - network (emulated Realtek NIC) Does not work: + - copy & paste (the qubes way) - copying files into / out of the VM (the qubes way) - assigning USB devices (the qubes way via the tray applet) @@ -29,6 +31,7 @@ Does not work: - all other features/hardware needing special tool/driver support Installation procedure: + - Have the Windows 10 ISO image (I used the 64-bit version) downloaded in some qube. - Create a new Qube: - Name: Win10, Color: red @@ -219,6 +222,7 @@ At that point you should have a functional and stable Windows VM, although witho ## Windows as a template Windows 7 and 10 can be installed as TemplateVM by selecting + ~~~ qvm-create --class TemplateVM --property virt_mode=HVM --property kernel='' --label black Windows-template ~~~ @@ -231,6 +235,7 @@ when creating the VM. To have the user data stored in AppVMs depending on this t For Windows 10, configuration data like those stored in directories like `AppData` still remain in the TemplateVM, such that their changes are lost each time the AppVM shuts down. In order to make permanent changes to these configuration data, they have to be changed in the TemplateVM, meaning that applications have to be started there, which violates and perhaps even endangers the security of the TemplateVM. Such changes should be done only if absolutely necessary and with great care. It is a good idea to test them first in a cloned TemplateVM before applying them in the production VM. AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying + ~~~ qvm-create --class=AppVM --template= ~~~ diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md index 4d38a4bbe..bfd3a10f6 100644 --- a/user/templates/windows/windows-qubes-4-1.md +++ b/user/templates/windows/windows-qubes-4-1.md @@ -46,6 +46,7 @@ For better integration, a set of drivers and services, called Qubes Windows Tool However, if you are an expert or want to do it manually you may continue below. **Notes:** + - The instructions may work on other versions than Windows 7, 8.1, 10 and 11 x64 but haven't been tested. - Qubes Windows Tools (QWT) only supports Windows 7, 8.1, 10 and 11 x64. For installation, see [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1). @@ -61,46 +62,49 @@ Unofficial “debloated” ISOs from projects like reviOS 18 or ameliorated 10 c Create a VM named WindowsNew in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH). This can be done in either of two ways: -- Using Qube Manager - - In order to create the new qube, select the command Qube -> New Qube in the Qube Manager:: - - Name: `WindowsNew`, Color: `orange` (for a standalone qubes, `black` for a template) - - Type: `StandaloneVM (fully persistent)` or `TemplateVM (template home, persistent root)` - - Template: `(none)` - - Networking: `sys-firewall (default)` - - Launch settings after creation: check - - Click "OK". - - - Settings: - - Basic: - - System storage: 60.0+ GB - - Advanced: - - Include in memory balancing: uncheck - - Initial memory: 4096+ MB - - Kernel: `(none)` - - Mode: `HVM` - - Click "Apply". +- Using Qube Manager: In order to create the new qube, select the command Qube -> New Qube in the Qube Manager: + + - Name: `WindowsNew`, Color: `orange` (for a standalone qubes, `black` for a template) + - Type: `StandaloneVM (fully persistent)` or `TemplateVM (template home, persistent root)` + - Template: `(none)` + - Networking: `sys-firewall (default)` + - Launch settings after creation: check + - Click "OK". + - Settings: + - Basic: + - System storage: 60.0+ GB + - Advanced: + - Include in memory balancing: uncheck + - Initial memory: 4096+ MB + - Kernel: `(none)` + - Mode: `HVM` + - Click "Apply". After creation, set `qvm-prefs WindowsNew qrexec_timeout 7200` via CLI in a dom0 terminal. - Using CLI in a dom0 terminal - This can also be done via the following CLI commands in dom0, for a standalone qube: - ~~~ - qvm-create --class StandaloneVM --label orange --property virt_mode=hvm WindowsNew - ~~~ - and for a template: - ~~~ - qvm-create --class TemplateVM --label black --property virt_mode=hvm WindowsNew - ~~~ + + ~~~ + qvm-create --class StandaloneVM --label orange --property virt_mode=hvm WindowsNew + ~~~ + + and for a template: + + ~~~ + qvm-create --class TemplateVM --label black --property virt_mode=hvm WindowsNew + ~~~ + - After creation, set the following parameters via CLI in a dom0 terminal: - ~~~ - qvm-volume extend WindowsNew:root 60g - qvm-prefs WindowsNew memory 4096 - qvm-prefs WindowsNew maxmem 4096 - qvm-prefs WindowsNew kernel '' - qvm-prefs WindowsNew qrexec_timeout 7200 - ~~~ + + ~~~ + qvm-volume extend WindowsNew:root 60g + qvm-prefs WindowsNew memory 4096 + qvm-prefs WindowsNew maxmem 4096 + qvm-prefs WindowsNew kernel '' + qvm-prefs WindowsNew qrexec_timeout 7200 + ~~~ These parameters are set for the following reasons: @@ -109,13 +113,14 @@ These parameters are set for the following reasons: - Setting memory to 4096MB may work in most cases, but using 6144MB (or even 8192MB) may reduce the likelihood of crashes during installation, especially for Windows 10 or 11. This is important as Windows qubes have to be created without memory balancing, as requested by the parameter settings described above. - The Windows' installer requires a significant amount of memory or else the VM will crash with such errors: - ~~~ - /var/log/xen/console/hypervisor.log: + ~~~ + /var/log/xen/console/hypervisor.log: - p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120) - (XEN) domain_crash called from p2m-pod.c:1218 - (XEN) Domain 120 (vcpu#0) crashed on cpu#3: - ~~~ + p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120) + (XEN) domain_crash called from p2m-pod.c:1218 + (XEN) Domain 120 (vcpu#0) crashed on cpu#3: + ~~~ + So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing), or 6144MB / 8192MB, as recommended above. - Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence. This is done by setting the qube's kernel to an empty value. @@ -135,6 +140,7 @@ These parameters are set for the following reasons: - Click "OK" to boot into the windows installer. This can also be done via the following CLI command in dom0 (assuming that the Windows installer ISO is stored in the directory `/home/user/` in the AppVM `untrusted`): + ~~~ qvm-start --cdrom=untrusted:/home/user/windows_install.iso WindowsNew ~~~ @@ -154,10 +160,14 @@ These parameters are set for the following reasons: - Position to this key and create 3 DWORD values called `BypassTPMCheck`, `BypassSecureBootCheck` and `BypassRAMCheck` and set each value to `1`. - Close the registry editor and console windows. - In the setup window, hit the left arrow in the left upper corner. You will then return into the setup, which will continue normally and install Windows 11 without TPM 2.0. - - :warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft some time. + + + - The installation of Windows 11 may require an internet connection to grab a Microsoft ID. This is currently true only for the home addition, but will probably extend to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that currently works for version 21H2 but may be blocked some time in the future by Microsoft: + - The installation of Windows 11 may require an internet connection to grab a Microsoft ID. This is currently true only for the home addition, but will probably extend to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that currently works for version 21H2 but may be blocked some time in the future by Microsoft: - When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window. - Here you type `taskmgr` to start the Task Manager window so you can see all running processes. @@ -165,7 +175,7 @@ These parameters are set for the following reasons: - Select this process and then hit the “End Task” button. - Now you can close these newly opened windows and return to the Windows 11 setup, where you will enter local account information. - For Windows 11 version 22H2, the following sequence of actions to use a local account instead of a Microsoft account has been published: + - For Windows 11 version 22H2, the following sequence of actions to use a local account instead of a Microsoft account has been published: - Enter `no@thankyou.com` (or some other senseless address) as the email address and click `Next` when Windows 11 setup prompts you to log into your Microsoft account. - Enter any text you want in the password field and click `Sign in`. If this method works, you'll get a message saying "Oops, something went wrong." @@ -175,8 +185,10 @@ These parameters are set for the following reasons: - On systems shipped with a Windows license, the product key may be read from flash via root in dom0: + `strings < /sys/firmware/acpi/tables/MSDM` + Alternatively, you can also try a Windows 7 license key (as of 2018/11 they are still accepted for a free upgrade to Windows 10). - The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone WindowsNew WindowsNewbkp1`). Then, (re)start the VM via the Qubes Manager or with `qvm-start WindowsNew` from a dom0 terminal (without the `--cdrom` parameter!). @@ -186,9 +198,11 @@ These parameters are set for the following reasons: **After Windows installation** - From the Windows command line, disable hibernation in order to avoid incomplete Windows shutdown, which could lead to corruption of the VM's disk. + ~~~ powercfg -H off ~~~ + Also, recent versions of Windows won’t show the CD-ROM drive after starting the qube with `qvm-start vm --cdrom ...` (or using the GUI). The solution is to disable hibernation in Windows with this command. (That command is included in QWT’s setup but it’s necessary to run it manually in order to be able to open QWT’s setup ISO/CD-ROM in Windows). - In case you switch from `sys-firewall` to `sys-whonix`, you'll need a static IP network configuration, DHCP won't work for `sys-whonix`. Sometimes this may also happen if you keep using `sys-firewall`. In both cases, proceed as follows: @@ -202,6 +216,7 @@ These parameters are set for the following reasons: - Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'WindowsNew'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM. + At this point you may open a tab in dom0 for debugging, in case something goes amiss: ~~~ @@ -234,6 +249,7 @@ For additional information on configuring a Windows qube, see the [Customizing W As described above Windows 7, 8.1, 10 and 11 can be installed as TemplateVM. To have the user data stored in AppVMs depending on this template, the option `Move User Profiles` has to be selected on installation of Qubes Windows Tools. For Windows 7, before installing QWT, the private disk `D:` has to be renamed to `Q:`, see the QWT installation documentation in [Qubes Windows Tools](/doc/templates/windows/qubes-windows-tools-4-1). AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying + ~~~ qvm-create --class=AppVM --template= ~~~ @@ -243,6 +259,7 @@ On starting the AppVM, sometimes a message is displayed that the Xen PV Network **Caution:** These AppVMs must not be started while the corresponding TemplateVM is running, because they share the TemplateVM's license data. Even if this could work sometimes, it would be a violation of the license terms. Furthermore, if manual IP setup was used for the template, the IP address selected for the template will also be used for the AppVM, as it inherits this address from the template. Qubes, however, will have assigned a different address to the AppVM, which will have to changed to that of the template (e.g. 10.137.0.x) so that the AppVM can access the network, vis the CLI command in a dom0 terminal: + ~~~ qvm-prefs WindowsNew ip 10.137.0.x ~~~ diff --git a/user/troubleshooting/installation-troubleshooting.md b/user/troubleshooting/installation-troubleshooting.md index 2a0c19360..6e2eae8b9 100644 --- a/user/troubleshooting/installation-troubleshooting.md +++ b/user/troubleshooting/installation-troubleshooting.md @@ -61,19 +61,20 @@ If that doesn't help, then disable one and try the other. Visit the [UEFI Troubleshooting guide](/doc/uefi-troubleshooting/) if other errors arise during UEFI booting. These errors may also occur due to an incompatible Nvidia graphics card. If you have one, follow the following instructions: + 1. Disable secure/fast boot and use legacy mode 2. Enter GRUB, move the selection to the first choice, and then press the Tab key. 3. Now, you are in edit mode. Move the text cursor with your arrow key and after ``kernel=`` line, add: - ``` - nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off - ``` + ```bash + nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off + ``` - If the above code doesn't fix the problem, replace it with: + If the above code doesn't fix the problem, replace it with: - ``` - noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img - ``` + ```bash + noexitboot=1 modprobe.blacklist=nouveau rd.driver.blacklist=nouveau --- intitrd.img + ``` For more information, look at the [Nvidia Troubleshooting guide](https://forum.qubes-os.org/t/19021#disabling-nouveau). diff --git a/user/troubleshooting/uefi-troubleshooting.md b/user/troubleshooting/uefi-troubleshooting.md index 35e33877f..890fa091e 100644 --- a/user/troubleshooting/uefi-troubleshooting.md +++ b/user/troubleshooting/uefi-troubleshooting.md @@ -23,6 +23,7 @@ If you've installed successfully in legacy mode but had to change some kernel pa 04. Install using your modified boot entry **Change xen configuration directly in an iso image** + 01. Set up a loop device (replacing `X` with your ISO's version name): `losetup -P /dev/loop0 Qubes-RX-x86_64.iso` 02. Mount the loop device: `sudo mount /dev/loop0p2 /mnt` 03. Edit `EFI/BOOT/BOOTX64.cfg` to add your params to the `kernel` configuration key diff --git a/user/troubleshooting/update-troubleshooting.md b/user/troubleshooting/update-troubleshooting.md index 5cbcf0815..60cc2feca 100644 --- a/user/troubleshooting/update-troubleshooting.md +++ b/user/troubleshooting/update-troubleshooting.md @@ -43,5 +43,6 @@ This can usually be fixed by updating via the command line. In dom0, open a terminal and run `sudo qubes-dom0-update`. Depending on your operating system, open a terminal in the templates and run: + * Fedora: `sudo dnf upgrade` * Debian: `apt-get update && apt-get dist-upgrade`