From dc0819594baa7b2e4ecb28672495e49ba975cb04 Mon Sep 17 00:00:00 2001 From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com> Date: Thu, 1 Sep 2022 07:32:52 +0200 Subject: [PATCH 01/20] Use sentence case instead of title case As required by the style guide --- user/how-to-guides/how-to-use-usb-devices.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index e515231f..c3db0601 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -28,9 +28,9 @@ Examples of valid cases for USB-passthrough: (If you are thinking to use a two-factor-authentication device, [there is an app for that](/doc/u2f-proxy/). But it has some [issues](https://github.com/QubesOS/qubes-issues/issues/4661).) -## Attaching And Detaching a USB Device +## Attaching and detaching a USB device -### With Qubes Device Manager +### With Qubes device manager Click the device-manager-icon: ![device manager icon](/attachment/doc/media-removable.png) A list of available devices appears. @@ -48,7 +48,7 @@ Hover on the attached device to display a list of running VMs. The one to which your device is connected will have an eject button ![eject icon](/attachment/doc/media-eject.png) next to it. Click that and your device will be detached. -### With The Command Line Tool +### With the command line tool In dom0, you can use `qvm-usb` from the commandline to attach and detach devices. @@ -87,14 +87,14 @@ sys-usb:2-5 058f:3822 058f_USB_2.0_Camera sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse ``` -## Maintenance And Customisation +## Maintenance and customisation -### Creating And Using a USB qube +### Creating and using a USB qube If you've selected to install a usb-qube during system installation, everything is already set up for you in `sys-usb`. If you've later decided to create a usb-qube, please follow [this guide](/doc/usb-qubes/). -### Installation Of `qubes-usb-proxy` +### Installation of `qubes-usb-proxy` To use this feature, the `qubes-usb-proxy` package needs to be installed in the templates used for the USB qube and qubes you want to connect USB devices to. This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. @@ -111,13 +111,13 @@ If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you sudo apt-get install qubes-usb-proxy ``` -### Using USB Keyboards And Other Input Devices +### Using USB keyboards and other input devices **Warning:** especially keyboards need to be accepted by default when using them to login! Please make sure you carefully read and understood the **[security considerations](/doc/device-handling-security/#usb-security)** before continuing! Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/). -### Finding The Right USB Controller +### Finding the right USB controller Some USB devices are not compatible with the USB pass-through method Qubes employs. In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. From 2b24640962d12880aa91c93a478d0b71d4553444 Mon Sep 17 00:00:00 2001 From: qubesbugreport <112062467+qubesbugreport@users.noreply.github.com> Date: Thu, 1 Sep 2022 08:00:33 +0200 Subject: [PATCH 02/20] Add instructions for using Qube Manager Using the Qube Manager to determine USB controller and address --- user/how-to-guides/how-to-use-usb-devices.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index c3db0601..f845f89e 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -123,6 +123,10 @@ Some USB devices are not compatible with the USB pass-through method Qubes emplo In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it. +You can find your controller and its BDF address using either of two methods described below. Using the command-line tools lsusb and readlink or by using the Qube Manager GUI. It is possible that on some system configurations the readlink method produces output which is different from the example below, while the Qube Manager method allows one to easily determine the correct controller and BDF address. + +#### Method 1: Using lsusb and readlink + If you have multiple USB controllers, you must first figure out which PCI device is the right controller. First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube): @@ -155,6 +159,8 @@ This should output something like: ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 ``` +If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead. + Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM. For example, On R 4.0 the command would look something like @@ -162,3 +168,17 @@ For example, On R 4.0 the command would look something like ``` qvm-pci attach --persistent personal dom0:00_1a.0 ``` + +#### Method 2: Using the Qube Manager + +Open the Qube Manager, then right click on one of the VMs and open the settings. Go to the tab "Devices". + +Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller". + +They should look something like: `01:00.0 USB controller: Name of manufacturer` + +The first part is the BDF address, in this example: `01:00.0` + +If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation" while the added controller shows another name of manufacturer. + +Now you should be able to tell which is the correct BDF address of the mainboard USB controller or the added USB controller. From c5314bed7f3001996c10458145cc5ba4a0ebaad8 Mon Sep 17 00:00:00 2001 From: zenkuro <42751749+zenkuro@users.noreply.github.com> Date: Thu, 5 Jan 2023 22:57:18 -0500 Subject: [PATCH 03/20] Eetend VPN troubleshooting by notify-send case There are guides and scripts on internet that are helping to configure and run VPN service on QubesOS This record provides explanation how to identify and what to do to fix possible issues with notify-send that being used by this guides. --- user/troubleshooting/vpn-troubleshooting.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md index d63bbe0c..d06eb5d1 100644 --- a/user/troubleshooting/vpn-troubleshooting.md +++ b/user/troubleshooting/vpn-troubleshooting.md @@ -31,3 +31,20 @@ After suspend/resume, OpenVPN may not automatically reconnect. In order to get i After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected. To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing OpenVPN libraries, which you can then install. + +## `notify-send` induced failure +[Some VPN guides](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md) use complex scripts that by themselves include call of `notify-send`, yet some images may not contain this tool or may not have it working properly. +For instance calling `notify-send` on `fedora-36` template VM gives: +``` +Failed to execute child process “dbus-launch” (No such file or directory) +``` + +To check this tool is working properly run: +```bash +sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle +``` +You should see `info` message appear on the top of your scree. +If that is the case then, `notify-send` is not the issue. +If it is not, and you have an error of some sort you can: +1. Remove all calls of `notify-send` from scripts you are using to start VPN +2. Use other template VM that have `notify-send` working or find proper guide and make your current template VM run `notify-send` work properly. From a65a507db57fc5166163f05c4f1244edcd5bf3fa Mon Sep 17 00:00:00 2001 From: zenkuro <42751749+zenkuro@users.noreply.github.com> Date: Sat, 7 Jan 2023 02:47:34 -0500 Subject: [PATCH 04/20] Update vpn-troubleshooting.md Fix typo --- user/troubleshooting/vpn-troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md index d06eb5d1..4671066c 100644 --- a/user/troubleshooting/vpn-troubleshooting.md +++ b/user/troubleshooting/vpn-troubleshooting.md @@ -43,7 +43,7 @@ To check this tool is working properly run: ```bash sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle ``` -You should see `info` message appear on the top of your scree. +You should see `info` message appear on the top of your screen. If that is the case then, `notify-send` is not the issue. If it is not, and you have an error of some sort you can: 1. Remove all calls of `notify-send` from scripts you are using to start VPN From 108fb1e106a65e0d5c0a7f13913be8fd288a62d0 Mon Sep 17 00:00:00 2001 From: chomiczosc <155738605+chomiczosc@users.noreply.github.com> Date: Fri, 5 Jan 2024 15:26:36 +0100 Subject: [PATCH 05/20] Update getting-started.md - simplifying "Getting started section" to make it more comprehensible - updating the section to match Qubes 4.2 --- introduction/getting-started.md | 135 +++++++++++++++----------------- 1 file changed, 64 insertions(+), 71 deletions(-) diff --git a/introduction/getting-started.md b/introduction/getting-started.md index 1ac922d5..92409e27 100644 --- a/introduction/getting-started.md +++ b/introduction/getting-started.md @@ -18,14 +18,13 @@ Dive right in to [organizing your qubes](/doc/how-to-organize-your-qubes/).) ## The Basics -Qubes OS is an operating system built out of securely-isolated compartments -called [qubes](/doc/glossary/#qube). For example, you might have a work qube, a -personal qube, a banking qube, a web browsing qube, and so on. You can have as -many qubes as you want! Most of the time, you'll be using an [app -qube](/doc/glossary/#app-qube), which is a qube intended for running software +Qubes OS is an operating system built out of securely-isolated compartments, or [qubes](/doc/glossary/#qube). +You can have a work qube, a personal qube, a banking qube, a web browsing qube, a standalone Windows qube and so on. +You can have as many qubes as you want! Most of the time, you'll be using an [app +qube](/doc/glossary/#app-qube), a qube for running software programs like web browsers, email clients, and word processors. Each app qube is based on another type of qube called a [template](/doc/glossary/#template). -More than one qube can be based on the same template. Importantly, a qube +The same template can be a base for various cubes. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is @@ -35,9 +34,8 @@ Suppose you want to use your favorite web browser in several different qubes. You'd install the web browser in a template, then every qube based on that template would be able to run the web browser software (while still being forbidden from modifying the template and any other qubes). This way, you only -have to install the web browser a single time, and updating the template serves -to update all the qubes based on it. This elegant design saves time and space -while enhancing security. +have to install the web browser a single time, and updating the template updates all the qubes based on it. +This elegant design saves time and space while enhancing security. There are also some "helper" qubes in your system. Each qube that connects to the Internet does so through a network-providing [service @@ -54,27 +52,24 @@ corresponding version number. There are many ready-to-use many as you like. Last but not least, there's a very special [admin -qube](/doc/glossary/#admin-qube) which, as the name suggests, is used to -administer your entire system. There's only one admin qube, and it's called -[dom0](/doc/glossary/#dom0). You can think of it as the master qube, holding -ultimate power over everything that happens in Qubes OS. Dom0 is more trusted -than any other qube. If dom0 were ever compromised, it would be "game over." -The entire system would effectively be compromised. That's why everything in -Qubes OS is specifically designed to protect dom0 and ensure that doesn't +qube](/doc/glossary/#admin-qube) used to administer your entire system. +There's only one admin qube, and it's called [dom0](/doc/glossary/#dom0). +You can think of it as the master qube, holding ultimate power over everything that happens in Qubes OS. +Dom0 is the most trusted one of all qubes. If dom0 were ever to be compromised, it would be "game over"- an effective compromise of the entire system. +That's why everything in Qubes OS is specifically designed to protect dom0 and ensure that doesn't happen. Due to its overarching importance, dom0 has no network connectivity and is used only for running the [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be used for anything else. In particular, you should never run user applications -in dom0. (That's what your app qubes are for!) +in dom0. (That's what your app qubes are for!) In short, do not interact directly with dom0 in any way, shape or form. ### Color & Security You'll choose a **color** for each of your qubes out of a predefined set of -colors. Each window on your desktop will have its frame colored according to -the color of that qube. These colored frames help you keep track of which qube -each window belongs to and how trustworthy it is. This is especially helpful -when you have the same app running in multiple qubes at the same time. For +colors. The color of the frame of each window on your desktop will correspond to the color of that cube. +These colored frames help you keep track of which qube you're currently using and how trustworthy it is. This is especially helpful +when you have the same program running in multiple qubes at the same time. For example, if you're logged in to your bank account in one qube while doing some random web surfing in a different qube, you wouldn't want to accidentally enter your banking password in the latter! The colored frames help to avoid such @@ -83,16 +78,16 @@ mistakes. [![snapshot_40.png](/attachment/doc/r4.0-snapshot_40.png)](/attachment/doc/r4.0-snapshot_40.png) Most Qubes users associate red with what's untrusted and dangerous (like a red -light: stop! danger!), green with what's safe and trusted, and yellow and -orange with things in the middle. This color scheme also extends to include -blue and black, which are usually interpreted as indicating progressively more -trusted domains than green, with black being ultimately trusted. Color and -associated meanings are ultimately up to you, however. The system itself does -not treat the colors differently. If you create two identical qubes --- black +stop light signalling danger), green with what's safe and trusted, and yellow and +orange with things in-between. This color scheme also includes +blue and black, commonly interpreted as indicating progressively more +trusted domains than green, with black being ultimately trusted. However, color and +associated meanings are entirely up to you. The system itself does +not treat the colors differently - they're all equally safe on their own. If you create two identical qubes --- black and red, say --- they'll be the same until you start using them differently. -Feel free to use the colors in whatever way is most useful to you. For example, +Feel free to use the colors in the way that best meets your needs. For example, you might decide to use three or four qubes for work activities and give them -all the same color --- or all different colors. It's entirely up to you. +all the same color --- or all different colors depending on the nature of the task they are used for. ### User Interface @@ -104,27 +99,24 @@ the window managers [i3](/doc/i3/) and [AwesomeWM](/doc/awesomewm/). [![r4.0-taskbar.png](/attachment/doc/r4.0-taskbar.png)](/attachment/doc/r4.0-taskbar.png) -The bar at the top of your screen in Qubes 4.0 includes the following XFCE +The bar at the top of your screen in Qubes 4.2 includes the following XFCE component areas: -- The **Tray**, where many functional widgets live. +- The **App Menu**, where you go to open an application within a qube, to open + a dom0 terminal, to access administrative UI tools such as the Qube Manager, + or to access settings panels for your desktop environment. +- The **Task Bar** where buttons for open and hidden windows live. - **Spaces**, an interface for [virtual desktops](https://en.wikipedia.org/wiki/Virtual_desktop). Virtual desktops do not have any inherent security isolation properties, but some users find them useful for organizing things. -- The **Task Bar** where buttons for open and hidden windows live. -- The **App Menu**, where you go to open an application within a qube, to open - a dom0 terminal, to access administrative UI tools such as the Qube Manager, - or to access settings panels for your desktop environment. - -To learn more about how to customize your desktop environment, we recommend you -spend some time going through [XFCE's documentation](https://docs.xfce.org/). +- The **Tray**, where many functional widgets live. There are several tray widgets that are unique to Qubes OS: - The **Whonix SDWDate** allows you to control the Tor connection in your [`sys-whonix`](https://www.whonix.org/wiki/Qubes) qube. -- The **Qubes Clipboard** lets you easily copy text from dom0. +- The **Qubes Clipboard** lets you easily [copy text](https://wwwpreview.qubes-os.org/doc/how-to-copy-and-paste-text/) between various qubes and from dom0. - The **Qubes Devices** widget allows you to attach and detach devices --- such as USB drives and cameras --- to qubes. - The **Qubes Disk Space** widget shows you how much storage you're using. @@ -136,50 +128,57 @@ There are several tray widgets that are unique to Qubes OS: [![r4.1-widgets.png](/attachment/doc/r4.1-widgets.png)](/attachment/doc/r4.1-widgets.png) +To learn more about how to customize your desktop environment, we recommend you +go through [XFCE's documentation](https://docs.xfce.org/). + #### Qube Manager -To see all of your qubes at the same time, you can use the **Qube Manager** (go -to the App Menu → Qubes Tools → Qube Manager), which displays the states of -all the qubes in your system, even the ones that aren't running. +To see all of your qubes at the same time, you can use the **Qube Manager**. +It displays the states of all the qubes in your system, even the ones that aren’t running. + +To access Qube Manager go to: +Qubes Icon (App Menu) → Settings Icon → Qubes Tools → **Qube Manager** [![r4.0-qubes-manager.png](/attachment/doc/r4.0-qubes-manager.png)](/attachment/doc/r4.0-qubes-manager.png) #### Command-line interface -All aspects of Qubes OS can be controlled using command-line tools. Opening a -terminal emulator in dom0 can be done in several ways: +All aspects of Qubes OS can be controlled using command-line tools such as the terminal emulator. +The default terminal emulator in Qubes is Xfce Terminal. +Opening a terminal emulator in dom0 can be done in several ways: -- Go to the App Menu and select **Terminal Emulator** at the top. +- Go to the App Menu, click on the Settings icon, choose Other from the drop-down menu, and select **Xfce Terminal Emulator** at the bottom. - 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 -command-line tools are described as part of this guide, and the whole reference -can be found [here](/doc/tools/). +Various command-line tools are described as part of this guide, and the whole reference can be found [here](/doc/tools/). +Terminal emulators can also be run in other qubes as normal programs. ## First boot When you install Qubes OS, a number of qubes are pre-configured for you: -- **Templates:** `fedora-XX` (`XX` being the version number) +- **App qubes** such as `work`, `personal`, `untrusted`, and `vault` are your "starter pack" qubes to compartmentalize tasks + and types of data to suit most basic needs. (There is nothing special about these pre-configured qubes - they are identical in nature to more specific ones you might wish to create later.) +- **Templates:** `fedora-XX`, `debian-XX` (`XX` being the version number) +- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix`) - **Admin qube:** `dom0` -- **Service qubes:** `sys-usb`, `sys-net`, `sys-firewall`, and `sys-whonix` -- **App qubes** configured to prioritize security by compartmentalizing tasks - and types of data: `work`, `personal`, `untrusted`, and `vault`. (There is - nothing special about these qubes. If you were to create a black qube and - name it `vault`, it would be the same as the pre-configured `vault` qube. - They're just suggestions to get you started. ) -A variety of open-source applications such as file managers, command-line -terminals, printer managers, text editors, and "applets" used to configure -different things like audio or parts of the user interface are also installed -by default—most within the templates. Most are bundled with each template. +Other software installed in Qubes OS by default includes open-source applications such as file managers, +command-line terminals, printer managers, text editors, and applets for configuring audio and user interface settings. +Most of these applications are incorporated within each template. ### Adding, removing, and listing qubes -You can easily create a new qube with the **Create Qubes VM** option in the App -Menu. If you need to add or remove qubes, simply use the Qube Manager's **Add** -and **Remove** buttons. You can also add, remove, and list qubes from the +To create a new qube or remove one, use **Create Qubes VM** option in the App Menu. + +Creating a New Qube: +Qubes Icon → Settings → Qubes Tools → Qube Manager → Create Qubes VM → **New Qube** + +Removing a qube: +To remove a qube, use the **Delete qube button** as the final step instead. + +You can also add, remove, and list qubes from the command line using the following tools: - `qvm-create` @@ -188,14 +187,8 @@ command line using the following tools: ### How many qubes do I need? -That's a great question, but there's no one-size-fits-all answer. It depends on -the structure of your digital life, and this is at least a little different for -everyone. If you plan on using your system for work, then it also depends on -what kind of job you do. - -It's a good idea to start out with the qubes created automatically by the -installer: `work`, `personal`, `untrusted`, and `vault`. If and when you start -to feel that some activity just doesn't fit into any of your existing qubes, or +It's a good idea to start out with the pre-installed app qubes: `work`, `personal`, `untrusted`, and `vault`. +If you start to feel that some activity just doesn't fit into any of your existing qubes, or you want to partition some part of your life, you can easily create a new qube for it. You'll also be able to easily [copy any files](/doc/how-to-copy-and-move-files) you need to the newly-created qube. @@ -252,5 +245,5 @@ GitHub](https://github.com/QubesOS). ## Documentation -Peruse our extensive library of [documentation](/doc/) for users and developers +Browse our extensive library of [documentation](/doc/) for users and developers of Qubes OS. You can even [help us improve it](/doc/how-to-edit-the-documentation/)! From 4a9ab9fac587590027d8330dcc25e6a825d93182 Mon Sep 17 00:00:00 2001 From: chomiczosc <155738605+chomiczosc@users.noreply.github.com> Date: Fri, 5 Jan 2024 15:45:08 +0100 Subject: [PATCH 06/20] Update getting-started.md Fixes from review --- introduction/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/introduction/getting-started.md b/introduction/getting-started.md index 92409e27..4a02083c 100644 --- a/introduction/getting-started.md +++ b/introduction/getting-started.md @@ -24,7 +24,7 @@ You can have as many qubes as you want! Most of the time, you'll be using an [ap qube](/doc/glossary/#app-qube), a qube for running software programs like web browsers, email clients, and word processors. Each app qube is based on another type of qube called a [template](/doc/glossary/#template). -The same template can be a base for various cubes. Importantly, a qube +The same template can be a base for various qubes. Importantly, a qube cannot modify its template in any way. This means that, if a qube is ever compromised, its template and any other qubes based on that template will remain safe. This is what makes Qubes OS so secure. Even if an attack is @@ -62,7 +62,7 @@ is used only for running the [desktop environment](https://en.wikipedia.org/wiki/Desktop_environment) and [window manager](https://en.wikipedia.org/wiki/Window_manager). Dom0 should never be used for anything else. In particular, you should never run user applications -in dom0. (That's what your app qubes are for!) In short, do not interact directly with dom0 in any way, shape or form. +in dom0. (That's what your app qubes are for!) In short, be very careful when interacting with dom0. ### Color & Security From 9218f2316760612376313fc7a126b13ded1e6fc4 Mon Sep 17 00:00:00 2001 From: "Dr. Gerhard Weck" Date: Sun, 25 Aug 2024 10:12:11 +0200 Subject: [PATCH 07/20] Describe Move user profiles without QWT installation --- user/templates/windows/windows-qubes-4-1.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md index 4d38a4bb..62210c0a 100644 --- a/user/templates/windows/windows-qubes-4-1.md +++ b/user/templates/windows/windows-qubes-4-1.md @@ -231,7 +231,16 @@ For additional information on configuring a Windows qube, see the [Customizing W ## Windows as a template -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). +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 user data have to be stored on a private disk named `Q:`. If there is already a disk for user data, possibly called `D:`, it has to be renamed to `Q:`. Otherwise, this disk has to be created via the Windows `diskpart` utility, or the Disk Management administrative function by formatting the qube's private volume and associating the letter `Q:` with it. The volume name is of no importance. + +Moving the user data is not directly possible under Windows, because the directory `C:\Users` is permanently open and thus locked. Qubes Windows Tools provides a function to move these data on Windows reboot when the directory is not yet locked. To use this function, a working version of QWT has to be used (see the documentation on QWT installation). For Qubes R4.2, this is currently the version 4.1.69. There are two possibilities to move the user data to this volume `Q:`. + +- If Qubes Windows Tools is installed, the option `Move User Profiles` has to be selected on the installation. In this case, the user files are moved to the new disk during the reboot at the end of the installation. + +- This can also be accomplished without QWT installation, avoiding the installation of the Xen PV drivers, if the risk of a compromised version of these drivers according to QSB-091 is considered too severe. In this case, the file `relocate_dir.exe` has to be extracted from the QWT installer kit `qubes-tools-x64.msi`, which will be shown as the content of the CDROM made available by starting the Windows qube with the additional option `--install-windows-tools` (see the QWT installation documentation). The installer kit is a specially formatted archive, from which the file `relocate_dir.exe` can be extracted using a utility like 7-Zip. The file has then to be copied to `%windir%\system32`, i.e. usually `C:\Windows\system32`. Furthermore, locate the registry key `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`, and add the text `relocate_dir.exe C:\Users Q:\Users` as a new line to the REG_MULTI_SZ-value `\BootExecute` in this key. On rebooting the Windows qube, the user files will be moved to the disk `Q:`, and the additional registry entry will be removed, such that this action occurs only once. + +If the user data have been moved to `Q:`, be sure not to user the option `Move User Profeiles`on subsequent installations of Qubes Windows tools. + AppVMs based on these templates can be created the normal way by using the Qube Manager or by specifying ~~~ From 63bf921aa6179d0d96215a8a252daaaa3ef5d3ca Mon Sep 17 00:00:00 2001 From: "Dr. Gerhard Weck" Date: Sat, 21 Sep 2024 13:27:20 +0200 Subject: [PATCH 08/20] Formal change --- user/templates/windows/windows-qubes-4-1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md index 62210c0a..84bf67ff 100644 --- a/user/templates/windows/windows-qubes-4-1.md +++ b/user/templates/windows/windows-qubes-4-1.md @@ -237,7 +237,7 @@ Moving the user data is not directly possible under Windows, because the directo - If Qubes Windows Tools is installed, the option `Move User Profiles` has to be selected on the installation. In this case, the user files are moved to the new disk during the reboot at the end of the installation. -- This can also be accomplished without QWT installation, avoiding the installation of the Xen PV drivers, if the risk of a compromised version of these drivers according to QSB-091 is considered too severe. In this case, the file `relocate_dir.exe` has to be extracted from the QWT installer kit `qubes-tools-x64.msi`, which will be shown as the content of the CDROM made available by starting the Windows qube with the additional option `--install-windows-tools` (see the QWT installation documentation). The installer kit is a specially formatted archive, from which the file `relocate_dir.exe` can be extracted using a utility like 7-Zip. The file has then to be copied to `%windir%\system32`, i.e. usually `C:\Windows\system32`. Furthermore, locate the registry key `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`, and add the text `relocate_dir.exe C:\Users Q:\Users` as a new line to the REG_MULTI_SZ-value `\BootExecute` in this key. On rebooting the Windows qube, the user files will be moved to the disk `Q:`, and the additional registry entry will be removed, such that this action occurs only once. +- This can also be accomplished without QWT installation, avoiding the installation of the Xen PV drivers, if the risk of a compromised version of these drivers according to QSB-091 is considered too severe. In this case, the file `relocate_dir.exe` has to be extracted from the QWT installer kit `qubes-tools-x64.msi`, which will be shown as the content of the CDROM made available by starting the Windows qube with the additional option `--install-windows-tools` (see the QWT installation documentation). The installer kit is a specially formatted archive, from which the file `relocate_dir.exe` can be extracted using a utility like 7-Zip. The file has then to be copied to `%windir%\system32`, i.e. usually `C:\Windows\system32`. Furthermore, locate the registry key `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`, and add the text `relocate_dir.exe C:\Users Q:\Users` as a new line to the `REG_MULTI_SZ` value `\BootExecute` in this key. On rebooting the Windows qube, the user files will be moved to the disk `Q:`, and the additional registry entry will be removed, such that this action occurs only once. If the user data have been moved to `Q:`, be sure not to user the option `Move User Profeiles`on subsequent installations of Qubes Windows tools. From 7c7911177f2709dce43ce937949ad9895e302c3e Mon Sep 17 00:00:00 2001 From: b90g <63392812+b90g@users.noreply.github.com> Date: Fri, 29 Nov 2024 20:21:29 +0100 Subject: [PATCH 09/20] Update windows-qubes-4-1.md evading microsoft account enforcement. --- user/templates/windows/windows-qubes-4-1.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md index 4d38a4bb..a89fd2ae 100644 --- a/user/templates/windows/windows-qubes-4-1.md +++ b/user/templates/windows/windows-qubes-4-1.md @@ -172,7 +172,15 @@ These parameters are set for the following reasons: - Click `Next`. A screen appears saying "Who's going to use this device?" This is the local account creation screen. - Enter the username you want to use and click `Next`. - Enter a password and click `Next`. You can leave the field blank but it's not recommended. + + For Windows 11 version 24H2, the following sequence of actions to use a local account instead of a Microsoft account has been proved working: + - Boot with a disconnected machine. + - When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window. + - Enter `oobe\bypassnro` and hit enter. + - The machine will restart and then lets you setup a local account. + - Machine then can go online again if desired. + - 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` From cc001965399ce3ac66c9f854e6e776aa16ff6906 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Fri, 20 Dec 2024 19:29:36 +0000 Subject: [PATCH 10/20] luksFormat: add --sector-size=512 argument --- user/advanced-topics/secondary-storage.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md index 24d97e2c..391e3059 100644 --- a/user/advanced-topics/secondary-storage.md +++ b/user/advanced-topics/secondary-storage.md @@ -65,10 +65,12 @@ In theory, you can still use file-based disk images ("file" pool driver), but it Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot): ``` -sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb +sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb sudo blkid /dev/sdb ``` +(The `--sector-size=512` argument can sometimes work around an incompatibility of storage hardware with LVM thin pools on Qubes. If this does not apply to your hardware, the argument will make no difference.) + Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing: ``` From 4fb0f0c851a44aeecd0778bca3c9babeebc79ec6 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Fri, 20 Dec 2024 19:29:37 +0000 Subject: [PATCH 11/20] luksFormat: drop arguments that are already the default --- user/advanced-topics/secondary-storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md index 391e3059..3e2e8cf9 100644 --- a/user/advanced-topics/secondary-storage.md +++ b/user/advanced-topics/secondary-storage.md @@ -65,7 +65,7 @@ In theory, you can still use file-based disk images ("file" pool driver), but it Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot): ``` -sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb +sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 /dev/sdb sudo blkid /dev/sdb ``` From 65e0511d1521be509a5226296ce9912b39d2eac8 Mon Sep 17 00:00:00 2001 From: Rusty Bird Date: Fri, 20 Dec 2024 19:29:38 +0000 Subject: [PATCH 12/20] luksFormat: drop --hash=sha512 argument The default (sha256) seems fine for LUKS2 where the hash algorithm has a limited role anyway - it's not used for key stretching like in LUKS1. --- user/advanced-topics/secondary-storage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user/advanced-topics/secondary-storage.md b/user/advanced-topics/secondary-storage.md index 3e2e8cf9..d541c3c3 100644 --- a/user/advanced-topics/secondary-storage.md +++ b/user/advanced-topics/secondary-storage.md @@ -65,7 +65,7 @@ In theory, you can still use file-based disk images ("file" pool driver), but it Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot): ``` -sudo cryptsetup luksFormat --sector-size=512 --hash=sha512 /dev/sdb +sudo cryptsetup luksFormat --sector-size=512 /dev/sdb sudo blkid /dev/sdb ``` From 5cb2a1e404bd415f35727b1cced9659f3226bb68 Mon Sep 17 00:00:00 2001 From: "Dr. Gerhard Weck" Date: Fri, 25 Apr 2025 13:56:11 +0200 Subject: [PATCH 13/20] Describe installation changes for Windows 11 --- user/templates/windows/windows-qubes-4-1.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/user/templates/windows/windows-qubes-4-1.md b/user/templates/windows/windows-qubes-4-1.md index 4d38a4bb..829a1087 100644 --- a/user/templates/windows/windows-qubes-4-1.md +++ b/user/templates/windows/windows-qubes-4-1.md @@ -146,18 +146,17 @@ These parameters are set for the following reasons: - Install on first disk. - **For Windows 11 only**: Windows 11 requires TPM 2.0, which currently is not supported from Xen. In Order to install Windows 11 under Qubes, the check for TPM in the Windows installer has to be disabled: - - When you start setup without having a TPM, you get an error message like *This PC does not fulfil the minimum requirements for Windows 11*. - - Typing Shift-F10 then opens a console window. + - When the window allowing you to select a Windows version is displayed, **do not select a version and close this window**, but instead type Shift-F10 to open a console window. - Here you type `regedit` to start the registry editor. - There you position to the key `HKEY_LOCAL_MACHINE\SYSTEM\Setup`. - Now create the key `LabConfig`. - 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. + - You will then return to 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. + :warning: **Caution:** This temporary patch may cease to work if it so pleases Microsoft sometime. With version 24H2 it is still working. - 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. Previously, this was true only for the home edition, but since version 24H2, it extends to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that works for version 21H2 but may be blocked for newer versions: - 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. @@ -173,6 +172,15 @@ These parameters are set for the following reasons: - Enter the username you want to use and click `Next`. - Enter a password and click `Next`. You can leave the field blank but it's not recommended. + For version 24H2, the following actions allow you to install Windows 11 with a local account, if the VM is defined, at least temporarily, without a netVM: + - After some reboots, the VM will show a window allowing the selection of an installation country. In this window, type Shift-F10 to open a console window. + - In this window, type `oobe\bypassnro`. The VM will then reboot and return to the country selection window. The network connection window will now show an option "I don't have internet", allowing you to define a local account. + + In new preview builds of Windows (26120 and beyond, and eventually the next release version), the `oobe\bypassnro` command has been erased and no longer works. Instead, there's a new command called start `ms-chx:localonly` that does something similar. In this case, proceed as follows: + - Follow the Windows 11 install process until you get to the Sign in screen. Here, type Shift-F10 to open a console window. + - Enter start `ms-cxh:localonly` at the command prompt. + - A "Create a user for this PC" dialog window appears, allowing you to define a local account. + - 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` From 5bd45751f962ce485cacb3bf376991dc2e27b398 Mon Sep 17 00:00:00 2001 From: PixelPilot <161360836+PixelPil0t1@users.noreply.github.com> Date: Sun, 27 Apr 2025 09:06:44 +0200 Subject: [PATCH 14/20] Update release-notes.md --- developer/releases/4_0/release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md index b80a1959..ca97ac0d 100644 --- a/developer/releases/4_0/release-notes.md +++ b/developer/releases/4_0/release-notes.md @@ -9,7 +9,7 @@ title: Qubes R4.0 release notes New features since 3.2 ---------------------- -* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/qubes-core-admin/en/latest/) +* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/en/latest/index.html) * [Admin API](/news/2017/06/27/qubes-admin-api/) allowing strictly controlled managing from non-dom0 * All `qvm-*` command-line tools rewritten, some options have changed * Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM From bd8a41941247969c2251b72d068bde25c0fef15c Mon Sep 17 00:00:00 2001 From: unman Date: Tue, 29 Apr 2025 12:35:08 +0000 Subject: [PATCH 15/20] Slight change to comment on use of color. Fix minor spelling mistake. --- introduction/getting-started.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/introduction/getting-started.md b/introduction/getting-started.md index 4a02083c..34ed98a2 100644 --- a/introduction/getting-started.md +++ b/introduction/getting-started.md @@ -67,8 +67,9 @@ in dom0. (That's what your app qubes are for!) In short, be very careful when in ### Color & Security You'll choose a **color** for each of your qubes out of a predefined set of -colors. The color of the frame of each window on your desktop will correspond to the color of that cube. -These colored frames help you keep track of which qube you're currently using and how trustworthy it is. This is especially helpful +colors. The color of the frame of each window on your desktop will correspond to the color of that qube. +These colored frames help you keep track of which qube you're currently using. +You may use them to show how trustworthy it is. This is especially helpful when you have the same program running in multiple qubes at the same time. For example, if you're logged in to your bank account in one qube while doing some random web surfing in a different qube, you wouldn't want to accidentally enter From 7870666de371d924021449f8886e1e99d4b110b2 Mon Sep 17 00:00:00 2001 From: unman Date: Wed, 30 Apr 2025 11:42:31 +0000 Subject: [PATCH 16/20] Clarified that main method relates to finding controller for attached device. Moved QubeManager method to separate section --- user/how-to-guides/how-to-use-usb-devices.md | 45 ++++++++++---------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index f845f89e..58d704ce 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -13,7 +13,7 @@ title: How to use USB devices If you are looking to handle USB *storage* devices (thumbdrives or USB-drives), please have a look at the [block device](/doc/how-to-use-block-storage-devices/) page. -**Note:** Attaching USB devices to VMs requires a [USB qube](/doc/usb-qubes/). +**Note:** Attaching USB devices to qubes requires a [USB qube](/doc/usb-qubes/). **Important security warning:** USB passthrough comes with many security implications. Please make sure you carefully read and understand the **[security considerations](/doc/device-handling-security/#usb-security)**. @@ -36,7 +36,7 @@ Click the device-manager-icon: ![device manager icon](/attachment/doc/media-remo A list of available devices appears. USB-devices have a USB-icon to their right: ![usb icon](/attachment/doc/generic-usb.png) -Hover on one device to display a list of VMs you may attach it to. +Hover on one device to display a list of qubes you may attach it to. Click one of those. The USB device will be attached to it. @@ -44,7 +44,7 @@ You're done. After you finished using the USB-device, you can detach it the same way by clicking on the Devices Widget. You will see an entry in bold for your device such as **`sys-usb:2-5 - 058f_USB_2.0_Camera`**. -Hover on the attached device to display a list of running VMs. +Hover on the attached device to display a list of running qubes The one to which your device is connected will have an eject button ![eject icon](/attachment/doc/media-eject.png) next to it. Click that and your device will be detached. @@ -74,7 +74,7 @@ sys-usb:2-1 03f0:0641 PixArt_Optical_Mouse ``` Now, you can use your USB device (camera in this case) in the `work` qube. -If you see the error `ERROR: qubes-usb-proxy not installed in the VM` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy). +If you see the error `ERROR: qubes-usb-proxy not installed in the qube` instead, please refer to the [Installation Section](#installation-of-qubes-usb-proxy). When you finish, detach the device. @@ -100,7 +100,7 @@ To use this feature, the `qubes-usb-proxy` package needs to be installed in the This section exists for reference or in case something broke and you need to reinstall `qubes-usb-proxy`. Under normal conditions, `qubes-usb-proxy` should already be installed and good to go. -If you receive this error: `ERROR: qubes-usb-proxy not installed in the VM`, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to. +If you receive this error: `ERROR: qubes-usb-proxy not installed in the qube`, you can install the `qubes-usb-proxy` with the package manager in the qube you want to attach the USB device to. - Fedora: ``` @@ -121,12 +121,9 @@ Mouse and keyboard setup are part of [setting up a USB qube](/doc/usb-qubes/). Some USB devices are not compatible with the USB pass-through method Qubes employs. In situations like these, you can try to pass through the entire USB controller to a qube as PCI device. -However, with this approach one cannot attach single USB devices but has to attach the whole USB controller with whatever USB devices are connected to it. - -You can find your controller and its BDF address using either of two methods described below. Using the command-line tools lsusb and readlink or by using the Qube Manager GUI. It is possible that on some system configurations the readlink method produces output which is different from the example below, while the Qube Manager method allows one to easily determine the correct controller and BDF address. - -#### Method 1: Using lsusb and readlink +However, with this approach you cannot attach single *USB devices* but have to attach the whole *USB controller* with whatever USB devices are connected to it. +You can find your controller and its BDF address using the method described below, using the command-line tools `lsusb` and `readlink`. If you have multiple USB controllers, you must first figure out which PCI device is the right controller. First, find out which USB bus the device is connected to (note that these steps need to be run from a terminal inside your USB qube): @@ -145,7 +142,7 @@ Bus 003 Device 003: ID 413c:818d Dell Computer Corp. (In this case, the device isn't fully identified) The device is connected to USB bus \#3. -Check which other devices are connected to the same bus, since *all* of them will be attach to the same VM. +Check which other devices are connected to the same bus, since *all* of them will be attached to the target qube. To find the right controller, follow the usb bus: @@ -158,27 +155,29 @@ This should output something like: ``` ../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3 ``` - -If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead. - -Now you see the path and the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the targetVM. - -For example, On R 4.0 the command would look something like - +Now you see the path: the text between `/pci0000:00/0000:` and `/usb3` i.e. `00:1a.0` is the BDF address. Strip the address and pass it to the [`qvm-pci` tool](/doc/how-to-use-pci-devices/) to attach the controller to the target qube, like this: ``` qvm-pci attach --persistent personal dom0:00_1a.0 ``` -#### Method 2: Using the Qube Manager +It is possible that on some system configurations the readlink method produces output which is different from the example above, +For example, you might see output like this: +``` +../../../devices/pci0000:00/0000:00:1c.0/0000:01:00.0/usb1 +``` +In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0 -Open the Qube Manager, then right click on one of the VMs and open the settings. Go to the tab "Devices". +If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead. +#### Identifying controllers using the Qube Manager +Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses. + +Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices". Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller". - They should look something like: `01:00.0 USB controller: Name of manufacturer` The first part is the BDF address, in this example: `01:00.0` -If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation" while the added controller shows another name of manufacturer. +If, for example, you have 2 USB controllers in your system because you added one you should see 2 such lines and you can probably guess which controller is the one on the mainboard and which one you added. For example, if you have a mainboard with an Intel chipset, it is possible that all of the mainboard devices show as "Intel Corporation", while the added controller shows another manufacturer's name. -Now you should be able to tell which is the correct BDF address of the mainboard USB controller or the added USB controller. +Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller. From 4a91a742fec5baacf6e338e96631d934759e2f7c Mon Sep 17 00:00:00 2001 From: unman Date: Wed, 30 Apr 2025 12:05:15 +0000 Subject: [PATCH 17/20] Minor changes to How to use USB devices page. --- user/how-to-guides/how-to-use-usb-devices.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/user/how-to-guides/how-to-use-usb-devices.md b/user/how-to-guides/how-to-use-usb-devices.md index cdcb7f54..b47c4c14 100644 --- a/user/how-to-guides/how-to-use-usb-devices.md +++ b/user/how-to-guides/how-to-use-usb-devices.md @@ -167,10 +167,10 @@ For example, you might see output like this: ``` In this case, there is a PCI bridge, and the BDF address of the controller is the *last* item, 01:00.0 -If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using method 2 using the Qube Manager instead. +If the output format does not match this example, or you are unsure if it contains the correct BDF address, you can try finding the address using using the Qube Manager instead. -#### Identifying controllers using the Qube Manager -Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses. +### Identifying controllers using the Qube Manager +Using Qube Manager you can quickly determine the controllers on your system and their BDF addresses, but not which controller a particular device is attached to. Open the Qube Manager, then right click on one of the qubes and open the settings. Go to the tab "Devices". Here you should see your available devices along with their BDF addresses. Look for the lines containing "USB controller". From ef37a8c68b16f8b560e47341471ba6e68c9e0ba6 Mon Sep 17 00:00:00 2001 From: unman Date: Wed, 30 Apr 2025 13:15:08 +0000 Subject: [PATCH 18/20] Update page on standalones with informatin about virtualization modes. Closes https://github.com/QubesOS/qubes-issues/issues/7517 --- user/advanced-topics/standalones-and-hvms.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/user/advanced-topics/standalones-and-hvms.md b/user/advanced-topics/standalones-and-hvms.md index 198dab42..2eae8b0c 100644 --- a/user/advanced-topics/standalones-and-hvms.md +++ b/user/advanced-topics/standalones-and-hvms.md @@ -50,6 +50,21 @@ is about the virtualization mode. In practice, however, it is most common for standalones to be HVMs and for HVMs to be standalones. Hence, this page covers both topics. +## Understanding Virtualization Modes + +PVH has both better performance and better security than either PV or HVM: + +PVH has less attack surface than PV, as it relies on Second Level Address Translation (SLAT) hardware. Guests modify their own page tables natively, without hypervisor involvement. Xen does not need to perform complex checks to ensure that a guest cannot obtain write access to its own page tables, as is necessary for PV. Flaws in these checks have been a source of no fewer than four guest ⇒ host escapes: XSA-148, XSA-182, XSA-212, and XSA-213. + +PVH also has less attack surface than HVM, as it does not require QEMU to provide device emulation services. While QEMU is confined in a stubdomain, and again in a seccomp based sandbox, the stubdomain has significant attack surface against the hypervisor. Not only does it have the full attack surface of a PV domain, it also has access to additional hypercalls that allow it to control the guest it is providing emulation services for. XSA-109 was a vulnerability in one of these hypercalls. + +PVH has better performance than HVM, as the stubdomain iin HVM consumes resources (both memory and a small amount of CPU). There is little difference in the I/O path at runtime, as both PVH and HVM guests usually use paravirtualized I/O protocols. + +Surprisingly, PVH often has better performance than PV. This is because PVH does not require hypercalls for page table updates, which are expensive. SLAT does raise the cost of TLB misses, but this is somewhat mitigated by a second-level TLB in recent hardware. + + + + ## Creating a standalone You can create a standalone in the Qube Manager by selecting the "Type" of From 55441615bfc082426c4f3b57e45c106afbedbd7e Mon Sep 17 00:00:00 2001 From: unman Date: Fri, 2 May 2025 00:24:26 +0000 Subject: [PATCH 19/20] Fix reference to /var/logs/syslog, and add journalctl. Update link from Qubes-Community to Forum guides. Minor changes. --- user/troubleshooting/vpn-troubleshooting.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/user/troubleshooting/vpn-troubleshooting.md b/user/troubleshooting/vpn-troubleshooting.md index 4671066c..dbf2ccd4 100644 --- a/user/troubleshooting/vpn-troubleshooting.md +++ b/user/troubleshooting/vpn-troubleshooting.md @@ -30,11 +30,11 @@ After suspend/resume, OpenVPN may not automatically reconnect. In order to get i After setting up OpenVPN and restarting the VM, you may be repeatedly getting the popup "Ready to start link", but the VPN isn't connected. -To figure out the root of the problem, check the VPN logs in `/var/logs/syslog`. The log may reveal issues like missing OpenVPN libraries, which you can then install. +To figure out the root of the problem, check the VPN logs in `/var/log/syslog` or use `journalctl`. The logs may reveal issues like missing OpenVPN libraries, which you can then install. ## `notify-send` induced failure -[Some VPN guides](https://github.com/Qubes-Community/Contents/blob/master/docs/configuration/vpn.md) use complex scripts that by themselves include call of `notify-send`, yet some images may not contain this tool or may not have it working properly. -For instance calling `notify-send` on `fedora-36` template VM gives: +[Some VPN guides](https://forum.qubes-os.org/t/configuring-a-proxyvm-vpn-gateway/19061) use complex scripts that include a call to `notify-send`, yet some images may not contain this tool or may not have it working properly. +For instance calling `notify-send` on a `fedora-36` template VM gives: ``` Failed to execute child process “dbus-launch” (No such file or directory) ``` @@ -43,8 +43,8 @@ To check this tool is working properly run: ```bash sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle ``` -You should see `info` message appear on the top of your screen. -If that is the case then, `notify-send` is not the issue. +You should see the `info` message appear on the top of your screen. +If that is the case then `notify-send` is not the issue. If it is not, and you have an error of some sort you can: -1. Remove all calls of `notify-send` from scripts you are using to start VPN -2. Use other template VM that have `notify-send` working or find proper guide and make your current template VM run `notify-send` work properly. +1. Remove all calls to `notify-send` from scripts you are using to start VPN +2. Use another template qube that has a working `notify-send` or find proper guide and make your current template run `notify-send` work properly. From 0c4d924d2152cc0179e75557bb5739c2c48929a3 Mon Sep 17 00:00:00 2001 From: unman Date: Fri, 2 May 2025 15:00:25 +0000 Subject: [PATCH 20/20] Update release notes link to head API --- developer/releases/4_0/release-notes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/developer/releases/4_0/release-notes.md b/developer/releases/4_0/release-notes.md index ca97ac0d..56b99d64 100644 --- a/developer/releases/4_0/release-notes.md +++ b/developer/releases/4_0/release-notes.md @@ -9,7 +9,7 @@ title: Qubes R4.0 release notes New features since 3.2 ---------------------- -* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/en/latest/index.html) +* Core management scripts rewrite with better structure and extensibility, [API documentation](https://dev.qubes-os.org/projects/core-admin/en/latest/index.html) * [Admin API](/news/2017/06/27/qubes-admin-api/) allowing strictly controlled managing from non-dom0 * All `qvm-*` command-line tools rewritten, some options have changed * Renaming VM directly is prohibited, there is GUI to clone under new name and remove old VM