Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-01-23 13:11:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into intel-troubleshooting

Browse Source
This commit is contained in:
Enjeck Cleopatra 2020-11-25 15:04:50 +01:00 committed by GitHub
commit ee391c3166
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
39 changed files with 889 additions and 781 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
.gitlab-ci.yml Normal file
View File

@ -0,0 +1,5 @@
include:
- https://raw.githubusercontent.com/QubesOS/qubes-continuous-integration/master/gitlab-website.yml
build:doc:
extends: .website

5
developer/code/license.md
View File

@ -14,8 +14,3 @@ Qubes OS License
Qubes is a compilation of software packages, each under its own license. The compilation is made available under the GNU General Public License version 2.
The full text of the GPL v2 license can be found [here](http://www.gnu.org/licenses/gpl-2.0.html).
Note on rights to double-licensing of the Qubes code
----------------------------------------------------
Invisible Things Lab (ITL), who has funded and run the Qubes project since the beginning, and who has contributed the majority of Qubes-specific code (specifically: `core-*`, `gui-*`, and `qubes-*` repositories) would like to have a right to redistribute parts of this code under proprietary licenses. This is especially important for Qubes R3 and later, where the new architecture allows the creation of many editions of Qubes, using different hypervisors, some of which might not be open source. That's why we ask every developer who contributes code to Qubes project to grant ITL permission to reuse the code under a different license, and to express this consent by including the [standard signed-off line](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst?id=HEAD#n416) in the commit.

23
developer/general/doc-guidelines.md
View File

@ -126,6 +126,8 @@ To add an image to a page, use the following syntax in the main document:
```
Then, submit your image(s) in a separate pull request to the [qubes-attachment] repository using the same path and filename.
This is the only permitted way to include images.
Do not link to images on other websites.
Version-specific Documentation
@ -239,6 +241,19 @@ Style Guidelines
* Familiarize yourself with the terms defined in the [glossary]. Use these
terms consistently and accurately throughout your writing.
* Syntactically distinguish variables in commands.
For example, this is ambiguous:
$ qvm-run --dispvm=dvm-template --service qubes.StartApp+xterm
It should instead be:
$ qvm-run --dispvm=<DVM_TEMPLATE> --service qubes.StartApp+xterm
Note that we syntactically distinguish variables in three ways:
1. Surrounding them in angled brackets (`< >`)
2. Using underscores (`_`) between words
3. Using all capital letters
Markdown Conventions
@ -248,6 +263,11 @@ All the documentation is written in Markdown for maximum accessibility.
When making contributions, please try to observe the following style conventions:
* Use spaces instead of tabs.
* Do not write HTML inside Markdown documents (except in rare, unavoidable cases, such as alerts).
In particular, never include HTML or CSS for styling, formatting, or white space control.
That belongs in the (S)CSS files instead.
* Link only to images in [qubes-attachment] (see [instructions above](#how-to-add-images)).
Do not link to images on other websites.
* In order to enable offline browsing, use relative paths (e.g., `/doc/doc-guidelines/` instead of `https://www.qubes-os.org/doc/doc-guidelines/`, except when the source text will be reproduced outside of the Qubes website repo.
Examples of exceptions:
* [QSBs] (intended to be read as plain text)
@ -289,9 +309,6 @@ When making contributions, please try to observe the following style conventions
~~~
The `#` symbol preceding each comment is ambiguous with a root command prompt.
Instead, put your comments *outside* of the code block in normal prose.
* Use `[reference-style][ref]` links.
`[ref]: https://daringfireball.net/projects/markdown/syntax#link`
([This][md] is a great source for learning about Markdown.)

4
developer/services/qrexec-socket-services.md
View File

@ -223,8 +223,8 @@ echo -e 'policy.Ask dom0\0<input data>' | nc -U /etc/qubes-rpc/policy.Ask
## Further reading
* [Qrexec overview][qrexec](/doc/qrexec/)
* [Qrexec internals][qrexec](/doc/qrexec-internals/)
* [Qrexec overview](/doc/qrexec/)
* [Qrexec internals](/doc/qrexec-internals/)
* [qubes-core-qrexec](https://github.com/QubesOS/qubes-core-qrexec/) repository - contains the above example
* [systemd.socket](https://www.freedesktop.org/software/systemd/man/systemd.socket.html) - socket unit configuration
* [Streams in Python asyncio](https://docs.python.org/3/library/asyncio-stream.html)

16
doc.md
View File

@ -131,6 +131,8 @@ Core documentation for Qubes users.
* [GUI Troubleshooting](/doc/gui-troubleshooting/)
* [Media Troubleshooting](/doc/media-troubleshooting/)
* [Firewall Troubleshooting](/doc/firewall/#firewall-troubleshooting)
* [VPN Troubleshooting](/doc/vpn-troubleshooting/)
* [Update Troubleshooting](/doc/update-troubleshooting/)
### Reference Pages
@ -264,6 +266,7 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co
* [Rxvt Guide](/doc/rxvt/)
* [Adding SSD storage cache](https://groups.google.com/d/msgid/qubes-users/a08359c9-9eb0-4d1a-ad92-a8a9bc676ea6%40googlegroups.com)
* [How to Make a Multimedia TemplateVM](/doc/multimedia/)
* [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
### Customization Guides
@ -272,15 +275,16 @@ For more, please see [Qubes Community Documentation](https://github.com/Qubes-Co
* [Language Localization](/doc/language-localization/)
* [Dark Theme in Dom0 and DomU](/doc/dark-theme/)
* [Safely Removing TemplateVM Packages (Example: Thunderbird)](/doc/removing-templatevm-packages/)
### Troubleshooting
* [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/)
* [Lenovo ThinkPad Troubleshooting](/doc/thinkpad-troubleshooting/)
* [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
* [How to install an Nvidia driver in dom0](/doc/install-nvidia-driver/)
* [Nvidia troubleshooting guide](/doc/nvidia-troubleshooting/)
* [Apple MacBook Troubleshooting](/doc/macbook-troubleshooting/)
* [Getting Sony Vaio Z laptop to work with Qubes](/doc/sony-vaio-tinkering/)
* [Sony Vaio Troubleshooting](/doc/sony-vaio-tinkering/)
* [Intel Integrated Graphics Troubleshooting](/doc/intel-igfx-troubleshooting/)
* [Multiboot Troubleshooting](/doc/multiboot/#troubleshooting)
* [Application Troubleshooting](/doc/application-troubleshooting/)
* [Tails Troubleshooting](/doc/tails-troubleshooting/)
### Building Guides

40
user/troubleshooting/install-nvidia-driver.md → external/configuration-guides/install-nvidia-driver.md vendored
View File

@ -135,43 +135,7 @@ mv /root/xorg.conf.new /etc/X11/xorg.conf
Reboot to verify all this works.
# Troubleshooting lack of video output during installation
## Troubleshooting lack of video output during installation
Specifically, the notes below are aimed to help when the GRUB menu shows up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules.
The GRUB menu may show up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules. See the [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#lack-of-video-output-during-nvidia-driver-installation) guide for troubleshooting steps.
## Initial setup.
*Note*: The steps below do *not* produce a fully-functional Qubes OS install. Rather, only a dom0 instance is functional, and there is no networking there. However, they can be used to gather data in order to troubleshoot video card issues and/or possible other basic kernel module issues.
1. Append `nomodeset ip=dhcp inst.nokill inst.vnc` to the kernel command line. Remove `rhgb` and `quiet` to see the kernel messages scroll by, which may help in further diagnostics.
* If DHCP is not available on the installation network, the syntax becomes a bit more involved. The full list of variants is documented in the [Dracut Command-line parameters] (http://man7.org/linux/man-pages/man7/dracut.cmdline.7.html)
2. The VGA console should switch into the installer's multi-virtual-terminal display. VNC may take a number of minutes to start, please be patient.
* Using the anaconda installer interface, switch to the "shell" TTY (ALT-F2), and use `ip a` command to display the IP addresses.
3. Using the Connect to the IP (remember the :1) using a VNC viewer.
4. Follow the installation UI.
* Since this won't be a usable install, skipping LUKS encryption is an option which will simplify this troubleshooting process.
* Do *not* reboot at the end of the installation.
5. Once the installation completes, use the local VGA console switch to TTY2 via ALT-F2
* Switch to the chroot of the newly-installed system via `chroot /mnt/sysinstall`
* Set the root password (this will also enable the root account login)
* Double-check that `/boot/grub2/grub.cfg` contains a `nomodeset` kernel parameter.
* Exit out of the chroot environment (`exit` or CTRL-D)
6. Reboot
*Note* If the kernel parameters do *not* include `quiet` and `rhgb`, the kernel messages can easily obscure the LUKS passphrase prompt. Additionally, each character entered will cause the LUKS passphrase prompt to repeat onto next line. Both of these are cosmetic. The trade-off between kernel messages and the easy-to-spot LUKS passphrase prompt is left as an exercise to the user.
## Gather initial `dmesg` output
If all is well, the newly-installed Qubes OS instance should allow for user root to log in.
Run `dmesg > dmesg.nomodeset.out` to gather an initial dmesg output.
## Gather the 'video no worky' `dmesg` output
1. Reboot and interrupt the Grub2's process, modifying the kernel parameters to no longer contain `nomodeset`.
* If the LUKS passphrase was set, blindly enter it.
2. Wait for the system to finish booting (about 5 minutes, typically).
3. Blindly switch to a TTY via CTRL-ALT-F2.
4. Blindly log in as user root
5. Blindly run `dmesg > dmesg.out`
6. Blindly run `reboot` (this will also serve to confirm that logging in as root, and running commands blindly is possible rather than, say, the kernel having hung or some such).
* Should this step fail, perhaps by the time step #3 was undertaken, the OS hasn't finished coming up yet. Please retry, possibly with a different TTY (say, 3 or 4 - so CTRL-ALT-F3?)
## Exfiltrate the dmesg outputs
Allow the system to boot normally, log in as user root, and sneakernet the files off the system for analysis, review, bug logging, et cetera.

4
external/configuration-guides/vpn.md vendored
View File

@ -318,6 +318,4 @@ If you want to update your TemplateVMs through the VPN, you can enable the `qube
Troubleshooting
---------------
* Always test your basic VPN connection before adding scripts.
* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain.
* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding.
See the [VPN Troubleshooting](/doc/vpn-troubleshooting/) guide for tips on how to fix common VPN issues.

36
external/privacy-guides/tails.md vendored
View File

@ -47,36 +47,7 @@ To run Tails under Qubes:
7. Use Tails as normal.
## Usage Notes
### Display issues:
**Black screen on start up.**
This was reported with earlier versions of Tails: The problem should now be fixed.
If you do encounter this problem, you can try to constrain display settings by appending vga codes to the Tails boot parameters.
(If you do not know the codes, append `vga=999`, and a helpful prompt will appear.)
N.B Tails 2.3 does not appear to honour the vga code.
**Window extends beyond the bottom of the screen.**
This seems to arise because Tails sizes to the height of the screen, but there is a title bar at the top of the window.
Either remove the title bar altogether, or move the window upwards using ALT+drag.
### Persistent Volume
The persistence tools will not work because Tails has not been launched from USB.
The HVM disk(s) can be configured and mounted from within Tails to provide persistent storage.
If you want to use an existing USB persistent volume:
- Interrupt the Tails vm boot process with arrow-up when the grub boot menu appears.
- In dom0 attach the USB drive containing the persistent volume to the Tails vm.
- Continue booting Tails: Tails-greeter will detect the encrypted partition on the attached USB.
- Unlock the persistent volume in Tails-greeter and use it as normal.
### Shutdown
The Tails qube will not shut down cleanly.
Kill it from the GUI Manager or ```qvm-kill Tails``` in Konsole.
### Security
## Security
You will probably want to implement [MAC spoofing](/doc/anonymizing-your-mac-address/).
There are added security concerns for Tails users when running it in a virtual machine.
@ -84,3 +55,8 @@ If you intend to do this, you should read [the warnings](https://tails.boum.org/
While the Qubes security model mitigates most of the risks identified, traces of the Tails session may remain on the disk.
Live booting Tails, though less convenient, is always more secure than using it inside virtualization software or Qubes, because you don't run the added risk of the virtualization software or Host OS being compromised.
Depending on your threat model, this might induce too much risk.
## Troubleshooting
See the [Tails Troubleshooting guide](/doc/tails-troubleshooting/).

45
external/troubleshooting/application-troubleshooting.md vendored Normal file
View File

@ -0,0 +1,45 @@
---
layout: doc
title: Application Troubleshooting
permalink: /doc/application-troubleshooting/
---
# Troubleshooting default applications on Qubes #
## Fullscreen Firefox is frozen ##
Press F11 twice.
## Firefox crashes ##
If you are facing frequent crashes or lags when using Firefox browser (especially when watching videos), you may need to turn off Hardware Acceleration. You can do this by navigating to "Preferences", then "Performance". Untick the "Use recommended performance settings" checkbox, followed by "Use hardware acceleration when available".
If this doesn't fix the issue, try turning off smooth scrolling by unticking "Use smoothing scrolling" under the "Browsing" section.
## LibreOffice open as a tiny window ##
Some programs like LibreOffice open as a tiny window -- small enough that the content of the file is not even visible.
You can open LibreOffice as a larger window using this workaround:
### Using the command line
1. In the VM where you want to open the LibreOffice, open the `registrymodifications.xcu` file in an editor:
~~~
sudo nano ~/.config/libreoffice/4/user/registrymodifications.xcu
~~~
2. Find the lines containing `ooSetupFactoryWindowAttributes`. It will look like this:
~~~
<item oor:path="/org.openoffice.Setup/Office/Factories/org.openoffice.Setup:Factory['com.sun.star.sheet.SpreadsheetDocument']"><prop oor:name="ooSetupFactoryWindowAttributes" oor:op="fuse"><value>61,61,1807,982;5;38,56,1807,982;</value></prop></item>
~~~
3. We are interested in the values between the `<value>` tag. These window position values are specified as: `x-pos,y-pos,width,height ; window-state ; maximized-x-pos,maximized-y-pos,maximized-width,maximized-height`. Edit the third and fourth values to your desired width and height (for example, to 1800 and 900).
4. Do this once for every template and the program will always open at this size.
### Using the GUI
1. Open any Libreoffice app.
2. Navigate to the "Tools" menu, select "Options", then "Advanced". Click the "Open Expert Configuration" button.
3. Search for "ooSetupFactoryWindowAttributes".
4. Scroll right to see the values set for each component as a string value. For example: `61,61,1807,982;5;38,56,1807,982;`. These window position values are specified as: `x-pos,y-pos,width,height ; window-state ; maximized-x-pos,maximized-y-pos,maximized-width,maximized-height`. Edit the third and fourth values to your desired width and height (for example, to 1800 and 900).
5. Do this once for every template and the program will always open at this size.

241
external/troubleshooting/macbook-troubleshooting.md vendored Normal file
View File

@ -0,0 +1,241 @@
---
layout: doc
title: Apple MacBook Troubleshooting
permalink: /doc/macbook-troubleshooting/
---
# Apple MacBook Troubleshooting
## System freezes after attaching Broadcom BCM43602 Wi-Fi card
You may experience system freezes or crashes after attaching a Broadcom Wi-Fi adapter to the sys-net VM. This issue has been reported to exist on both Qubes 3.2 and 4.0.
### Qubes 3.2
To fix this issue on Qubes 3.2:
1. During VM setup, force a reboot and press `OPTION` key.
2. You will reach the grub shell
~~~
configfile /EFI/qubes/grub.cfg
~~~
3. Press Fn+F10 to boot without XEN support.
4. Once booted, press Fn+CTRL+ALT+F4 to open a shell.
5. Log into the system
~~~
sudo su -
systemctl disable qubes-netvm
~~~
6. Press Fn+F2 and complete the setup.
7. Reboot Qubes.
8. DO NOT launch the sys-net qube.
Rather, open its setting and remove the Wi-Fi adapter from the Selected devices using the Qubes Manager.
You can also remove it from the command line, if you know the BDF of the adapter.
You can see the list of devices attached to sys-net and their associated BDFs by running:
~~~
qvm-pci -l sys-net
~~~
For a device with a BDF of `04:00.0`, you can remove it with:
~~~
qvm-pci -d sys-net 04:00.0
~~~
9. In a dom0 terminal, run:
~~~
sudo su -
xl pci-assignable-list
echo 04:00.0 > /sys/bus/pci/drivers/pciback/permissive
qvm-start sys-net
xl pci-attach sys-net DEVICE_BDF
~~~
Be sure to replace "DEVICE_BDF" with the actual BDF of the Wi-Fi adapter.
After following the above steps, you should be able to launch sys-net with Wi-Fi access. These steps can be automated in a custom `systemd` service.
### Qubes 4.0
For Qubes 4.0, you may have to remove the wireless card from sys-net or replace it, as described in the [PCI Troubleshooting](/doc/pci-troubleshooting/#broadcom-bcm43602-wi-fi-card-causes-system-freeze) guide.
It is a bit tricky to execute, but you may be able to successfully attach a Broadcom BCM43602 to sys-net by executing the `attach` command immediately after starting sys-net. Follow these steps:
1. Disable "Start qube automatically on boot" for sys-net and sys-firewall in the Qubes Manager.
2. Manually start sys-net using the `qvm-start sys-net` command.
3. Immediately (About 2 seconds later) after stating sys-net, attach the device to sys-net using permissive mode:
`sudo xl pci-attach sys-net 'DEVICE_BDF,permissive=1`
Replace `DEVICE_BDF,` with the BDF of your wireless card. If you can immediately attach the device to sys-net while it is still starting up, it could work. If it is attached too late, the VM doesn't seem to detect it.
You can use the following script to do the above steps quickly after each boot:
~~~
#!/bin/bash
qvm-start sys-net &
sleep 3
sudo xl pci-attach sys-net '03:00.0,permissive=1'
~~~
## Broadcom BCM4360 doesn't work in a Fedora-based qube
Several people have been unable use the Broadcom BCM4360 Wireless card on a Fedora-based qube. This issue appears to be [related to Fedora](https://ask.fedoraproject.org/t/cant-connect-to-wifi-after-update-bcm4360-with-broadcom-wl-driver/482?page=2), not Qubes.
To get internet access in sys-net, try shutting down all your VMs, then changing sys-net to use the Debian 10 template. Finally, install the [broadcom-sta-dkms](https://pkgs.org/download/broadcom-sta-dkms) package.
## Boot freezes at "Setting up networking"
After installing Qubes 3.2 on a MacBook Air 13" mid-2011 (MacBookAir 4,2), it may freeze at "Setting up networking" during booting. This issue is caused by the Broadcom Wireless adapter, if you have one.
To fix the problem, you need to [remove the Wi-Fi card from your Mac][bluetooth-replacement] or put the Wi-Fi adapter into PCI passthrough, as explained below:
1. Run in a terminal:
~~~
# diskutil list
(find your usb device)
# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition
# reboot
~~~
2. Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up.
Select Troubleshooting and Boot the Rescue image. Enter your disk password when
prompted. Select continue and after mounting the HD filesystem and launching a
shell, `chroot` as instructed.
3. Find your Wi-Fi card:
~~~
# lspci
...
02:00.0 Network controller: Broadcom Corporation BCM43224 802.11a/b/g/n (rev 01)
~~~
In the above example, the device has a BDF of `02:00.0`.
To assign this device to the sys-net VM:
~~~
# qvm-pci -a sys-net 02:00.0
~~~
4. Create `/etc/systemd/system/qubes-pre-netvm.service` with:
~~~
[Unit]
Description=Netvm fix for Broadcom
Before=qubes-netvm.service
[Service]
ExecStart=/bin/sh -c 'echo 02:00.0 > /sys/bus/pci/drivers/pciback/permissive'
Type=oneshot
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
~~~
5. To enable the `qubes-pre-netvm` services, run:
~~~
systemctl enable qubes-pre-netvm.service
~~~
6. After reboot, boot Mac OS X again by running in a terminal:
~~~
# diskutil list
(find the HD device where you installed Qubes)
# bless –device /dev/diskX –legacy –setBoot # bless the disk not the partition
# reboot
~~~
## Can't boot the installer
You can install Qubes 3.2 on a MacBook Pro Retina, 15 inch, Mid-2015 (MacBookPro 11,5) using BIOS or UEFI (If one method fails, try the other):
* BIOS/CSM/Legacy
* UEFI plain: Here, the grub menu appears, but any gives a quick flash and returns the main menu. Then, you can boot it manually and fix the `grub.cfg` file by adding the commands `linuexefi` and `initrdefi` and pointing to the proper files in `/efi/boot`. After boot, you may end up with no root file system.
* UEFI, using rEFInd: This method may prove successful, but there are some issues to be fixed manually after the installation is complete.
1. Download [rEFInd] refind-bin-0.10.4.zip. Note that this file is not signed, so decide if you trust it or not. The SHA1 sum is 3d69c23b7d338419e5559a93cd6ae3ec66323b1e
2. Unzip it and run the installer, which installs rEFInd on the internal SSD
3. If installation fails due to SIP, reboot in recovery mode, open a terminal and run the command:
~~~
csrutil disable
~~~
4. Reboot. You will see some icons.
5. Choose Boot EFI\BOOT\xen.efi from ANACONDA. After a while, the graphical installer is up (keyboard and touchpad working)
## Can't boot using GRUB2
After installing Qubes 3.2 on a MacBook Mid-2015, you may be unable to boot using `EFI/qubes/xen.efi` because the [XEN bootloader configuration is broken](/doc/macbook-troubleshooting/#cant-boot-using-xen-bootloader).
You can't also boot using GRUB2 without XEN support because the GRUB configuration is broken as well.
To start fixing this issue manually, switch to the console by pressing Fn+CTRL+ALT+F2.
It can be very useful – during troubleshooting – to have a rescue system at hand. It could help you boot Qubes, even without XEN support. This troubleshoot assumes you are performing a [UEFI boot, using rEFInd](/doc/macbook-troubleshooting/#cant-boot-the-installer).
At this point, the GRUB configuration file is using some wrong commands, which are not compatible with grub2-efi
~~~
chroot /mnt/sysimage
sed -i.bak -e "s/multiboot/chainloader/" -e "s/module.*--nounzip/initrdefi/" -e "s/module/linuxefi/" /etc/grub.d/20_linux_efi
exit
~~~
Now, despite XEN configuration is still broken, you have a rescue system booting vmlinux from rEFInd screen.
TBV1: chainloading XEN does not work, unless you specify the right disk prefix, eg: (hd1,gpt4)
TBV2: grub.cfg set the wrong disk in "set root" command
TBV3: in case you reach grub shell, you can
~~~
ls
~~~
and also reload config file and change it manually before booting
~~~
configfile /EFI/qubes/grub.cfg
~~~
Then press "e", edit `grub.cfg` and boot by pressing Fn+F10.
## Can't boot using XEN bootloader
You may be unable to boot Qubes 3.2 using `EFI/qubes/xen.efi` on a MacBook Mid-2015 because the XEN bootloader configuration is broken. This issue is accompanied by the GRUB2 configuration being broken as well. After [fixing the GRUB configuration](/doc/macbook-troubleshooting/#cant-boot-using-grub2), follow the following steps to fix the bootloader. This troubleshoot assumes you are performing a [UEFI boot, using rEFInd](/doc/macbook-troubleshooting/#cant-boot-the-installer).
* Fix grub2 configuration, which uses wrong command for EFI boot
* Analyzing `/mnt/sysimage/var/log/anaconda/program.log`, you may find the faulty commands issued by the Anaconda installer.
~~~
chrooot /mnt/sysimage
~~~
* Edit the `/boot/efi/EFI/qubes/xen.cfg` file to add the following content:
~~~
[global]
default=4.4.14-11.pvops.qubes.x868_64
[4.4.14-11.pvops.qubes.x868_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M
kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64
ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img
~~~
* The main mistake is that `efibootmgr` needs the right commands. Just in case, reapply all the commands, adapting them to your own disk layout (`-d /dev/sdxxx -p partition_number`)
~~~
grep Running /mnt/sysimage/var/log/anaconda/program.log | tail -n 20
efibootmgr -b 0000 -B
efibootmgr -c -w -L Qubes -d /dev/sda -p 4 -l \\EFI\\qubes\\xen-4.6.1.efi
/usr/libexec/mactel-boot-setup
kernel-install add 4.4.14-11.pvops.qubes.x86_64 /boot/vmlinuz-4.4.14-11.pvops.qubes.x86_64
systemctl disable qubes-netvm
reboot
~~~
At the rEFInd screen, choose Boot EFI/qubes/xen-4.6.1.efi.
Everything should now be ok, Qubes OS boots using EFI and you will get the last setup screen.
Select "Qubes OS", do not change anything and click on "Done".
VMs are created, including NetVM.
## System freezes often for 20 seconds
Using Qubes 3.2 on the MacBook Mid-2015 was reported to have frequent freezes, which lasts for 20 seconds. Upon looking at the `journalctl` output, you may see that pulseaudio locks the CPU for 20 seconds, very often.
To fix this issue, kill audio support with this quick workaround:
1. Open a dom0 terminal as root
2. Edit `/etc/pulse/client.conf` and add `autospawn = no`
3. As normal user, kill pulseaudio with the command `pulseaudio --kill`
[bluetooth-replacement]: https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360
[rEFInd]: http://www.rodsbooks.com/refind/getting.html

86
user/troubleshooting/nvidia-troubleshooting.md → external/troubleshooting/nvidia-troubleshooting.md vendored
View File

@ -8,21 +8,20 @@ redirect_from:
- /wiki/NvidiaTroubleshooting/
---
NVidia Troubleshooting Guide
============================
# Nvidia Troubleshooting Guide
If you have an NVidia graphics card it will probably not work under Xen out of the box. If your system freezes during boot and you don't see the graphical login manager after you installed Xen, then this problem most likely affects you. The following steps should provide a work around so that you should be able to use your NVidia with X under Xen, however without any fancy "desktop effects".
## System freezes during boot / Graphical login manager is not visible
Boot in failsafe
---------------------
If you have an NVidia graphics card it will probably not work under Xen out of the box. If your system freezes during boot and you don't see the graphical login manager after you installed Xen, then this problem most likely affects you. The following steps should provide a workaround so that you should be able to use your NVidia with X under Xen, however without any fancy "desktop effects".
### Boot in failsafe
Boot your system using the "failsafe" boot menu, that should have been automatically added to your `grub.conf` when you installed the Dom0 kernel.
If the X Window System doesn't start now, this is probably a non-Xen related issue and this guide will probably not help you.
Configure X with nouveau
---------------------
### Configure X with nouveau
Assuming your X Window System works fine now when you booted from the "failsafe" configuration, do the next steps...
@ -78,14 +77,15 @@ Assuming your X Window System works fine now when you booted from the "failsafe"
8. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now.
## Boot failure after GRUB menu / System freezes followed by reboot
Disabling Nouveau
---------------------
If Qubes fails to properly boot after the GRUB Boot menu and you are stuck on a black screen that displays messages starting with `nouveau` then it means that the nouveau driver failed to launch properly.
One way to get rid of this for now is to disable nouveau.
Example error
### Disabling Nouveau
Example error:
~~~
nouveau E[ PGRAPH][0000:01:00.0] grctx template channel unload timeout
@ -97,6 +97,32 @@ Tip: In case you only have an external monitor it is advised to attach it direct
If you're seeing this error then that means another graphics card (most likely an integrated one) acted as failsafe. Disabling nouveau has the consequences of disabling nvidia support altogether.
#### EFI
1. Open a terminal in dom0.
2. To edit the `xen.cfg` file using the `nano` editor:
~~~
sudo nano /boot/efi/EFI/qubes/xen.cfg
~~~
3. Locate the three `kernel=` lines. Press the left/right arrow keys to position the cursor at the end of the lines, after `rhgb quiet`.
4. Add the following:
~~~
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
~~~
This will disable nouveau until the option is manually edited back to its original state.
5. Press the `Ctrl+X` keys, then `y` to save changes.
6. Reboot
#### GRUB
1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast.
~~~
@ -157,3 +183,43 @@ You'll have to do the following to make this change persistent, so that it will
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
## Lack of video output during Nvidia driver installation
Specifically, the notes below are aimed to help when during Nvidia driver installation, the GRUB menu shows up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules.
### Initial setup.
*Note*: The steps below do *not* produce a fully-functional Qubes OS install. Rather, only a dom0 instance is functional, and there is no networking there. However, they can be used to gather data in order to troubleshoot video card issues and/or possible other basic kernel module issues.
1. Append `nomodeset ip=dhcp inst.nokill inst.vnc` to the kernel command line. Remove `rhgb` and `quiet` to see the kernel messages scroll by, which may help in further diagnostics.
* If DHCP is not available on the installation network, the syntax becomes a bit more involved. The full list of variants is documented in the [Dracut Command-line parameters] (http://man7.org/linux/man-pages/man7/dracut.cmdline.7.html)
2. The VGA console should switch into the installer's multi-virtual-terminal display. VNC may take a number of minutes to start, please be patient.
* Using the anaconda installer interface, switch to the "shell" TTY (ALT-F2), and use `ip a` command to display the IP addresses.
3. Using the Connect to the IP (remember the :1) using a VNC viewer.
4. Follow the installation UI.
* Since this won't be a usable install, skipping LUKS encryption is an option which will simplify this troubleshooting process.
* Do *not* reboot at the end of the installation.
5. Once the installation completes, use the local VGA console switch to TTY2 via ALT-F2
* Switch to the chroot of the newly-installed system via `chroot /mnt/sysinstall`
* Set the root password (this will also enable the root account login)
* Double-check that `/boot/grub2/grub.cfg` contains a `nomodeset` kernel parameter.
* Exit out of the chroot environment (`exit` or CTRL-D)
6. Reboot
*Note* If the kernel parameters do *not* include `quiet` and `rhgb`, the kernel messages can easily obscure the LUKS passphrase prompt. Additionally, each character entered will cause the LUKS passphrase prompt to repeat onto next line. Both of these are cosmetic. The trade-off between kernel messages and the easy-to-spot LUKS passphrase prompt is left as an exercise to the user.
### Gather initial `dmesg` output
If all is well, the newly-installed Qubes OS instance should allow for user root to log in.
Run `dmesg > dmesg.nomodeset.out` to gather an initial dmesg output.
### Gather the 'video no worky' `dmesg` output
1. Reboot and interrupt the Grub2's process, modifying the kernel parameters to no longer contain `nomodeset`.
* If the LUKS passphrase was set, blindly enter it.
2. Wait for the system to finish booting (about 5 minutes, typically).
3. Blindly switch to a TTY via CTRL-ALT-F2.
4. Blindly log in as user root
5. Blindly run `dmesg > dmesg.out`
6. Blindly run `reboot` (this will also serve to confirm that logging in as root, and running commands blindly is possible rather than, say, the kernel having hung or some such).
* Should this step fail, perhaps by the time step #3 was undertaken, the OS hasn't finished coming up yet. Please retry, possibly with a different TTY (say, 3 or 4 - so CTRL-ALT-F3?)
### Exfiltrate the dmesg outputs
Allow the system to boot normally, log in as user root, and sneakernet the files off the system for analysis, review, bug logging, et cetera.

28
user/troubleshooting/sony-vaio-tinkering.md → external/troubleshooting/sony-vaio-tinkering.md vendored
View File

@ -11,36 +11,37 @@ redirect_from:
Instructions for getting your Sony Vaio Z laptop working with Qubes/Linux
=========================================================================
Sony Vaio Z are great laptops -- they are very powerful, yet compact. The newer models, starting from Z12 are, however, not very well supported by Linux kernels (at least 2.6.34 that we currently use in Dom0) and thus some tinkering is needed to get Qubes working on those machines.
The following issues were reported on Qubes 3.2 and may not be prevalent on Qubes 4.0.
Getting the graphics card working under Linux/Qubes OS
------------------------------------------------------
Graphics card does not work
---------------------------
Newer models of Sony Vaio Z come with an "intelligent" GPU switch, that automatically chooses either Intel Integrated GPU (IGD) or the discrete NVIDIA GPU. This confuses the Linux graphics so much, that in most cases won't even be able to install a regular Linux on such a machine. Unfortunately, moving the switch into the "Stamina" position apparently doesn't work, and the automatic GPU switching is still active.
Newer models of Sony Vaio Z come with an "intelligent" GPU switch, that automatically chooses either Intel Integrated GPU (IGD) or the discrete NVIDIA GPU. This confuses the Linux graphics so much, that in most cases, it won't even be able to install a regular Linux on such a machine. Unfortunately, moving the switch into the "Stamina" position apparently doesn't work, and the automatic GPU switching is still active.
One solution that actually worked for me was to reflash the BIOS (I know, I know, this is scary) and to enable the so called "Advanced Menu" in the BIOS. This Advanced Menu allows you to choose the desired behaviour of the GPU switch, which in our case would be to set it to "Static" and then move the mechanical switch to the "Stamina" position, that enabled the Intel IGD (which is much better supported on Linux).
If you think you are ready to reflash you BIOS, here are the instructions that worked for me:
[http://forum.notebookreview.com/sony/473226-insyde-hacking-new-vaio-z-advanced-menu-bios.html](http://forum.notebookreview.com/sony/473226-insyde-hacking-new-vaio-z-advanced-menu-bios.html)
If you think you are ready to reflash you BIOS, you can follow [these instructions](http://forum.notebookreview.com/sony/473226-insyde-hacking-new-vaio-z-advanced-menu-bios.html).
**WARNING**: We take absolutely no responsibility that the BIOS reflashing instructions given at the referenced forum are 1) valid, 2) non-malicious, and 3) work at all. Do this step at your own risk. Keep in mind that reflashing your BIOS might yield your system unusable. If you don't feel like taking this risk (which is a reasonable state of mind), look for a different notebook, or ask Sony Support to enable this option for you.
In practice I have downloaded the BIOS-patching tools, run them in a VM on a BIOS image I extracted from my laptop, diffed the two versions, and concluded that it doesn't *seem* malicious, and then bravely applied tha patched image. If you don't know what are you doing, just get a different laptop, really!
In practice I have downloaded the BIOS-patching tools, run them in a VM on a BIOS image I extracted from my laptop, diffed the two versions, and concluded that it doesn't *seem* malicious, and then bravely applied the patched image. If you don't know what are you doing, just get a different laptop, really!
On a side note, we should note that allowing anybody to reflash the BIOS is really a bad idea from a security point of view (Hello Evil Maids!). Shame on you, Sony!
Getting the touchpad working during installation
------------------------------------------------
Touchpad does not work during installation
------------------------------------------
In order to get the touchpad working during installation you should pass the **~~~i8042.nopnp=1~~~** option to the kernel before the installer starts.
In order to get the touchpad working during installation you should pass the `i8042.nopnp=1` option to the kernel before the installer starts:
\<screenshot\>
~~~
sudo nano /etc/default/grub
GRUB_CMDLINE_LINUX_DEFAULT="i8042.nopnp=1"
~~~
Applying other fixes
--------------------
There are a few more fixes needed for Sony Vaio Z, and we have prepared a special package that you can install in Dom0 that applies them all. After the installation is complete, open console in Dom0 and do the following:
There are a few more fixes needed for Sony Vaio Z, and we have prepared a special package that you can install in dom0 that applies them all. After the installation is complete, open a console in dom0 and do the following:
~~~
$ sudo bash
@ -55,4 +56,3 @@ This script takes care about the following:
- Adding special option for the sound module (so you can get sound)
- Adding pm-suspend scripts that take care about restoring your screen after resume
... now, having done this all, you will surely feel unprecedented satisfaction and you will love your Vaio very much! ;)

33
external/troubleshooting/tails-troubleshooting.md vendored Normal file
View File

@ -0,0 +1,33 @@
---
layout: doc
title: Tails Troubleshooting
permalink: /doc/tails-troubleshooting/
---
# Tails Troubleshooting Guide #
## Black screen during startup
This was reported with earlier versions of Tails -- the problem should now be fixed.
If you do encounter a black screen during Tails startup, you can try to constrain display settings by appending vga codes to the Tails boot parameters.
If you do not know the codes, append `vga=999`, and a helpful prompt will appear.
Note: Tails 2.3 does not appear to honour the vga code.
## Window extends beyond the bottom of the screen
This problem seems to arise because Tails sizes to the height of the screen, but there is a title bar at the top of the window.
Either remove the title bar altogether, or move the window upwards using ALT+drag.
## Persistent tools do not work
The persistence tools, such as persistent volume, may not work because Tails has not been launched from USB.
The HVM disk(s) can be configured and mounted from within Tails to provide persistent storage.
If you want to use an existing USB persistent volume:
1. Interrupt the Tails vm boot process with arrow-up when the grub boot menu appears.
2. In dom0 attach the USB drive containing the persistent volume to the Tails VM.
3. Continue booting Tails. Tails-greeter will detect the encrypted partition on the attached USB.
4. Unlock the persistent volume in Tails-greeter and use it as normal.
## Tails qube doesn't shut down cleanly
If the Tails qube will not shut down cleanly, you can kill it from the GUI Manager or enter ```qvm-kill Tails``` in the console.

82
introduction/faq.md
View File

@ -348,7 +348,7 @@ See [Admin API] and [Core Stack] for more details.
### What are the system requirements for Qubes OS?
See the [System Requirements].
See the [system requirements].
### Is there a list of hardware that is compatible with Qubes OS?
@ -367,46 +367,42 @@ This also means that it is possible to update the software for several qubes sim
### How much memory is recommended for Qubes?
At least 6 GB, but 8 GB is more realistic.
It is possible to install Qubes on a system with 4 GB of RAM, but the system would probably not be able to run more than three qubes at a time.
Please see the [system requirements].
### Can I install Qubes 4.x on a system without VT-x or VT-d?
### Can I install Qubes on a system without VT-x/AMD-V or VT-d/ADM-Vi/AMD IOMMU?
Qubes 4.x requires Intel VT-x with EPT / AMD-V with RVI (SLAT) and Intel VT-d / AMD-Vi (aka AMD IOMMU) for proper functionality (see the [4.x System Requirements]).
Please see the [system requirements] for the latest information.
If you are receiving an error message on install saying your "hardware lacks the features required to proceed", check to make sure the virtualization options are enabled in your BIOS/UEFI configuration.
You may be able to install without the required CPU features for testing purposes only, but VMs (in particular, sys-net) may not function correctly and there will be no security isolation.
For more information, see our post on [updated requirements for Qubes-certified hardware](/news/2016/07/21/new-hw-certification-for-q4/).
For more information, see [Qubes-certified hardware](/doc/certified-hardware/).
### Can I install Qubes OS on a system without VT-x?
### Why is VT-x/AMD-V important?
Yes, for releases 3.2.1 and below.
Xen doesn't use VT-x (or AMD-v) for PV guest virtualization.
(It uses ring0/3 separation instead.)
However, without VT-x, you won't be able to use fully virtualized VMs (e.g., Windows-based qubes), which were introduced in Qubes 2.
In addition, if your system lacks VT-x, then it also lacks VT-d. (See next question.)
By default, Qubes uses Xen's PVH and HVM virtualization modes, which require VT-x/AMD-V.
This means that, without VT-x/AMD-V, no VMs will start in a default Qubes installation.
In addition, if your system lacks VT-x/AMD-V, then it also lacks VT-d/ADM-Vi/AMD IOMMU.
(See next question.)
### Can I install Qubes OS on a system without VT-d?
Yes, for releases 3.2.1 and below.
You can even run a NetVM, but you will not benefit from DMA protection for driver domains.
On a system without VT-d, everything should work in the same way, except there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple DMA attack to go from the NetVM to Dom0.
**Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d.
Therefore, a system running Qubes will still be significantly more secure than one running Windows, Mac, or Linux, even if it lacks VT-d.**
### Why is VT-d/ADM-Vi/AMD IOMMU important?
On a system without VT-d/ADM-Vi/AMD IOMMU, there will be no real security benefit to having a separate NetVM, as an attacker could always use a simple [DMA attack](#what-is-a-dma-attack) to go from the NetVM to Dom0.
Nonetheless, all of Qubes' other security mechanisms, such as qube separation, work without VT-d/ADM-Vi/AMD IOMMU.
Therefore, a system running Qubes without VT-d/ADM-Vi/AMD IOMMU would still be significantly more secure than one running Windows, Mac, or Linux.
### What is a DMA attack?
DMA is mechanism for PCI devices to access system memory (read/write).
Without VT-d, any PCI device can access all the memory, regardless to which VM it is assigned (or if it is left in dom0).
Direct Memory Access (DMA) is mechanism for PCI devices to access system memory (read/write).
Without VT-d/ADM-Vi/AMD IOMMU, any PCI device can access all the memory, regardless of the VM to which it is assigned (or if it is left in dom0).
Most PCI devices allow the driver to request an arbitrary DMA operation (like "put received network packets at this address in memory", or "get this memory area and send it to the network").
So, without VT-d, it gives unlimited access to the whole system.
So, without VT-d/ADM-Vi/AMD IOMMU, it gives unlimited access to the whole system.
Now, it is only a matter of knowing where to read/write to take over the system, instead of just crashing.
But since you can read the whole memory, it isn't that hard.
Now, how does this apply to Qubes OS?
The above attack requires access to a PCI device, which means that it can be performed only from NetVM / UsbVM, so someone must first break into one of those VMs.
The above attack requires access to a PCI device, which means that it can be performed only from the NetVM or USB VM, so someone must first break into one of those VMs.
But this isn't that hard, because there is a lot of complex code handling network traffic.
Recent bugs include DHCP client, DNS client, etc.
Most attacks on NetVM / UsbVM (but not all!) require being somewhat close to the target system - for example connected to the same WiFi network, or in the case of a UsbVM, having physical access to a USB port.
There is a history of bugs in DHCP clients, DNS clients, etc.
Most attacks on the NetVM and USB VM (but not all of them!) require being somewhat close to the target system, for example, being connected to the same Wi-Fi network, or in the case of a USB VM, having physical access to a USB port.
### Can I use AMD-v instead of VT-x?
@ -445,12 +441,9 @@ It begins with an explanation of the risks with such a setup.
See [here][version].
### My qubes lost Internet access after a TemplateVM update. What should I do?
### My qubes lost internet access after a TemplateVM update. What should I do?
Run `systemctl enable NetworkManager-dispatcher.service` in the TemplateVM upon which your NetVM is based.
You may have to reboot afterward for the change to take effect.
(Note: This is an upstream problem. See [here](https://bugzilla.redhat.com/show_bug.cgi?id=974811)).
For details, see the qubes-users mailing list threads [here](https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion) and [here](https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion).)
See [Update Troubleshooting](/doc/update-troubleshooting/#lost-internet-access-after-a-templatevm-update).
### My keyboard layout settings are not behaving correctly. What should I do?
@ -611,34 +604,11 @@ From a `dom0` prompt, enter:
### When I try to install a TemplateVM, it says no match is found.
For example:
```
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10
Using sys-whonix as UpdateVM to download updates for Dom0; this may take some time...
No Match for argument qubes-template-debian-10
Nothing to download
```
This normally means you already have the template installed.
It may be that you have the matching package installed, but you removed or renamed the template.
Check `rpm -q qubes-template-<name>`.
If it lists the package, but you don't really have the template present (`qvm-ls` doesn't list it), you need to clean up leftovers of the package with `rpm -e --noscripts qubes-template-<name>`, then install it normally.
See [VM Troubleshooting](/doc/vm-troubleshooting/#no-match-found-when-trying-to-install-a-templatevm).
### I keep getting "Failed to synchronize cache for repo" errors when trying to update my Fedora templates
This is general Fedora issue, not a Qubes-specific issue.
Usually, this is due to network problems (especially if downloading updates over Tor) or problems with the download mirrors.
Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later.
Here are some examples of non-Qubes reports about this problem:
- <https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/>
- <https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update>
- <https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/>
- <https://bugzilla.redhat.com/show_bug.cgi?id=1494178>
- <https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates>
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.
See [Update Troubleshooting](/doc/update-troubleshooting/#failed-to-synchronize-cache-for-repo-errors-when-updating-fedora-templates).
### I see a "Failed to start Load Kernel Modules" message on boot
@ -798,7 +768,7 @@ There is also the unofficial [ansible-qubes toolkit][ansible].
[shell]: https://en.wikipedia.org/wiki/Shell_(computing)
[Should I trust this website?]: #should-i-trust-this-website
[storage]: /doc/block-devices/
[System Requirements]: /doc/system-requirements/
[system requirements]: /doc/system-requirements/
[Tails]: https://tails.boum.org/
[Template]: /doc/template-implementation
[terminal emulator]: https://en.wikipedia.org/wiki/Terminal_emulator

5
introduction/reporting-bugs.md
View File

@ -74,7 +74,9 @@ The Qubes team will classify your issue according to its type.
### New issues should include all relevant information ###
When you file a new issue, you should be sure to include the version of Qubes you're using, as well as versions of related software packages ([how to copy information out of dom0]).
If your issue is related to hardware, provide as many details as possible about the hardware, which could include using command-line tools such as `lspci`.
If your issue is related to hardware, provide as many details as possible about the hardware.
A great way to do this is by [generating and submitting a Hardware Compatibility List (HCL) report][hcl-howto], then linking to it in your issue.
You may also need to use command-line tools such as `lspci`.
If you're reporting a bug in a package that is in a [testing] repository, please reference the appropriate issue in the [updates-status] repository.
Project maintainers really appreciate thorough explanations.
It usually helps them address the problem more quickly, so everyone wins!
@ -143,4 +145,5 @@ If the issue is closed without one of these specific resolutions, then it means,
[Contributing Code]: /doc/contributing/#contributing-code
[Package Contributions]: /doc/package-contributions/
[Documentation Guidelines]: /doc/doc-guidelines/
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports

7
introduction/support.md
View File

@ -101,8 +101,10 @@ over you and help someone else who gets right to the point.
Tell us what you've already tried, and which
documentation pages you've already read. Put yourself in your readers' shoes.
What essential information would they require in order to be able to help
you? Make sure to include that information in your message. [Ask
questions the smart way.][smart-questions]
you? Make sure to include that information in your message. A great way to
provide your hardware details is by [generating and submitting a Hardware
Compatibility List (HCL) report][hcl-howto], then linking to it in your
message. [Ask questions the smart way.][smart-questions]
### Be patient ###
@ -448,4 +450,5 @@ The following unofficial chat channels are maintained by the community:
[free hosting for open source projects]: https://blog.discourse.org/2018/11/free-hosting-for-open-source-v2/
[IRC]: #unofficial-chat-channels
[Reddit]: https://www.reddit.com/r/Qubes/
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-report

126
project-security/verifying-signatures.md
View File

@ -58,16 +58,17 @@ If you run into any problems, please consult the [Troubleshooting FAQ] below.
Before we begin, you'll need a program that can verify PGP signatures.
Any such program will do, but here are some examples for popular operating systems:
**Windows:** [Gpg4win](https://gpg4win.org/download.html).
**Windows:** [Gpg4win](https://gpg4win.org/download.html) ([documentation](https://www.gpg4win.org/documentation.html)).
Use the Windows command line (`cmd.exe`) to enter commands.
**Mac:** [GPG Suite](https://gpgtools.org/).
**Mac:** [GPG Suite](https://gpgtools.org/) ([documentation](https://gpgtools.tenderapp.com/kb)).
Open a terminal to enter commands.
**Linux:** `gpg2` from your package manager or from [gnupg.org](https://gnupg.org/download/index.html).
**Linux:** `gpg2` from your package manager or from [gnupg.org](https://gnupg.org/download/index.html) ([documentation](https://www.gnupg.org/documentation/)).
Open a terminal to enter commands.
The commands below will use `gpg2`, but if that doesn't work for you, try `gpg` instead.
If that still doesn't work, please consult the documentation for your specific program (see links above).
### 1. Get the Qubes Master Signing Key and verify its authenticity
@ -83,6 +84,12 @@ There are several ways to get the Qubes Master Signing Key.
$ gpg2 --import /usr/share/qubes/qubes-master-key.asc
- If you're on Fedora, you can get it in the `distribution-gpg-keys` package:
$ dnf install distribution-gpg-keys
- If you're on Debian, it may already be included in your keyring.
- Fetch it with GPG:
$ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc
@ -91,38 +98,55 @@ There are several ways to get the Qubes Master Signing Key.
$ gpg2 --import ./qubes-master-signing-key.asc
- Get it from a public [keyserver] (specified on first use with `--keyserver <URI>`, then saved in `~/.gnupg/gpg.conf`), e.g.:
- Get it from a public [keyserver] (specified on first use with `--keyserver <URI>` along with keyserver options to include key signatures), e.g.:
$ gpg2 --keyserver pool.sks-keyservers.net --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
$ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://pool.sks-keyservers.net:11371 --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
The Qubes Master Signing Key is also available in the [Qubes Security Pack] and in the archives of the project's [developer][devel-master-key-msg] and [user][user-master-key-msg] [mailing lists].
Once you have obtained the Qubes Master Signing Key, you should verify the fingerprint of this key very carefully by obtaining copies of the fingerprint from multiple independent sources and comparing them to the downloaded key's fingerprint to ensure they match.
Here are some ideas:
Once you have obtained the Qubes Master Signing Key, you must verify that it is authentic rather than a forgery.
Anyone can create a PGP key with the name "Qubes Master Signing Key," so you cannot rely on the name alone.
You also should not rely on any single website, not even over HTTPS.
- Use the PGP Web of Trust.
- Check the key against different keyservers.
- Use different search engines to search for the fingerprint.
- Use Tor to view and search for the fingerprint on various websites.
- Use various VPNs and proxy servers.
- Use different Wi-Fi networks (work, school, internet cafe, etc.).
- Ask people to post the fingerprint in various forums and chat rooms.
- Check against PDFs and photographs in which the fingerprint appears
(e.g., slides from a talk or on a T-shirt).
- Repeat all of the above from different computers and devices.
So, what *should* you do?
One option is to use the PGP [Web of Trust](https://en.wikipedia.org/wiki/Web_of_trust).
In addition, some operating systems include the means to acquire the Qubes Master Signing Key in a secure way.
For example, on Fedora, `dnf install distribution-gpg-keys` will get you the Qubes Master Signing Key along with several other Qubes keys.
On Debian, your keyring may already contain the necessary keys.
In addition, some operating systems have built-in keyrings containing keys capable of validating the Qubes Master Signing Key.
For example, if you have a Debian system, then your keyring may already contain the necessary keys.
Another option is to rely on the key's fingerprint.
Every PGP key has a fingerprint that uniquely identifies it among all PGP keys (viewable with `gpg2 --fingerprint <KEY_ID>`).
Therefore, if you know the genuine Qubes Master Signing Key fingerprint, then you always have an easy way to confirm whether any purported copy of it is authentic, simply by comparing the fingerprints.
For additional security, we also publish the fingerprint of the Qubes Master Signing Key here (but [remember not to blindly trust the live version of this website][website-trust]):
For example, here is the Qubes Master Signing Key fingerprint:
pub 4096R/36879494 2010-04-01
Key fingerprint = 427F 11FD 0FAA 4B08 0123 F01C DDFA 1A3E 3687 9494
uid Qubes Master Signing Key
Once you're confident that you have the legitimate Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys).
But how do you know that this is the real fingerprint?
After all, [this website could be compromised][website-trust], so the fingerprint you see here may not be genuine.
That's why we strongly suggest obtaining the fingerprint from *multiple, independent sources in several different ways*.
$ gpg2 --edit-key 0x36879494
Here are some ideas for how to do that:
- Check the fingerprint on various websites (e.g., [mailing lists](https://groups.google.com/g/qubes-devel/c/RqR9WPxICwg/m/kaQwknZPDHkJ), [discussion forums](https://qubes-os.discourse.group/t/there-is-no-way-to-validate-qubes-master-signing-key/1441/9?u=adw), [social](https://twitter.com/rootkovska/status/496976187491876864) [media](https://www.reddit.com/r/Qubes/comments/5bme9n/fingerprint_verification/), [personal websites](https://andrewdavidwong.com/fingerprints.txt)).
- Check against PDFs, photographs, and videos in which the fingerprint appears
(e.g., [slides from a talk](https://hyperelliptic.org/PSC/slides/psc2015_qubesos.pdf), on a [T-shirt](https://twitter.com/legind/status/813847907858337793/photo/2), or in the [recording of a presentation](https://youtu.be/S0TVw7U3MkE?t=2563)).
- Download old Qubes ISOs from different sources and check the included Qubes Master Signing Key.
- Ask people to post the fingerprint on various mailing lists, forums, and chat rooms.
- Repeat the above over Tor.
- Repeat the above over various VPNs and proxy servers.
- Repeat the above on different networks (work, school, internet cafe, etc.).
- Text, email, call, video chat, snail mail, or meet up with people you know to confirm the fingerprint.
- Repeat the above from different computers and devices.
Once you've obtained the fingerprint from enough independent sources in enough different ways that you feel confident that you know the genuine fingerprint, keep it in a safe place.
Every time you need to check whether a key claiming to be the Qubes Master Signing Key is authentic, compare that key's fingerprint to your trusted copy and confirm they match.
Now that you've imported the authentic Qubes Master Signing Key, set its trust level to "ultimate" so that it can be used to automatically verify all the keys signed by the Qubes Master Signing Key (in particular, Release Signing Keys).
$ gpg2 --edit-key 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494
gpg (GnuPG) 1.4.18; Copyright (C) 2014 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
@ -164,15 +188,29 @@ Once you're confident that you have the legitimate Qubes Master Signing Key, set
Now, when you import any of the legitimate Qubes developer keys and Release Signing Keys used to sign ISOs, RPMs, TGZs, Git tags, and Git commits, they will already be trusted in virtue of being signed by the Qubes Master Signing Key.
Before proceeding to the next step, make sure the Qubes Master Signing Key is in your keyring with the correct trust level.
(Note: We have already verified the authenticity of the key, so this final check is not about security.
Rather, it's just a sanity check to make sure that we've imported the key into our keyring correctly.)
$ gpg2 -k "Qubes Master Signing Key"
pub rsa4096 2010-04-01 [SC]
427F11FD0FAA4B080123F01CDDFA1A3E36879494
uid [ultimate] Qubes Master Signing Key
If you don't see the Qubes Master Signing Key here with a trust level of "ultimate," go back and follow the instructions in this section carefully.
### 2. Get the Release Signing Key
The filename of the Release Signing Key for your version is `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release.
The filename of the Release Signing Key for your version is usually `qubes-release-X-signing-key.asc`, where `X` is the major version number of your Qubes release.
There are several ways to get the Release Signing Key for your Qubes release.
- If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/`.
- If you have access to an existing Qubes installation, the release keys are available in dom0 in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
These can be [copied][copy-from-dom0] into other VMs for further use.
In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/`.
In addition, every other VM contains the release key corresponding to that installation's release in `/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*`.
If you wish to use one of these keys, make sure to import it into your keyring, e.g.:
$ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*
- Fetch it with GPG:
@ -197,13 +235,19 @@ The Release Signing Key should be signed by the Qubes Master Signing Key:
gpg: 2 good signatures
This is just an example, so the output you receive will not look exactly the same.
What matters is the line that shows that this key is signed by the Qubes Master
Signing Key with a `sig!` prefix. This verifies the authenticity of the
Release Signing Key. Note that the `!` flag after the `sig` tag is important
because it means that the key signature is valid. A `sig-` prefix would
indicate a bad signature and `sig%` would mean that gpg encountered an error
while verifying the signature.
It is not necessary to independently verify the authenticity of the Release Signing Key.
What matters is the line that shows that this key is signed by the Qubes Master Signing Key with a `sig!` prefix.
This verifies the authenticity of the Release Signing Key.
Note that the `!` flag after the `sig` tag is important because it means that the key signature is valid.
A `sig-` prefix would indicate a bad signature and `sig%` would mean that gpg encountered an error while verifying the signature.
It is not necessary to independently verify the authenticity of the Release Signing Key, since you already verified the authenticity of the Qubes Master Signing Key.
Before proceeding to the next step, make sure the Release Signing Key is in your keyring:
$ gpg2 -k "Qubes OS Release"
pub rsa4096 2017-03-06 [SC]
5817A43B283DE5A9181A522E1848792F9E2795E9
uid [ full ] Qubes OS Release X Signing Key
If you don't see the correct Release Signing Key here, go back and follow the instructions in this section carefully.
### 3. Verify your Qubes ISO
@ -212,7 +256,9 @@ Every Qubes ISO is released with a detached PGP signature file, which you can fi
If the filename of your ISO is `Qubes-RX-x86_64.iso`, then the name of the signature file for that ISO is `Qubes-RX-x86_64.iso.asc`, where `X` is a specific version of Qubes.
The signature filename is always the same as the ISO filename followed by `.asc`.
Once you've downloaded both the ISO and its signature file, you can verify the ISO using GPG:
Download both the ISO and its signature file.
Put both of them in the same directory, then navigate to that directory.
Now, you can verify the ISO by executing this GPG command in the directory that contains both files:
$ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso
gpg: armor header: Version: GnuPG v1
@ -301,8 +347,8 @@ Another way is to use `openssl` to compute each hash value, then compare them to
(Notice that the outputs match the values from the digest file.)
However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a malicious ISO, computed the hash values for that ISO, and replaced the values in `Qubes-RX-x86_64.iso.DIGESTS` with his own set of values.
Therefore, ideally, we should also verify the authenticity of the listed hash values.
However, it is possible that an attacker replaced `Qubes-RX-x86_64.iso` with a malicious ISO, computed the hash values for that malicious ISO, and replaced the values in `Qubes-RX-x86_64.iso.DIGESTS` with his own set of values.
Therefore, we should also verify the authenticity of the listed hash values.
Since `Qubes-RX-x86_64.iso.DIGESTS` is a clearsigned PGP file, we can use GPG to verify it from the command line:
1. [Get the Qubes Master Signing Key and verify its authenticity][QMSK]
@ -376,10 +422,16 @@ The problem could be one or more of the following:
If you still get the same result, try downloading the ISO again from a different source, then try verifying again.
### I'm getting "bash: gpg2: command not found"
### Why am I getting "bash: gpg2: command not found"?
You don't have `gpg2` installed.
Please install it using the method appropriate for your environement (e.g., via your package manager).
Please install it using the method appropriate for your environment (e.g., via your package manager).
### Why am I getting "No such file or directory"?
Your working directory does not contain the required files.
Go back and follow the instructions more carefully, making sure that you put all required files in the same directory *and* navigate to that directory.
### Why am I getting "can't open signed data `Qubes-RX-x86_64.iso' / can't hash datafile: file open error"?

6
user/advanced-configuration/disposablevm-customization.md
View File

@ -15,9 +15,9 @@ redirect_from:
## Introduction
A DisposableVM (previously known as a "DispVM") in can be based on any TemplateBasedVM.
You can also choose to use different DisposableVM Templates for different DisposableVMs.
To prepare AppVM to be a DisposableVM Template, you need to set `template_for_dispvms` property, for example:
A [DisposableVM](/doc/disposablevm) can be based on any [TemplateBasedVM](/doc/glossary/#templatebasedvm).
You can also choose to use different [DisposableVM Templates](/doc/glossary/#disposablevm-template) for different DisposableVMs.
To prepare an AppVM to be a DisposableVM Template, you need to set `template_for_dispvms` property, for example:
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True

84
user/common-tasks/copy-from-dom0.md
View File

@ -9,67 +9,71 @@ redirect_from:
- /wiki/CopyToDomZero/
---
Copying from (and to) dom0
==========================
# Copying from (and to) dom0
Copying **from** dom0
---------------------
This page covers copying files and clipboard text between [dom0](/doc/glossary/#dom0) and [domUs](/doc/glossary/#domu).
Since dom0 is special, the processes are different from [copying and pasting text between qubes](/doc/copy-paste/) and [copying and moving files between qubes](/doc/copying-files/).
To copy a file from dom0 to a VM (domU), simply use `qvm-copy-to-vm`:
## Copying **from** dom0
~~~
qvm-copy-to-vm <dest-vm> <file>
~~~
### Copying files from dom0
The file will arrive in your destination VM in the `~/QubesIncoming/dom0/` directory.
To copy a file from dom0 to a VM, simply use `qvm-copy-to-vm`:
### Copying logs from dom0 ###
qvm-copy-to-vm <target_vm> <file>
The file will arrive in the target VM in the `/home/user/QubesIncoming/dom0/` directory.
### Copying and pasting clipboard text from dom0
Use the **Qubes Clipboard** widget:
1. Copy text to the clipboard normally in dom0 (e.g., by pressing Ctrl+C).
2. Click the **Qubes Clipboard** icon in the Notification Area.
3. Click "Copy dom0 clipboard".
This displays a notification that text has been copied to the inter-qube clipboard.
4. Press Ctrl+Shift+V in the target qube.
This pastes the inter-qube clipboard contents into the target qube's normal clipboard.
5. Paste normally within that qube (e.g., by pressing Shift+V).
Alternatively, you can put your text in a file, then [copy it as a file](#copying-files-from-dom0).
Or, you can write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`.
Then use Ctrl+Shift+V to paste the data to the target qube.
### Copying logs from dom0
In order to easily copy/paste the contents of logs from dom0 to the inter-VM clipboard, you can simply:
1. Right-click on the desired VM in the Qubes VM Manager.
2. Click "Logs."
3. Click on the desired log.
4. Click "Copy to Qubes clipboard."
1. Right-click on the desired qube in the Qube Manager.
You may now paste the log contents to any VM as you normally would (i.e., Ctrl-Shift-V, then Ctrl-V).
2. Click "Logs."
### Copy/paste from dom0 ###
3. Click on the desired log.
For data other than logs, there are several options:
4. Click "Copy to Qubes clipboard."
1. Use the **Qubes Clipboard** widget:
- Copy text to the clipboard normally in dom0.
- Click the **Qubes Clipboard** icon in the Notification Area.
- Click "Copy dom0 clipboard".
- Receive a notification that text has been copied to the inter-qube clipboard.
- Press Ctrl + Shift + V in a qube to paste into the desired qube's clipboard.
- Paste normally within that qube.
2. Copy it as a file (see above)
3. Write the data you wish to copy into `/var/run/qubes/qubes-clipboard.bin`, then `echo -n dom0 > /var/run/qubes/qubes-clipboard.bin.source`.
Then use Ctrl-Shift-V to paste the data to the desired VM.
You may now paste the log contents in qube as you normally would (e.g., Ctrl+Shift+V, then Ctrl+V).
Copying **to** dom0
-------------------
## Copying **to** dom0
Copying anything into dom0 is not advised, since doing so can compromise the security of your Qubes system.
For this reason, there is no simple means of copying anything into dom0, unlike [copying from dom0](#copying-from-dom0) and [copying files between VMs](/doc/copying-files/).
For this reason, there is no simple means of copying anything into dom0, unlike [copying from dom0](#copying-from-dom0).
There should normally be few reasons for the user to want to copy anything from VMs to dom0, as dom0 only acts as a "thin trusted terminal", and no user applications run there.
One possible use-case for this is if we want to use a desktop wallpaper in dom0 we have located in one of our AppVMs (e.g. in the 'personal' AppVM where we got the wallpaper from our camera or downloaded it from the Internet).
While this use-case is understandable, imagine what would happen if the wallpaper (e.g. a JPEG file) was somehow malformed or malicious and attempted to exploit a hypothetical JPEG parser bug in dom0 code (e.g. in the dom0's Xorg/KDE code that parses the wallpaper and displays it).
There should normally be few reasons for the user to want to copy anything from domUs to dom0, as dom0 only acts as a "thin trusted terminal", and no user applications run there.
Sometimes, new users feel the urge to copy a desktop wallpaper image into dom0, but that is not necessary.
A safer approach is simply to display the image in [full-screen mode](/doc/full-screen-mode/) in an AppVM, then take a screenshot from dom0, which results in exactly the image needed for a wallpaper, created securely and natively in dom0.
If you are determined to copy some files to dom0 anyway, you can use the following method.
(If you want to copy text, first save it into a text file.)
Run this command in a dom0 terminal:
~~~
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
~~~
qvm-run --pass-io <src-vm> 'cat /path/to/file_in_src_domain' > /path/to/file_name_in_dom0
Note that you can use the same method to copy files from dom0 to VMs (if, for some reason, you don't want to use `qvm-copy-to-vm`):
Note that you can use the same method to copy files from dom0 to domUs (if, for some reason, you don't want to use `qvm-copy-to-vm`):
~~~
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'
~~~
cat /path/to/file_in_dom0 | qvm-run --pass-io <dest-vm> 'cat > /path/to/file_name_in_appvm'

66
user/common-tasks/copy-paste.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Copy and Paste
title: Copying and pasting text between qubes
permalink: /doc/copy-paste/
redirect_from:
- /en/doc/copy-paste/
@ -8,51 +8,49 @@ redirect_from:
- /wiki/CopyPaste/
---
Copy and Paste between domains
==============================
Copying and pasting text between qubes
======================================
Qubes fully supports secure copy and paste operation between domains.
In order to copy a clipboard from domain A to domain B, follow those steps:
*This page is about copying and pasting plain text.
If you wish to copy more complex data, such as rich text or images, see [copying and moving files between qubes](/doc/copying-files/).
For dom0, see [copying from (and to) dom0](/doc/copy-from-dom0/).*
1. Click on the application window in domain A where you have selected text for copying.
Then use the *app-specific* hot-key (or menu option) to copy this into domain's local clipboard (in other words: do the copy operation as usual, in most cases by pressing Ctrl-C).
2. Then (when the app in domain A is still in focus) press Ctrl-Shift-C magic hot-key.
This will tell Qubes that we want to select this domain's clipboard for *global copy* between domains.
3. Now select the destination app, running in domain B, and press Ctrl-Shift-V, another magic hot-key that will tell Qubes to make the clipboard marked in the previous step available to apps running in domain B.
This step is necessary because it ensures that only domain B will get access to the clipboard copied from domain A, and not any other domain that might be running in the system.
4. Now, in the destination app use the app-specific key combination (usually Ctrl-V) for pasting the clipboard.
Qubes OS features a secure inter-qube clipboard that allows you to copy and paste text between qubes.
Note that the global clipboard will be cleared after step \#3, to prevent accidental leakage to another domain, if the user accidentally pressed Ctrl-Shift-V later.
In order to copy text from qube A to qube B:
This 4-step process might look complex, but after some little practice it really is very easy and fast.
At the same time it provides the user with full control over who has access to the clipboard.
1. Select text from the source app in qube A, then copy it normally (e.g., by pressing Ctrl+C).
Note that only simple plain text copy/paste is supported between AppVMs.
This is discussed in a bit more detail in [this message](https://groups.google.com/group/qubes-devel/msg/57fe6695eb8ec8cd).
2. With the source app in qube A still in focus, press Ctrl+Shift+C.
This copies the text from qube A's clipboard to the inter-qube clipboard.
On Copy/Paste Security
----------------------
3. Select the target app in qube B and press Ctrl+Shift+V.
This copies the text from the inter-qube clipboard to qube B's clipboard and clears the inter-qube clipboard, ensuring that only qube B will have access to the copied text.
The scheme is *secure* because it doesn't allow other VMs to steal the content of the clipboard.
However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* domain can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination VM (e.g.
the seemingly innocent link that we copy from untrusted domain, might turn out to be, in fact, a large buffer of junk that, when pasted into the destination VM's word processor could exploit a hypothetical bug in the undo buffer).
This is a general problem and applies to any data transfer between *less trusted to more trusted* domains.
It even applies to copying files between physically separate machines (air-gapped) systems.
So, you should always copy clipboard and data only from *more trusted* to *less trusted* domains.
4. Paste the text in the target app in qube B normally (e.g., by pressing Ctrl+V).
See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.
This process might look complicated at first glance, but in practice it is actually very easy and fast once you get used to it.
At the same time, it provides you with full control over exactly which qube receives the content of the inter-qube clipboard every time.
And [this message](https://groups.google.com/group/qubes-devel/msg/48b4b532cee06e01) from qubes-devel.
Security
--------
Copy/Paste between dom0 and other domains
-----------------------------------------
The inter-qube clipboard system is secure because it doesn't allow any qube other than your selected target to steal any contents from the inter-qube clipboard.
Without such a system in place, any password you were to copy from the password manager in your vault qube to another qube, for example, would immediately be leaked to every other running qube in the system, including qubes that are untrusted by default, such as `sys-net`.
By giving you precise control over exactly which qube receives the inter-qube clipboard content, then immediately wiping the inter-qube clipboard afterward, Qubes OS protects the confidentiality of the text being copied.
See ["Copying from (and to) dom0"](/doc/copy-from-dom0/).
However, one should keep in mind that performing a copy and paste operation from *less trusted* to *more trusted* qube is always potentially insecure, since the data that we copy could exploit some hypothetical bug in the target qube.
For example, the seemingly-innocent link that we copy from an untrusted qube could turn out to be a large buffer of junk that, when pasted into the target qube's word processor, could exploit a hypothetical bug in the undo buffer.
This is a general problem and applies to any data transfer from *less trusted* to *more trusted* qubes.
It even applies to copying files between physically separate (air-gapped) machines.
Therefore, you should always copy clipboard data only from *more trusted* to *less trusted* qubes.
See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes, as well as [this message](https://groups.google.com/group/qubes-devel/msg/48b4b532cee06e01) from qubes-devel.
Clipboard automatic policy enforcement
--------------------------------------
The Qubes clipboard [RPC policy] is configurable in:
The Qubes clipboard [RPC policy](/doc/rpc-policy/) is configurable in:
~~~
/etc/qubes-rpc/policy/qubes.ClipboardPaste
@ -66,7 +64,7 @@ For example, if you are certain that you never wish to paste *into* your "vault"
@anyvm @anyvm ask
~~~
Shortcut Configuration
Shortcut configuration
----------------------
The copy/paste shortcuts are configurable in:
@ -78,7 +76,3 @@ The copy/paste shortcuts are configurable in:
If you edit a line in this file, you must uncomment it (by removing the initial `#` character), or else it will have no effect.
VMs need to be restarted in order for changes in `/etc/qubes/guid.conf` to take effect.
[RPC policy]: /doc/rpc-policy/

56
user/common-tasks/copying-files.md
View File

@ -1,6 +1,6 @@
---
layout: doc
title: Copying Files between qubes
title: Copying and moving files between qubes
permalink: /doc/copying-files/
redirect_from:
- /en/doc/copying-files/
@ -8,31 +8,34 @@ redirect_from:
- /wiki/CopyingFiles/
---
Copying files and folders between qubes
=============================
Copying and moving files between qubes
======================================
Qubes also supports secure copying of files and folders between qubes.
These instructions refer to file(s) but equally apply to copying folders.
*This page is about copying and moving files.
If you wish to simply copy and paste text, that can be done more easily using the inter-qube clipboard.
See [copying and pasting text between qubes](/doc/copy-paste/).
For dom0, see [copying from (and to) dom0](/doc/copy-from-dom0/).*
In order to copy file(s) from qube A to qube B, follow these steps:
Qubes OS supports the secure copying and moving of files and directories (folders) between qubes.
GUI
---
For simplicity, these instructions will refer to copying/moving a single file, but they apply equally well to groups of files and directories, which are copied recursively.
1. Open file manager in the source qube (qube A), choose file(s) that you wish to copy, and right click on the selection, and choose `Copy to another AppVM`
1. Open a file manager in the qube containing the file you wish to copy (the source qube), right-click on the file you wish to copy or move, and select `Copy to Other AppVM...` or `Move to Other AppVM...`.
2. A dialog box will appear asking for the name of the destination qube (qube B).
2. A dialog box will appear in dom0 asking for the name of the target qube (qube B).
Enter or select the desired destination qube name.
3. A confirmation dialog box will appear(this will be displayed by Dom0, so none of the qubes can fake your consent).
After you click ok, qube B will be started if it is not already running, the file copy operation will start, and the files will be copied into the following folder in qube B:
3. If the target qube is not already running, it will be started automatically, and the file will be copied there.
It will show up in this directory (which will automatically be created if it does not already exist):
`/home/user/QubesIncoming/<source>`
/home/user/QubesIncoming/<source_qube>/<filename>
4. You can now move them whenever you like in the qube B filesystem using the file manager there.
If you selected **Move** rather than **Copy**, the original file in the source qube will be deleted.
(Moving a file is equivalent to copying the file, then deleting the original.)
4. If you wish, you may now move the file in the target qube to a different directory and delete the `/home/user/QubesIncoming/` directory when no longer needed.
CLI
---
The same operations are also available via these command-line tools:
```
qvm-copy [--without-progress] file [file]+
@ -42,18 +45,21 @@ qvm-copy [--without-progress] file [file]+
qvm-move [--without-progress] file [file]+
```
Security
--------
On inter-qube file copy security
----------------------------------
The scheme is *secure* because it doesn't allow other qubes to steal the files that are being copied, and also doesn't allow the source qube to overwrite arbitrary files on the destination qube.
Also, Qubes's file copy scheme doesn't use any sort of virtual block devices for file copy -- instead we use Xen shared memory, which eliminates lots of processing of untrusted data.
The inter-qube file copy system is secure because it doesn't allow other qubes to steal the files that are being copied, and it doesn't allow the source qube to overwrite arbitrary files on the destination qube.
Moreover, this system doesn't use any sort of virtual block device for file copy.
Instead, we use Xen shared memory, which eliminates a lot of processing of untrusted data.
For example, the receiving qube is *not* forced to parse untrusted partitions or file systems.
In this respect our file copy mechanism provides even more security than file copy between two physically separated (air-gapped) machines!
In this respect, the inter-qube file copy system provides even more security than file copy between two physically separated (air-gapped) machines!
(See [Software compartmentalization vs. physical separation](https://invisiblethingslab.com/resources/2014/Software_compartmentalization_vs_physical_separation.pdf) for more on this.)
However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes can always be potentially insecure, because the data that we insert might potentially try to exploit some hypothetical bug in the destination qube (e.g. a seemingly innocent JPEG that we copy from an untrusted qube might contain a specially crafted exploit for a bug in JPEG parsing application in the destination qube).
This is a general problem and applies to any data transfer between *less trusted to more trusted* qubes.
However, one should keep in mind that performing a data transfer from *less trusted* to *more trusted* qubes is always potentially insecure if the data will be parsed in the target qube.
This is because the data that we copy could try to exploit some hypothetical bug in software running in the target qube.
For example, a seemingly-innocent JPEG that we copy from an untrusted qube might contain a specially-crafted exploit for a bug in a JPEG-parsing application in the target qube.
This is a general problem and applies to any data transfer from *less trusted* to *more trusted* qubes.
It even applies to the scenario of copying files between air-gapped machines.
So, you should always copy data only from *more trusted* to *less trusted* qubes.
Therefore, you should always copy data only from *more trusted* to *less trusted* qubes.
See also [this article](https://blog.invisiblethings.org/2011/03/13/partitioning-my-digital-life-into.html) for more information on this topic, and some ideas of how we might solve this problem in some future version of Qubes.

20
user/common-tasks/disposablevm.md
View File

@ -59,7 +59,7 @@ You can change this behaviour for individual VMs: in the Application Menu, open
Here you can edit the "Default DisposableVM" setting to specify which DisposableVM Template will be used to launch DisposableVMs from that VM.
This can also be changed from the command line with:
qvm-prefs <vmname> default_dispvm <dvmtemplatename>
qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an AppVM that has also been configured as a DisposableVM Template to use itself, so DisposableVMs launched from within the AppVM/DisposableVM Template would inherit the same settings.
@ -82,9 +82,9 @@ Some DisposableVM Templates will automatically create a menu item to launch a DV
qvm-features deb-dvm appmenus-dispvm 1
To launch a DVM from the command line, in dom0 please type the following:
To launch a DisposableVM Template from the command line, in dom0 please type the following:
qvm-run --dispvm=NameOfDVM --service qubes.StartApp+NameOfApp
qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+NameOfApp
## Opening a file in a DisposableVM via GUI ##
@ -141,10 +141,10 @@ Some applications, such as GNOME Terminal, do not wait for the application to cl
It is possible to start an arbitrary application in a DisposableVM directly from dom0 by running:
~~~
$ qvm-run --dispvm=dvm-template --service qubes.StartApp+xterm
$ qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+xterm
~~~
The label color will be inherited from the `dvm-template`.
The label color will be inherited from `<DISPOSABLEVM_TEMPLATE>`.
(The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
@ -156,23 +156,23 @@ Obviously, you can't use the default DisposableVM Template, since it has no netw
You can do that with this command from the `email` qube (as long as your RPC policies allow it):
~~~
$ qvm-open-in-vm @dispvm:online-dvm-template https://www.qubes-os.org
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> https://www.qubes-os.org
~~~
This will create a new DisposableVM based on `online-dvm-template`, open the default web browser in that DisposableVM, and navigate to `https://www.qubes-os.org`.
This will create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`, open the default web browser in that DisposableVM, and navigate to `https://www.qubes-os.org`.
#### Example of RPC policies to allow this behavior
In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL`
~~~
@anyvm @dispvm:online-dvm-template allow
@anyvm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> allow
~~~
This line means:
- FROM: Any VM
- TO: A DisposableVM based on the `online-dvm-template` TemplateVM
- TO: A DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`
- WHAT: Allow sending an "Open URL" request
In other words, any VM will be allowed to create a new DisposableVM based on `online-dvm-template` and open a URL inside of that DisposableVM.
In other words, any VM will be allowed to create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>` and open a URL inside of that DisposableVM.
More information about RPC policies for DisposableVMs can be found [here][qrexec].

30
user/common-tasks/full-screen-mode.md
View File

@ -14,9 +14,9 @@ Enabling Full Screen Mode for select VMs
What is full screen mode?
-------------------------
Normally Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, ensuring that there are always clearly marked decorations drawn by the trusted Window Manager around each of the VMs window.
Normally, the Qubes GUI virtualization daemon restricts the VM from "owning" the full screen, ensuring that there are always clearly marked decorations drawn by the trusted Window Manager around each of the VMs window.
This allows the user to easily realize to which domain a specific window belongs.
See the [screenshots](/doc/QubesScreenshots/) for better understanding.
See the [screenshots](/doc/QubesScreenshots/) page for examples.
Why is full screen mode potentially dangerous?
----------------------------------------------
@ -26,17 +26,23 @@ If one allowed one of the VMs to "own" the full screen, e.g. to show a movie on
Secure use of full screen mode
------------------------------
However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to show the full desktop, and which cannot be intercepted by the VM.
An example of such a mechanism is the KDE's "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those.
However, it is possible to deal with full screen mode in a secure way assuming there are mechanisms that can be used at any time to switch between windows or show the full desktop and that cannot be intercepted by the VM.
The simplest example is the use of Alt+Tab for switching between windows, which is a shortcut handled by dom0.
Other examples such mechanisms are the KDE "Present Windows" and "Desktop Grid" effects, which are similar to Mac's "Expose" effect, and which can be used to immediately detect potential "GUI forgery", as they cannot be intercepted by any of the VM (as the GUID never passes down the key combinations that got consumed by KDE Window Manager), and so the VM cannot emulate those.
Those effects are enabled by default in KDE once Compositing gets enabled in KDE (System Settings -\> Desktop -\> Enable Desktop Effects), which is recommended anyway.
By default they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
Another option is to use Alt+Tab for switching windows.
This shortcut is also handled by dom0.
By default, they are triggered by Ctrl-F8 and Ctrl-F9 key combinations, but can also be reassigned to other shortcuts.
Enabling full screen mode for select VMs
----------------------------------------
If you want to enable full screen mode for select VMs, you can do that by creating the following entry in the `/etc/qubes/guid.conf` file in Dom0:
You can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen" or pressing `alt` + `f11`.
This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen" or simply press `alt` + `f11`.
For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.
As an alternative to the Xfce4 method, you can enable full screen mode for select VMs by creating the following entry in the `/etc/qubes/guid.conf` file in dom0:
~~~
VM: {
@ -48,7 +54,7 @@ VM: {
The string 'personal' above is an example only and should be replaced by the actual name of the VM for which you want to enable this functionality.
**Note:** There should be only one `VM: {}` block in the file (or you will [get into problems](https://groups.google.com/d/msg/qubes-users/-Yf9yNvTsVI/xXsEm8y2lrYJ))
**Note:** There should be only one `VM: {}` block in the file (or you will [get into problems](https://groups.google.com/d/msg/qubes-users/-Yf9yNvTsVI/xXsEm8y2lrYJ)).
One can also enable this functionality for all the VMs globally in the same file, by modifying the 'global' section:
@ -65,9 +71,3 @@ global: {
Be sure to restart the VM(s) after modifying this file, for the changes to take effect.
**Note:** Regardless of the settings above, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen" or pressing `alt` + `f11`.
This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen" or simply press `alt` + `f11`.
For StandaloneHVMs, you should set the screen resolution in the qube to that of the host, (or larger), *before* setting fullscreen mode in Xfce4.

3
user/common-tasks/software-update-dom0.md
View File

@ -10,7 +10,7 @@ redirect_from:
# Installing and updating software in dom0
Updating dom0 is one of the main steps in [Updating Qubes OS].
Updating [dom0] is one of the main steps in [Updating Qubes OS].
It is very important to keep dom0 up-to-date with the latest [security] updates.
We also publish dom0 updates for various non-security bug fixes and enhancements to Qubes components.
In addition, you may wish to update the kernel, drivers, or libraries in dom0 when [troubleshooting newer hardware].
@ -218,6 +218,7 @@ For example: sys-whonix.
Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix
[dom0]: /doc/glossary/#dom0
[Updating Qubes OS]: /doc/updating-qubes-os/
[security]: /security/
[testing]: /doc/testing/

5
user/downloading-installing-upgrading/installation-guide.md
View File

@ -357,6 +357,10 @@ Frequently updating is one of the best ways to remain secure against new threats
It is extremely important to make regular backups so that you don't lose your data unexpectedly.
The [Qubes backup system] allows you to do this securely and easily.
### Submit your HCL report
Consider giving back to the Qubes community and helping other users by [generating and submitting a Hardware Compatibility List (HCL) report][hcl-howto].
### Get Started
[Get Started] with Qubes, and read more about [Common Tasks] and [Managing Operating Systems within Qubes].
@ -403,5 +407,6 @@ The [Qubes backup system] allows you to do this securely and easily.
[Tor]: https://www.torproject.org/
[TemplateVMs]: /doc/templates/
[advanced configuration]: /doc/#advanced-configuration
[hcl-howto]: /doc/hcl/#generating-and-submitting-new-reports
[Get Started]: /getting-started/

4
user/downloading-installing-upgrading/supported-versions.md
View File

@ -30,7 +30,7 @@ past minor releases, are available from our [download mirrors].
### Note on point releases
Please note that point releases, such as 3.2.1 and 4.0.1, do not designate separate, new versions of Qubes OS.
Rather, they designate their respective major or minor releases, such as 4.0 and 3.2, inclusive of all package updates up to a certain point.
Rather, they designate their respective major or minor releases, such as 3.2 and 4.0, inclusive of all package updates up to a certain point.
For example, installing Release 4.0 and fully updating it results in the same system as installing Release 4.0.1.
Therefore, point releases are not displayed as separate rows on any of the tables on this page.
@ -97,7 +97,7 @@ Qubes support for each [Fedora] TemplateVM ends when that Fedora release reaches
| Fedora 28 | Unsupported |
| Fedora 29 | Unsupported |
| Fedora 30 | Unsupported |
| Fedora 31 | Supported |
| Fedora 31 | Unsupported |
| Fedora 32 | Supported |

7
user/hardware/certified-hardware.md
View File

@ -54,8 +54,8 @@ The benefits of hardware certification include:
## Hardware Certification Requirements
(Please note that these are the requirements for hardware *certification*, *not* the requirements for *running* Qubes 4.
For the latter, please see the [system requirements for Qubes 4].)
(Please note that these are the requirements for hardware *certification*, *not* the requirements for *running* Qubes.
For the latter, please see the [system requirements].)
One of the most important security improvements introduced with the release of Qubes 4.0 was to replace paravirtualization (PV) technology with **hardware-enforced memory virtualization**, which recent processors have made possible thanks to so-called Second Level Address Translation ([SLAT]), also known as [EPT][EPT-enabled CPUs] in Intel parlance.
SLAT (EPT) is an extension to Intel VT-x virtualization, which originally was capable of only CPU virtualization but not memory virtualization and hence required a complex Shadow Page Tables approach.
@ -102,10 +102,9 @@ If you are interested in having your hardware certified, please [contact us].
[version-scheme]: /doc/version-scheme/
[Hardware Testing]: /doc/hardware-testing/
[stateless laptop]: https://blog.invisiblethings.org/2015/12/23/state_harmful.html
[System Requirements]: /doc/system-requirements/
[Hardware Compatibility List]: /hcl/
[Hardware Certification]: #hardware-certification
[system requirements for Qubes 4]: /doc/system-requirements/#qubes-release-4x
[system requirements]: /doc/system-requirements/
[contact us]: mailto:business@qubes-os.org
[SLAT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation
[EPT-enabled CPUs]: https://ark.intel.com/Search/FeatureFilter?productType=processors&ExtendedPageTables=true&MarketSegment=Mobile

82
user/hardware/system-requirements.md
View File

@ -9,7 +9,7 @@ redirect_from:
- /wiki/SystemRequirements/
---
# System Requirements #
# System Requirements
<div class="alert alert-warning" role="alert">
<i class="fa fa-exclamation-triangle"></i>
@ -19,60 +19,42 @@ redirect_from:
We strongly recommend consulting the <a href="/hcl/">Hardware Compatibility List</a> to verify that Qubes can install and run on your specific model in the ways you need it to.
</div>
## Qubes Release 3.x ##
## Minimum
### Minimum ###
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
- [Intel VT-d] or [AMD-Vi (also known as AMD IOMMU)]
- **Memory:** 4 GB RAM
- **Storage:** 32 GB free space
* 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
* 4 GB RAM
* 32 GB disk space
* Legacy boot mode (required for R3.0 and earlier; UEFI is supported beginning with R3.1)
## Recommended
### Recommended ###
- **CPU:** 64-bit Intel or AMD processor (also known as `x86_64`, `x64`, and `AMD64`)
- [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
- [Intel VT-d] or [AMD-Vi (also known as AMD IOMMU)]
- **Memory:** 16 GB RAM
- **Storage:** 128 GB free space
- High-speed solid-state drive strongly recommended
- **Graphics:** Intel integrated graphics processor (IGP) strongly recommended
- Nvidia GPUs may require significant [troubleshooting][nvidia]
- AMD GPUs have not been formally tested, but Radeons (especially RX580 and earlier) generally work well
- **Peripherals:** A non-USB keyboard or multiple USB controllers
- **TPM:** Trusted Platform Module (TPM) with proper BIOS support (required for [Anti Evil Maid])
- **Other:** Satisfaction of all [hardware certification requirements for Qubes 4.x]
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* AMD GPUs have not been formally tested, but Radeons (RX580 and earlier) generally work well
* See the [Hardware Compatibility List]
* [Intel VT-x] or [AMD-V] (required for running HVM domains, such as Windows-based AppVMs)
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)] (required for effective isolation of network VMs)
* TPM with proper BIOS support (required for [Anti Evil Maid])
## Choosing Hardware
## Qubes Release 4.x ##
### Minimum ###
* 64-bit Intel or AMD processor (x86\_64 aka x64 aka AMD64)
* [Intel VT-x] with [EPT] or [AMD-V] with [RVI]
* [Intel VT-d] or [AMD-Vi (aka AMD IOMMU)]
* 4 GB RAM
* 32 GiB disk space
### Recommended ###
* Fast SSD (strongly recommended)
* Intel IGP (strongly preferred)
* Nvidia GPUs may require significant [troubleshooting][nvidia].
* AMD GPUs have not been formally tested, but Radeons (RX580 and earlier) generally work well
* See the [Hardware Compatibility List]
* TPM with proper BIOS support (required for [Anti Evil Maid])
* A non-USB keyboard or multiple USB controllers
* Also consider the [hardware certification requirements for Qubes 4.x].
## Choosing Hardware ##
* Please see the [Hardware Compatibility List] for a compilation of hardware reports generated and submitted by users across various Qubes versions.
- Please see the [Hardware Compatibility List] for a compilation of hardware reports generated and submitted by users across various Qubes versions.
(For more information about the HCL itself, see [here][hcl-doc].)
* See the [Certified Hardware] page.
* See the [Hardware Testing] page.
- See the [Certified Hardware] page.
- See the [Hardware Testing] page.
## Important Notes ##
## Important Notes
* **Installing Qubes in a virtual machine is not recommended, as it uses its own bare-metal hypervisor (Xen).**
* Qubes **can** be installed on systems which do not meet the recommended requirements.
- **Installing Qubes in a virtual machine is not recommended, as it uses its own bare-metal hypervisor (Xen).**
- Qubes **can** be installed on systems which do not meet the recommended requirements.
Such systems will still offer significant security improvements over traditional operating systems, since things like GUI isolation and kernel protection do not require special hardware.
* Qubes **can** be installed on a USB flash drive or external disk, and testing has shown that this works very well. A fast USB 3.0 flash drive is recommended for this.
- Qubes **can** be installed on a USB flash drive or external disk, and testing has shown that this works very well. A fast USB 3.0 flash drive is recommended for this.
(As a reminder, its capacity must be at least 32 GiB.)
Simply plug the flash drive into the computer before booting into the Qubes installer from a separate installation medium, choose the flash drive as the target installation disk, and proceed with the installation normally.
After Qubes has been installed on the flash drive, it can then be plugged into other computers in order to boot into Qubes.
@ -80,8 +62,8 @@ redirect_from:
store) before deciding on which computer to purchase.
(See [hcl-report] for advice on hardware compatibility testing.)
Remember to change the devices assigned to your NetVM and USBVM if you move between different machines.
* [Advice on finding a VT-d capable notebook][vt-d-notebook].
* You can check whether an Intel processor has VT-x and VT-d on [ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors)
- [Advice on finding a VT-d capable notebook][vt-d-notebook].
- You can check whether an Intel processor has VT-x and VT-d on [ark.intel.com](https://ark.intel.com/content/www/us/en/ark.html#@Processors).
[nvidia]: /doc/install-nvidia-driver/
@ -92,13 +74,11 @@ redirect_from:
[hcl-doc]: /doc/hcl/
[hcl-report]: /doc/hcl/#generating-and-submitting-new-reports
[Anti Evil Maid]: /doc/anti-evil-maid/
[live USB]: /doc/live-usb/
[#230]: https://github.com/QubesOS/qubes-issues/issues/230
[vt-d-notebook]: https://groups.google.com/d/msg/qubes-users/Sz0Nuhi4N0o/ZtpJdoc0OY8J
[Intel VT-x]: https://en.wikipedia.org/wiki/X86_virtualization#Intel_virtualization_.28VT-x.29
[AMD-V]: https://en.wikipedia.org/wiki/X86_virtualization#AMD_virtualization_.28AMD-V.29
[Intel VT-d]: https://en.wikipedia.org/wiki/X86_virtualization#Intel-VT-d
[AMD-Vi (aka AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29
[AMD-Vi (also known as AMD IOMMU)]: https://en.wikipedia.org/wiki/X86_virtualization#I.2FO_MMU_virtualization_.28AMD-Vi_and_Intel_VT-d.29
[EPT]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Extended_Page_Tables
[RVI]: https://en.wikipedia.org/wiki/Second_Level_Address_Translation#Rapid_Virtualization_Indexing

2
user/managing-os/minimal-templates.md
View File

@ -32,6 +32,8 @@ There are currently three Minimal TemplateVMs corresponding to the standard [Fed
3. The Minimal TemplateVMs are intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.][pref-default]
4. In order to reduce unnecessary risk, unused repositories have been disabled by default.
If you wish to install or update any packages from those repositories, you must enable them.
## Installation

30
user/managing-os/templates.md
View File

@ -117,11 +117,11 @@ If this doesn't work, please see [How to Remove VMs Manually].
If the Applications Menu entry doesn't go away after you uninstall a TemplateVM, execute the following type of command in dom0:
$ rm ~/.local/share/applications/<template-vm-name>
$ rm ~/.local/share/applications/<template_vm_name>
Applications Menu entries for backups of removed VMs can also be found in `/usr/local/share/applications/` of dom0.
$ rm /usr/local/share/applications/<template-vm-name>
$ rm /usr/local/share/applications/<template_vm_name>
## Reinstalling
@ -137,24 +137,22 @@ When you install a new template or upgrade a clone of a template, it is recommen
Applications Menu --> System Tools --> Qubes Global Settings --> Default template
2. Base AppVMs on the new template.
2. If your keyboard or mouse is connected through `sys-usb`, switch `sys-usb` to the new template.
(Note that this is a single command to ensure that `sys-usb` restarts.
If it does not, you will not be able to use your USB keyboard or mouse.)
[user@dom0 ~]$ qvm-shutdown --wait sys-usb; qvm-prefs sys-usb template <new_template>; qvm-start sys-usb
3. Base AppVMs on the new template.
Applications Menu --> System Tools --> Qubes Template Manager
3. Base the [DisposableVM Template] on the new template.
4. Base the [DisposableVM Template] on the new template.
[user@dom0 ~]$ qvm-create -l red -t new-template new-template-dvm
[user@dom0 ~]$ qvm-prefs new-template-dvm template_for_dispvms True
[user@dom0 ~]$ qvm-features new-template-dvm appmenus-dispvm 1
[user@dom0 ~]$ qubes-prefs default-dispvm new-template-dvm
4. Updating the template for sys-usb if peripheral devices are dependent upon the VM
If you are running Qubes on a desktop or other device where the peripheral devices such as keyboard / mouse / trackpad are dependent upon the sys-usb appVM then updating the template is a challenge. In this situation, you can use the following commands in a dom0 terminal window to update the templateVM.
$ qvm-shutdown --wait sys-usb; qvm-prefs sys-usb template fedora-31; qvm-start sys-usb
Be careful to run this set of commands as shown above (3 commands in a single line) because if the sys-usb VM does not start back up you may be locked out of your machine.
[user@dom0 ~]$ qvm-create -l red -t <new_template> <new_template_dvm>
[user@dom0 ~]$ qvm-prefs <new_template_dvm> template_for_dispvms True
[user@dom0 ~]$ qvm-features <new_template_dvm> appmenus-dispvm 1
[user@dom0 ~]$ qubes-prefs default-dispvm <new_template_dvm>
## Advanced

6
user/reference/glossary.md
View File

@ -119,8 +119,9 @@ FirewallVM
FirewallVMs, as defined here, no longer exist in Qubes 4.0 or later (see [here][pr-748] for technical details).*
Firewall Virtual Machine.
A type of [ProxyVM](#proxyvm) that is used to enforce network-level policies (a.k.a. "firewall rules").
A type of [ProxyVM](#proxyvm) that is used to enforce network-level policies (a.k.a. "firewall rules").
A FirewallVM called `sys-firewall` is created by default in most Qubes installations.
Also see [Qubes Firewall](/doc/firewall/).
DisposableVM
------------
@ -191,7 +192,8 @@ This allows for optimal performance on guest operating systems such as Windows.
Windows Tools
-----
Qubes Windows Tools are a set of programs and drivers that provide integration of Windows [AppVMs](#appvm) with the rest of the Qubes system.
[Qubes Windows Tools](/doc/windows-tools/) (QWT) are a set of programs and drivers that provide integration of Windows [AppVMs](#appvm) with the rest of the Qubes system.
Also see [Windows](/doc/windows/).
QWT
----

8
user/security-in-qubes/split-gpg.md
View File

@ -16,8 +16,8 @@ redirect_from:
# Qubes Split GPG #
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" plays another Qubes AppVM.
This way one, not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations, such as encryption/decryption and signing to another, more trusted, network-isolated, domain.
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" is played by another Qubes AppVM.
This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations -- such as encryption/decryption and signing -- to another, more trusted, network-isolated domain.
This way the compromise of your domain where Thunderbird or another client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys.
(We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
@ -378,8 +378,8 @@ As always, exercise caution and use your good judgment.)
[intro]: #what-is-split-gpg-and-why-should-i-use-it-instead-of-the-standard-gpg
[se-pinentry]: https://unix.stackexchange.com/a/379373
[​subkeys]: https://wiki.debian.org/Subkeys
[copied]: /doc/copying-files#on-inter-qube-file-copy-security
[pasted]: /doc/copy-paste#on-copypaste-security
[copied]: /doc/copying-files#security
[pasted]: /doc/copy-paste#security
[​MUA]: https://en.wikipedia.org/wiki/Mail_user_agent
[covert channels]: /doc/data-leaks
[trusting-templates]: /doc/templates/#trusting-your-templatevms

328
user/troubleshooting/macbook-troubleshooting.md
View File

@ -1,328 +0,0 @@
---
layout: doc
title: Apple MacBook Troubleshooting
permalink: /doc/macbook-troubleshooting/
---
Apple MacBook Troubleshooting
=============================
MacBook Air 13" mid 2011 (MacBookAir 4,2)
-----------------------------------------
In this section, I explain how to install Qubes on a MacBook Air 13" mid 2011
(MacBookAir 4,2).
This model has the following features:
* Dual Intel i7-2677M 1.80 Ghz CPU (2 dual cores)
* Intel HD Graphics 3000
* 4Gb RAM
* 256Gb SDD
* Broadcom BCM43224 802.11 a/b/g/n wifi and Bluetooth adapter
* Intel DSL2310 Thunderbolt controller
* It has 1 DVI/Thunderbolt display port, 2 USB2.0 ports, a Magsafe power
adapter, a standard 3.5mm audio jack and SD reader.
I first tried to install Qubes using the UEFI boot, but it failed. Not wanting
to waste too much time, I quickly opted for the legacy BIOS install.
### 1. Boot from Mac OS X (or Internet Recovery Image with `CMD`+`R` during bootup)
Run in a terminal [[1]]:
~~~
# diskutil list
(find your usb device)
# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition
# reboot
~~~
Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up.
Install Qubes normally.
If you try to boot Qubes now, it will freeze while "setting up networking." You
need to put the Broadcom wireless device into PCI passtrough [[2],[3]]. Or, as
an alternative [remove it from your Mac][bluetooth-replacement] and Qubes will
boot up smoothly. If you choose to remove the card, jump to step 3.
### 2. Boot from Mac OS X again
Run in a terminal:
~~~
# diskutil list
(find your usb device)
# bless –device /dev/diskX –legacy –setBoot –nextonly # bless the disk not the partition
# reboot
~~~
Insert your Qubes 3.2 USB flash drive. The ISOLINUX boot screen should come up.
Select Troubleshooting and Boot the Rescue image. Enter your disk password when
prompted. Select continue and after mounting the HD filesystem and launching a
shell, `chroot` as instructed.
Then find your Bluetooth card:
~~~
# lspci
..
02:00.0 Network controller: Broadcom Corporation BCM43224 802.11a/b/g/n (rev 01)
…
# qvm-pci -a sys-net 02:00.0 # this assigns the device to sys-net VM
~~~
Then create `/etc/systemd/system/qubes-pre-netvm.service` with:
~~~
[Unit]
Description=Netvm fix for Broadcom
Before=qubes-netvm.service
[Service]
ExecStart=/bin/sh -c 'echo 02:00.0 > /sys/bus/pci/drivers/pciback/permissive'
Type=oneshot
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
~~~
Run:
~~~
systemctl enable qubes-pre-netvm.service
~~~
And that's it.
### 3. After reboot, boot Mac OS X again
Run in a terminal:
~~~
# diskutil list
(find the HD device where you installed Qubes)
# bless –device /dev/diskX –legacy –setBoot # bless the disk not the partition
# reboot
~~~
Results:
* System booted and running smoothly
* Youtube video: OK (including full screen after configuration)
* Trackpad: OK
* Audio control: OK
* Brightness control: OK
* Keyboard light control:OK
* SD card access: OK (tested at dom0)
* Lid-close suspend: OK
* Wifi: +10%-20% ICMP packet loss when comparing with OSX (have similar rates
with Tails Linux, more tests are required)
### References
1. <https://github.com/QubesOS/qubes-issues/issues/794>
2. <https://github.com/QubesOS/qubes-issues/issues/1261>
3. <https://www.qubes-os.org/doc/assigning-devices/>
MacBook Air 2012 (MacBookAir 5,1)
---------------------------------
Please see [this thread o the qubes-devel mailing list][macbook-air-2012-5-1].
[1]: https://github.com/QubesOS/qubes-issues/issues/794
[2]: https://github.com/QubesOS/qubes-issues/issues/1261
[3]: /doc/assigning-devices/
[bluetooth-replacement]: https://www.ifixit.com/Guide/MacBook+Air+13-Inch+Mid+2011+AirPort-Bluetooth+Card+Replacement/6360
[macbook-air-2012-5-1]: https://groups.google.com/d/topic/qubes-devel/uLDYGdKk_Dk/discussion
MacBook Pro Retina, 15 inch, Mid-2015 (MacBookPro 11,5)
-------------------------------------------------------
In this section, I explain how I installed Qubes 3.2 on a MacBook Pro Retina 2015 (MacBookPro 11,5).
Good news: the relevant stuff works.
Bad news: still some minor issue to investigate.
For the time being, my setup is just for testing purposes and help to bypass some blocking issues: do not use it in production or on machine where security is a concern!
I hope to improve it as soon as possible.
During my nights trying to get Qubes OS working, I faced two main and blocking issues:
* no boot, due to empty xen.cfg file
* system freeze, due to Broadcom BCM43602 wifi card
I am already using Qubes for my daily job on Intel NUC. For the time being, I installed Qubes on Macbook for test purposes. Later on I will review the security implications.
This model has the following features:
* 2,5 GHz Intel Core i7-4870HQ (2 quad cores)
* Dual Graphic Card
* Intel Iris Pro
* AMD Radeon R9 M370X
* 16Gb RAM
* 512Gb SDD
* Broadcom BCM43602 802.11ac wifi adapter
### 1. Reclaim space to be able to multiboot OSX
For security reasons, you should install Qubes using the whole disk. I preferred to keep OSX, so I shrunk OS partition:
* reboot in recovery mode
* run disk utility and shrink OSX partition, eg 150GB for OSX and the remaining space for Qubes OS
* reboot
### 2. Boot installer
Download and prepare a USB with Qubes 3.2
You can install Qubes using BIOS or UEFI:
* BIOS/CSM/Legacy: I have not been able to install using legacy, but I did not spend a lot of time on it.
* UEFI plain: grub menu appears, but any gave me a quick flash and returned the main menu. I can boot it manually fixing the grub.cfg file, adding commands linuexefi and initrdefi, pointing proper files in /efi/boot. After boot, I end up with no root file system.
* UEFI, using rEFInd: I have been successful, despite some issues to be fixed manually, after installation completion
* download [rEFInd] refind-bin-0.10.4.zip: this file is not signed, so decide if you trust it or not. SHA1 sum is 3d69c23b7d338419e5559a93cd6ae3ec66323b1e
* unzip it and run installer, which installs rEFIind on the internal SSD
* if installation fails due to SIP, reboot in recovery mode, open a terminal and issue command
~~~
csrutil disable
~~~
* reboot and you will see some icons
* choose Boot EFI\BOOT\xen.efi from ANACONDA
* after a while the graphical installer is up (keyboard and touchpad working)
### 3. Installation
* As a general rule, keep the default values proposed during installation: you can change them later on
* Keep English, as language, locale
* My Macbook has a US keyboard, so I cannot say what happens if you change keyboard layout
* DO NOT CHANGE the timezone, because it will trigger the wifi card, leading to a system freeze
* Choose the "installation destination": do not change anything and press DONE button
* Insert your password for Full Disk Encryption
* If you do not already have free space on internal SSD disk, you will be prompted to reclaim some space:
* If you shrunk OSX partition, disk utility left an empty partition: delete useless partition (e.g.: if you shrunk OSX partition, diskutil created an empty partition)
* Press on "reclaim space"
* Press on "begin installation"
* create your user and password
* after a while, installation completes
* DO NOT press "Reboot button"
Qubes OS is now installed, but you cannot boot it due to some issues, with bootloader configuration and wifi card.
You cannot Qubes boot using EFI/qubes/xen.efi because XEN bootloader configuration is broken.
You cannot even Qubes without XEN support, using GRUB2, because its configuration is broken too.
Let's fix it manually, switch to console, pressing Fn+CTRL+ALT+F2
### 4. Fix GRUB configuration
You can skip this section, but I found it very useful - during troubleshooting - to have a rescue system at hand. I could boot Qubes, without XEN support
Grub configuration file is using some wrong commands, which are not compatible with grub2-efi
~~~
chroot /mnt/sysimage
sed -i.bak -e "s/multiboot/chainloader/" -e "s/module.*--nounzip/initrdefi/" -e "s/module/linuxefi/" /etc/grub.d/20_linux_efi
exit
~~~
Now, despite XEN configuration is still broken, you have a rescue system booting vmlinux from rEFInd screen.
TBV1: chainloading XEN does not work, unless you specify the right disk prefix, eg: (hd1,gpt4)
TBV2: grub.cfg set the wrong disk in "set root" command
TBV3: in case you reach grub shell, you can
~~~
ls
~~~
and also reload config file and change it manualy before booting
~~~
configfile /EFI/qubes/grub.cfg
~~~
then press "e", edit grub cfg and boot pressing Fn+F10
### 5. Fix bootloader
* Fix grub2 configuration, which uses wrong command for EFI boot
* analyzing /mnt/sysimage/var/log/anaconda/program.log I found the faulty commands issues by Anaconda installer
~~~
chrooot /mnt/sysimage
~~~
* edit /boot/efi/EFI/qubes/xen.cfg file putting the following content
~~~
[global]
default=4.4.14-11.pvops.qubes.x868_64
[4.4.14-11.pvops.qubes.x868_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M
kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64
ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img
~~~
* The main mistake is the efibootmgr, that needs the right commands. Just in case, re-apply all the commands, adapting to your own disk layout (-d /dev/sdxxx -p partition_number)
~~~
grep Running /mnt/sysimage/var/log/anaconda/program.log | tail -n 20
efibootmgr -b 0000 -B
efibootmgr -c -w -L Qubes -d /dev/sda -p 4 -l \\EFI\\qubes\\xen-4.6.1.efi
/usr/libexec/mactel-boot-setup
kernel-install add 4.4.14-11.pvops.qubes.x86_64 /boot/vmlinuz-4.4.14-11.pvops.qubes.x86_64
systemctl disable qubes-netvm
reboot
~~~
At rEFInd screen, choose Boot EFI/qubes/xen-4.6.1.efi
Everything should now be ok, Qubes OS boots using EFI and you will get the last setup screen
* select "Qubes OS", do not change anything and click on "Done"
* VMs are created, including NetVM
### 6. Fix pulseaudio, which locks CPU freezing the system often for 20 seconds
My Macbook has frequent freezes. Looking at journalctl output I saw that pulseaudio locks CPU for 20 seconds, very often.
You can fix this issue, killing audio support with this quick workaround:
* open a dom0 terminal, as root and edit /etc/pulse/client.conf
* add "autospawn = no"
* Then, as normal user, issue command "pulseaudio --kill"
### 7. Fix system freezes due to Broadcom BCM43602
* If you experience a system freeze, during VM setup, force a reboot and press OPTION key.
* You will reach grub shell
~~~
configfile /EFI/qubes/grub.cfg
~~~
press Fn+F10 to boot without XEN support
* Once booted, press Fn+CTRL+ALT+F4 to open a shell
* Log into system
~~~
sudo su -
systemctl disable qubes-netvm
~~~
Press Fn+F2 and complete setup
* reboot and you finally have your Qubes OS
* DO NOT launch sys-net machine
* Open its setting and remove wifi adapter from the Selected devices, using Qubes Manager or use the following command line. Get the BFD of the adapter and remove it. On my Macbook BFD is 04:00.0 and you will use it later on, also
~~~
qvm-pci -l sys-net
qvm-pci -d sys-net 04:00.0
~~~
Ok, setup is complete and we are almost done.
* Open a dom0 terminal
~~~
sudo su -
xl pci-assignable-list
echo 04:00.0 > /sys/bus/pci/drivers/pciback/permissive
qvm-start sys-net
xl pci-attach sys-net 04:00.0
~~~
These latest steps are required to launch sys-net with wifi access. They can be automated in a custom systemd service.
[rEFInd]: http://www.rodsbooks.com/refind/getting.html

2
user/troubleshooting/pci-troubleshooting.md
View File

@ -115,7 +115,7 @@ You can also configure strict reset directly from the Qubes interface by followi
## Broadcom BCM43602 Wi-Fi card causes system freeze ##
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in [Macbook Troubleshooting](/doc/macbook-troubleshooting/#7-fix-system-freezes-due-to-broadcom-bcm43602).
You may face the problem where the BCM43602 Wi-Fi chip causes a system freeze whenever it is attached to a VM. To fix this problem on a Macbook, follow the steps in [Macbook Troubleshooting](/doc/macbook-troubleshooting/#system-freezes-after-attaching-broadcom-bcm43602-wi-fi-card).
For other non-Macbook machines, it is advisable to replace the Broadcom BCM43602 with one known to work on Qubes, such as the Atheros AR9462.

36
user/troubleshooting/remove-vm-manually.md
View File

@ -1,36 +0,0 @@
---
layout: doc
title: How to Remove VMs Manually
permalink: /doc/remove-vm-manually/
---
How to Remove VMs Manually
==========================
How to Remove a TemplateVM Manually
-----------------------------------
Try the [normal method] before resorting to this.
All of the following commands should be executed in a dom0 terminal.
When a template is marked as 'installed by package manager', but cannot be uninstalled there, trying to uninstall manually will result in the error "ERROR: VM installed by package manager: template-vm-name". Do as follows to be able to uninstall the template:
1. Check the state of `installed_by_rpm`
$ qvm-prefs template-vm-name
2. If `installed_by_rpm - True]`, mark the template as not installed by package manager
$ qvm-prefs template-vm-name installed_by_rpm false
3. Re-check the state of `installed_by_rpm`
- If `installed_by_rpm - False`, remove the template like you would a regular qube:
$ qvm-remove template-vm-name
- If `installed_by_rpm` remains `True`, reboot your computer to bring qubes.xml in sync with qubesd, and try again to remove the template.
[normal method]: /doc/templates/#uninstalling

51
user/troubleshooting/update-troubleshooting.md Normal file
View File

@ -0,0 +1,51 @@
---
layout: doc
title: Update Troubleshooting
permalink: /doc/update-troubleshooting/
---
# Fixing issues that arise during updating #
## “Failed to synchronize cache for repo” errors when updating Fedora templates ##
This is general Fedora issue, not a Qubes-specific issue.
Usually, this is due to network problems (especially if downloading updates over Tor) or problems with the download mirrors.
Often, the problem can be resolved by trying again on a different connection (a different Tor circuit, if using Tor) or waiting and trying again later.
Here are some examples of non-Qubes reports about this problem:
- <https://ask.fedoraproject.org/en/question/88086/error-failed-to-synchronize-cache-for-repo-fedora/>
- <https://unix.stackexchange.com/questions/390805/repos-not-working-on-fedora-error-failed-to-synchronize-cache-for-repo-update>
- <https://www.reddit.com/r/Fedora/comments/74nldq/fedora_26_dnf_error_failed_to_synchronize_cache/>
- <https://bugzilla.redhat.com/show_bug.cgi?id=1494178>
- <https://stackoverflow.com/questions/45318256/error-failed-to-synchronize-cache-for-repo-updates>
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.
## Lost internet access after a TemplateVM update ##
In earlier versions of Qubes, there were situations where qubes lost internet access after a TemplateVM update. The following fix should be applied in recent versions of Qubes.
Run `systemctl enable NetworkManager-dispatcher.service` in the TemplateVM upon which your NetVM is based.
You may have to reboot afterward for the change to take effect.
(Note: This is an upstream problem. See [this Redhat ticket](https://bugzilla.redhat.com/show_bug.cgi?id=974811)).
For details, see the qubes-users mailing list threads [here](https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion) and [here](https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion).)
## Windows update is stuck ##
This has nothing to do with Qubes.
It's a longstanding Windows bug.
More information about this issue and solutions can be found [here](https://superuser.com/questions/951960/windows-7-sp1-windows-update-stuck-checking-for-updates).
## Dom0 and/or TemplateVM update stalls when updating via the GUI tool
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run `sudo qubes-dom0-update`.
Depending on your operating system, open a terminal in the TemplateVMs and run:
* Fedora: `sudo dnf upgrade`
* Debian: `apt-get update && apt-get dist-upgrade`

10
user/troubleshooting/usb-troubleshooting.md
View File

@ -81,3 +81,13 @@ Note that this procedure will attach your USB controllers to dom0, so do this on
If your computer has a PS/2 port, you may instead use a PS/2 keyboard to enter the LUKS password.
## "qubes-usb-proxy not installed in the VM" error ##
When trying to [create and use a USB qube](/doc/usb-devices/#creating-and-using-a-usb-qube) with the `qubes-usb-proxy` package, you may receive this error: `ERROR: qubes-usb-proxy not installed in the VM`.
If you encounter this error, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
Depending on your operating system, open a terminal in the TemplateVM and enter one of the following commands:
* Fedora: `sudo dnf install qubes-usb-proxy`
* Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`

17
user/troubleshooting/vm-troubleshooting.md
View File

@ -71,3 +71,20 @@ If you face this error when starting a VM, look into the VM logs at `/var/log/xe
Common reasons that may be revealed are: too low memory, corrupted files or a VM crash on startup.
If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory.
## "No match found" when trying to install a TemplateVM ##
For example:
```
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-itl qubes-template-debian-10
Using sys-whonix as UpdateVM to download updates for Dom0; this may take some time...
No Match for argument qubes-template-debian-10
Nothing to download
```
This normally means you already have the template installed.
It may be that you have the matching package installed, but you removed or renamed the template.
Check `rpm -q qubes-template-<name>`.
If it lists the package, but you don't really have the template present (`qvm-ls` doesn't list it), you need to clean up leftovers of the package with `rpm -e --noscripts qubes-template-<name>`, then install it normally.

31
user/troubleshooting/vpn-troubleshooting.md Normal file
View File

@ -0,0 +1,31 @@
---
layout: doc
title: VPN Troubleshooting
permalink: /doc/vpn-troubleshooting/
---
# VPN Troubleshooting Guide #
## Tips
* If using qubes-vpn, check the VPN service's log in the VPN VM by running:
~~~
sudo journalctl -u qubes-vpn-handler
~~~
* Always test your basic VPN connection before adding scripts.
* Test DNS: Ping a familiar domain name from an appVM. It should print the IP address for the domain.
* Use `iptables -L -v` and `iptables -L -v -t nat` to check firewall rules. The latter shows the critical PR-QBS chain that enables DNS forwarding.
## VPN does not reconnect after suspend
This applies when using OpenVPN.
After suspend/resume, OpenVPN may not automatically reconnect. In order to get it to work, you must kill the OpenVPN process and restart it.
## VPN stuck at "Ready to start link"
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.