Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-07-27 00:35:57 -04:00
Code Issues Projects Releases Packages Wiki Activity

update upstream

Browse source
This commit is contained in:
qubedmaiska 2025-05-03 10:18:23 -04:00
commit f55702643d
No known key found for this signature in database
GPG key ID: 204BCE0FD52C0501
6 changed files with 166 additions and 101 deletions
Download patch file Download diff file Expand all files Collapse all files

138
introduction/getting-started.md
View file

@ -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 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
@ -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,25 @@ 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, be very careful when interacting with dom0.
### 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 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
your banking password in the latter! The colored frames help to avoid such
@ -83,16 +79,16 @@ mistakes.
[![snapshot_41.png](/attachment/doc/r4.1-snapshot_40.png)](/attachment/doc/r4.1-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 +100,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 +129,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.1-qubes-manager.png](/attachment/doc/r4.1-qubes-manager.png)](/attachment/doc/r4.1-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.
- Press `Alt` + `F3` and search for `xfce terminal`.
- 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 +188,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 +246,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/)!

4
user/advanced-topics/secondary-storage.md
View file

@ -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 /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:
```

15
user/advanced-topics/standalones-and-hvms.md
View file

@ -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

59
user/how-to-guides/how-to-use-usb-devices.md
View file

@ -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)**.
@ -28,15 +28,15 @@ 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/ctap-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.
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,11 +44,11 @@ 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.
### 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.
@ -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.
@ -87,20 +87,20 @@ 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`.
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:
```
@ -111,18 +111,19 @@ 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.
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.
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):
@ -141,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:
@ -154,11 +155,29 @@ This should output something like:
```
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
```
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
```
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
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, 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".
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 manufacturer's name.
Now you should be able to tell which is the BDF address of the mainboard USB controller or the added USB controller.

32
user/templates/windows/windows-qubes-4-1.md
View file

@ -158,22 +158,20 @@ 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.
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-triangle"></i>
**Caution:** This temporary patch may stop functioning at Microsoft's discretion at some point in the future.
**Caution:** This temporary patch may cease to work if it so pleases Microsoft sometime. With version 24H2 it is still working.
</div>
- 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.
@ -188,6 +186,17 @@ 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:
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:
@ -252,7 +261,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

19
user/troubleshooting/vpn-troubleshooting.md
View file

@ -30,4 +30,21 @@ 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://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)
```
To check this tool is working properly run:
```bash
sudo notify-send "$(hostname): Test notify-send OK" --icon=network-idle
```
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 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.