Git-Mirrors/Qubes-Community-Content
1
0
Fork 0
mirror of https://github.com/Qubes-Community/Contents.git synced 2024-12-22 21:59:26 -05:00
Code Issues Packages Projects Releases Wiki Activity

Reorganize files to account for new "External" section

Browse Source 
QubesOS/qubes-issues#4693
This commit is contained in:
Andrew David Wong 2019-05-26 19:32:45 -05:00
commit 5861397b7d
62 changed files with 8809 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

491
building/building-archlinux-template.md Normal file
View File

@ -0,0 +1,491 @@
---
layout: doc
title: Building Archlinux Template
permalink: /doc/building-archlinux-template/
redirect_from:
- /en/doc/building-archlinux-template/
- /doc/BuildingArchlinuxTemplate/
- /wiki/BuildingArchlinuxTemplate/
---
# Archlinux template building instructions
**These are the instructions for Qubes 3.2. They will take you step by step through the entire process start to finish**
*Note: These instructions have not been tested for Qubes 3.1. However they could be working.*
*Note: No binary package for the archlinux template exists for Qubes 3.1.*
## 1: Create and configure VM to use for template building
* The VM should be based on a Fedora template. It's best to use a standalone VM. I created a standalone VM based on
the Fedora 23 template. I named the VM “**development**”. These instructions assume a standalone VM based on a Fedora template is being used.
<br>
<br>
![arch-template-01](/attachment/wiki/ArchlinuxTemplate/arch-template-01.png)
<br>
<br>
* Ensure there is at least 25GB preferably 30GB of free space in the private storage. I made the private storage 30GB to be safe.
<br>
<br>
![arch-template-02](/attachment/wiki/ArchlinuxTemplate/arch-template-02.png)
<br>
<br>
*Note: Unless otherwise noted, all commands are from within the “development” VM or whatever you named your standalone VM used for building the template.*
## 2: Create GitHub Account (optional)
* It can be helpful. Creating only a basic account is all that is needed. This will allow you to help, going forward, with the Qubes project. You could be help edit errors in documentation. It can also be of use building other templates.
* Create user account here https://github.com
<br>
<br>
![arch-template-03](/attachment/wiki/ArchlinuxTemplate/arch-template-03.png)
<br>
<br>
## 3: Install necessary packages to 'development' VM for "Qubes Automated Build System"
* Necessary packages to install:
* git
* createrepo
* rpm-build
* make
* rpmdevtools
* python2-sh
* dialog
* rpm-sign
* gnupg
* The tools can usually be installed all together with the following terminal command string:
* **$ sudo dnf install git createrepo rpm-build make wget rpmdevtools python2-sh dialog rpm-sign gnupg**
<br>
<br>
![arch-template-04](/attachment/wiki/ArchlinuxTemplate/arch-template-04.png)
<br>
<br>
## 4: Downloading and verifying the integrity of the "Qubes Automated Build System"
* Import the Qubes master key
gpg --keyserver pgp.mit.edu --recv-keys 0xDDFA1A3E36879494
* Verify its fingerprint, set as 'trusted'. [This is described here](/doc/VerifyingSignatures).
* Download the Qubes developers' keys.
wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc
gpg --import qubes-developers-keys.asc
* Download the latest stable qubes-builder repository:
git clone git://github.com/QubesOS/qubes-builder.git qubes-builder
![arch-template-05](/attachment/wiki/ArchlinuxTemplate/arch-template-05.png)
* Copy your gpg keyrings to your local copy of the repository. (Otherwise you will be asked to download the keys again.)
# Execute the following commands in your home directory.
# It is assumed that the path to the repository is '~/qubes-builder'.
mkdir -p qubes-builder/keyrings/git
cp -t qubes-builder/keyrings/git/ .gnupg/pubring.gpg .gnupg/trustdb.gpg
* Verify the integrity of the downloaded repository. The last line should read `gpg: Good signature from`...
cd qubes-builder
git tag -v `git describe`
## 5: Configuring setup script to create builder.conf file
* You will be creating the builder.conf file which tells where and what to use. The most automated, and in this case the easiest, way to create this is to use the script that is provided in Qubes Builder. Its named '**setup**'. Before running the script you need to edit one file it uses.
*In the future this should not be needed once a change is made to the 'setup' script.*
* Edit the '**qubes-os-r3.2.conf**' which is found in **/home/user/qubes-builder/example-configs** Use the text editor of your choice.
* **$ cd /home/user/qubes-builder/example-configs/**
* **$ nano -W qubes-os-r3.2.conf** or **$ gedit qubes-os-r3.2.conf** or etc….
<br>
<br>
![arch-template-06](/attachment/wiki/ArchlinuxTemplate/arch-template-06.png)
<br>
<br>
* Go to the first line containing '**DISTS_VM ?= fc23**' it will be preceeded by line '**DIST_DOM0 ?= fc20**'. Remove '**fc23**' or whatever is listed there leaving only '**DISTS_VM ?=**'. Then save the file and close the text editor.
<br>
<br>
![arch-template-07](/attachment/wiki/ArchlinuxTemplate/arch-template-07.png)
<br>
<br>
<br>
## 6: Run the 'setup' script to build the builder.conf file
* Run the 'setup' script located in '**/home/user/qubes-builder/**' Make sure you are in directory '**qubes-builder**'
* **$ cd /home/user/qubes-builder/**
* **$ ./setup**
<br>
<br>
![arch-template-08](/attachment/wiki/ArchlinuxTemplate/arch-template-08.png)
<br>
<br>
* First screen will ask you to import 'Qubes-Master-Signing-key.asc'. The 'setup' script not only downloads but confirms the key to that of the key on Qubes-OS website.
* Select '**YES**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-09](/attachment/wiki/ArchlinuxTemplate/arch-template-09.png)
<br>
<br>
* Next screen will ask you to import Marek Marczykowski-Goracki (Qubes OS signing key). Again 'setup' will confirm this key to the fingerprint.
* Select '**YES**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-10](/attachment/wiki/ArchlinuxTemplate/arch-template-10.png)
<br>
<br>
* This screen will give you the choice of which Qubes Release to build the template for.
* Select '**Qubes Release 3.2**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-11](/attachment/wiki/ArchlinuxTemplate/arch-template-11.png)
<br>
<br>
* Screen "**Choose Repos To Use To Build Packages**"
* Select 'QubesOS/qubes- Stable - Default Repo'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12.png)
<br>
<br>
* Screen "**Build Template Only?**"
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-12](/attachment/wiki/ArchlinuxTemplate/arch-template-12a.png)
<br>
<br>
* Screen '**Builder Plugin Selection**' will give choices of builder plugins to use for the build.
* Deselect '**Fedora**'
* Deselect '**mgmt_salt**'
* Select '**builder-archlinux**'
* Select '**OK**' Press **Enter**
<br>
<br>
![arch-template-13](/attachment/wiki/ArchlinuxTemplate/arch-template-13.png)
<br>
<br>
* Screen '**Get sources**' wants to download additional packages needed for the choosen plugin/s.
* Select '**Yes**' Press '**Enter**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-14.png)
<br>
<br>
* Then wait for download to finish and press '**OK**'
<br>
<br>
![arch-template-14](/attachment/wiki/ArchlinuxTemplate/arch-template-15.png)
<br>
<br>
* Screen '**Template Distribution Selection**' allows you to choose the actual template/s you wish to build.
* Scroll Down to the very bottom (it is off the screen at first)
* Select '**archlinux**'
* Select '**OK**' Press '**Enter**'
<br>
<br>
![arch-template-16](/attachment/wiki/ArchlinuxTemplate/arch-template-16.png)
<br>
<br>
*Note: 'Setup' will close and will output the text of the created build.conf file as well as the needed **make** commands to build the template*
<br>
<br>
![arch-template-17](/attachment/wiki/ArchlinuxTemplate/arch-template-17.png)
<br>
<br>
## 7: Install all the dependencies
*Note: make sure you are in the “qubes-builder” directory to run the following cmds*
* **$ make install-deps**
<br>
<br>
![arch-template-18](/attachment/wiki/ArchlinuxTemplate/arch-template-18.png)
<br>
<br>
## 8: Get all the require sources for the build: (Note: this may take some time)
* **$ make get-sources**
<br>
<br>
![arch-template-19](/attachment/wiki/ArchlinuxTemplate/arch-template-19.png)
<br>
<br>
<br>
## 9: Make all the require Qubes Components
* **Note:** You can run a single command to build all the Qubes components or you can run them each individually.
Both ways below:
* Single command to build all Qubes components together: (this command can take a long time to process depending of your pc proccessing power)
* **$ make qubes-vm**
<br>
<br>
![arch-template-20](/attachment/wiki/ArchlinuxTemplate/arch-template-20.png)
<br>
<br>
* These are the indivual component 'make' commands:
* **$ make vmm-xen-vm**
* **$ make core-vchan-xen-vm**
* **$ make core-qubesdb-vm**
* **$ make linux-utils-vm**
* **$ make core-agent-linux-vm**
* **$ make gui-common-vm**
* **$ make gui-agent-linux-vm**
<br>
<br>
## 10: Make the actual Archlinux template
* **$ make template**
<br>
<br>
![arch-template-21](/attachment/wiki/ArchlinuxTemplate/arch-template-21.png)
<br>
<br>
## 11: Transfer Template into Dom0
* You need to ensure these two files are in the '**noarch**' directory
* **$ cd /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/**
* **$ ls** *(confirm the below two files are there)*
* **install-templates.sh** (script to install template in dom0)
* **$ cd noarch**
* **$ ls**
* **qubes-template-archlinux-X.X.X-XXXXXXXXXXXX.noarch.rpm** (this is the template package 'X' replaces version and build digits)
<br>
<br>
![arch-template-22](/attachment/wiki/ArchlinuxTemplate/arch-template-22.png)
<br>
<br>
* **Transfer the install-templates.sh script file into Dom0**
*Note: as there is not a typical file transfer method for Dom0, for security reasons, this less than simple transfer function has to be used*
* Switch to Domo and open a terminal window.
**Note:** Take care when entering these cmd strings. They are very long and have a number of characters that are easy to mix '**-**' vs '**.**' '**<u>T</u>emplates** (correct) vs **<u>t</u>emplates** (wrong) or **Template_**'(also wrong) This script will also take care of transfering the actual template.rpm to Dom0 as well.
* **$ qvm-run --pass-io development 'cat /home/user/qubes-builder/qubes-src/linux-template-builder/rpm/install-templates.sh' > install-templates.sh**
* **$ chmod +x install-templates.sh**
* **$ ./install-templates.sh**
<br>
<br>
![arch-template-23](/attachment/wiki/ArchlinuxTemplate/arch-template-23.png)
<br>
<br>
![arch-template-24](/attachment/wiki/ArchlinuxTemplate/arch-template-24.png)
<br>
<br>
* If everything went correct there should be a Archlinux template listed in your Qubes VM Manager *
# Known problems in building with Qubes R3.X
## Build fails when fetching qubes-mgmt-salt
The `qubes-mgmt-salt` repo is not currently forked under the marmarek user on
GitHub, to whom the above instructions set the `GIT_PREFIX`. As Archlinux is
not yet supported by mgmt-salt, simply leave it out of the build (when building
the Archlinux template on its own) by appending the following to your `override.conf` file:
`BUILDER_PLUGINS := $(filter-out mgmt-salt,$(BUILDER_PLUGINS))`
## The nm-applet (network manager icon) fails to start when archlinux is defined as a template-vm
In fact /etc/dbus-1/system.d/org.freedesktop.NetworkManager.conf does not allow a standard user to run network manager clients. To allow this, one need to change inside \<policy context="default"\>:
`<deny send_destination="org.freedesktop.NetworkManager"/>`
to
`<allow send_destination="org.freedesktop.NetworkManager"/>`
## DispVM, Yum proxy and most Qubes addons (thunderbird ...) have not been tested at all
## Error when building the gui-agent-linux with pulsecore error
```
module-vchan-sink.c:62:34: fatal error: pulsecore/core-error.h: No such file or directory
#include <pulsecore/core-error.h>
```
This error is because Archlinux update package too quickly. Probably, a new version of pulseaudio has been released, but the qubes team has not imported the new development headers yet.
You can create fake new headers just by copying the old headers:
```
cd qubes-builder/qubes-src/gui-agent-linux/pulse
ls
cp -r pulsecore-#lastversion pulsecore-#archlinuxversion
```
You can check the current archlinux pulseaudio version like this:
`sudo chroot chroot-archlinux/ pacman -Qi pulseaudio`
## chroot-archlinux/dev/pts has not been unmounted
This is a known problem when there are errors during building. Check what is mounted using the command mount (with no parameters). Just unmount what you can (or reboot your vm if you are too lazy :) )
# Known problems in building with Qubes R2-B2
## xen-vmm-vm fail to build with a PARSETUPLE related error (FIXED)
Commenting out "\#define HAVE\_ATTRIBUTE\_FORMAT\_PARSETUPLE" from chroot\_archlinux/usr/include/python2.7/pyconfig.h fixes the problem, but it isn't the right solution [1]...
A better fix is planned for the next python release (the bug is considered release blocking), and will be updated in archlinux chroot as soon as available.
[1] [https://bugs.python.org/issue17547](https://bugs.python.org/issue17547)
## The boot process fails without visible errors in the logs, but spawn a recovery shell
The problem is new conflict between systemd and the old sysvinit style. To fix this, you can change the master xen template in dom0 to remove sysvinit remains: Edit **INSIDE DOM0** /usr/share/qubes/vm-template.conf, and change the variable 'extra' that contains the kernel variables: from:
`extra="ro nomodeset 3 console=hvc0 rd_NO_PLYMOUTH {kernelopts}"`
to:
`extra="ro nomodeset console=hvc0 rd_NO_PLYMOUTH {kernelopts}"`
## Qubes-OS is now using different xenstore variable names, which makes to archlinux VM failing to boot
Apply the following fix in the template to revert the variable name to the old Qubes version.
You can edit the template the following way:
```
sudo mkdir /mnt/vm
sudo mount /var/lib/qubes/vm-templates/archlinux-x64/root.img /mnt/vm
sudo chroot /mnt/vm
```
Then apply the fix:
```
sudo sed 's:qubes-keyboard:qubes_keyboard:g' -i /etc/X11/xinit/xinitrc.d/qubes-keymap.sh
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /etc/NetworkManager/dispatcher.d/30-qubes-external-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/init/network-proxy-setup.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/lib/qubes/init/qubes-sysinit.sh
sudo sed 's:qubes-ip:qubes_ip:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netmask:qubes_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-gateway:qubes_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-secondary-dns:qubes_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-network:qubes_netvm_network:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-gateway:qubes_netvm_gateway:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-netmask:qubes_netvm_netmask:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-netvm-secondary-dns:qubes_netvm_secondary_dns:g' -i /usr/lib/qubes/setup-ip
sudo sed 's:qubes-iptables-domainrules:qubes_iptables_domainrules:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-header:qubes_iptables_header:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables-error:qubes_iptables_error:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-iptables:qubes_iptables:g' -i /usr/bin/qubes-firewall
sudo sed 's:qubes-netvm-domid:qubes_netvm_domid:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-netvm-external-ip:qubes_netvm_external_ip:g' -i /usr/bin/qubes-netwatcher
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/lib/qubes/qubes_trigger_sync_appmenus.sh
sudo sed 's:qubes-vm-type:qubes_vm_type:g' -i /usr/bin/qubes-session
sudo sed 's:qubes-vm-updateable:qubes_vm_updateable:g' -i /usr/bin/qubes-session
```
Do not forgot to unmount the VM:
`umount /mnt/vm`
## Installing the template in dom0 fails because of a missing dependency (qubes-core-dom0-linux)
Again you built a template based on a recent Qubes API which has not been released yet. So skip the dependency for now
`sudo rpm -U --nodeps yourpackage.rpm`
# Qubes Mailing List Threads on the Archlinux build process
* [Qubes-Devel](https://groups.google.com/forum/#!forum/qubes-devel): [Qubes Builder failed Archlinux repository is missing](https://groups.google.com/forum/#!topic/qubes-devel/tIFkS-rPVx8)
* [Qubes-Users](https://groups.google.com/forum/#!forum/qubes-users): [Trying to compile archlinux template](https://groups.google.com/forum/#!topic/qubes-users/7wuwr3LgkQQ)
<br>

151
building/building-non-fedora-template.md Normal file
View File

@ -0,0 +1,151 @@
---
layout: doc
title: Building Non-Fedora Template
permalink: /doc/building-non-fedora-template/
redirect_from:
- /en/doc/building-non-fedora-template/
- /doc/BuildingNonFedoraTemplate/
- /wiki/BuildingNonFedoraTemplate/
---
Building a TemplateVM for ArchLinux (or another non Fedora OS)
==============================================================
If you don't like using Fedora because of specific administration, package management or other building needs, you could build a TemplateVM for your distribution of choice.
This article shows how to build a template for a different OS, taking ArchLinux as an example.
Qubes builder scripts
=====================
You can start creating Qubes builder scripts for your new OS. Just note that it will probably make your testing process harder than trying to build the package directly in an HVM on which you already installed this new OS.
chroot initialization
---------------------
You need to customize some scripts that will be used to build all the Qubes tools.
The scripts you will be interested in will be inside the `qubes-src/linux-template-builder` folder:
~~~
scripts_fedora
scripts_archlinux
scripts_yourOSname
~~~
### 00\_prepare.sh
The goal of the first script `00_prepare.sh` is to download and verify the signature of the installation CD and tools. You can use the `$CACHEDIR` directory variable to store files that could be reused (such as downloaded scripts or iso files).
### 01\_install\_core.sh
The goal of this script is to install a base environment of your target OS inside the `$INSTALLDIR` directory variable. Generally you need to bootstrap/install your package manager inside the `$INSTALLDIR` directory and install the base packages.
### Testing the installation process
Edit the file `builder.conf` to change the variable `$DISTS_VM` to your OS name (`DISTS_VM=your_os_name`). The try to create (make) the template to check that at least these first two scripts are working correctly:
~~~
make linux-template-builder
~~~
Qubes builder Makefiles
-----------------------
Now you need to create Makefiles specific to your OS. You will find the required scripts directly inside the `qubes-builder` folder:
~~~
prepare-chroot-yourOSname
Makefile.yourOSname
~~~
### prepare-chroot-yourOSname
The goal of this file is to prepare a development environment of your target OS inside a chroot. You will reuse the `00_prepare.sh` and `01_install_core.sh` scripts. Additionally, the following things will be necessary to put in this Makefile:
- the `$1` variable will contain the installation directory (`$INSTALLDIR` should contain the same value as `$1` when you run `00_prepare.sh` or `01_install_core.sh`)
- after your base system is installed, you should install development tools and libraries (gcc, make, ...)
- create a user called 'user' inside your chroot, and give him enough rights to run the command sudo without any password
- register all the repositories that are be necessary and synchronize the package database
- register a custom repository that will be used to store Qubes packages
### Makefile.yourOSname
This file will be used to define the action required when installing a custom package. The most important one are:
- `dist-prepare-chroot`: that's where you will call `prepare-chroot-yourOSname` if the chroot has not been initialized.
- `dist-package`: that's where you will chroot the development environment and run the command used to build a package.
- `dist-build-dep`: that's where you will create the custom repository for your target OS based on already compiled packages.
These additional target need to exist once you created your first packages:
- `dist-copy-out`: that's where you will retrieve the package you just built and put it with all the other packages you prepared.
- `update-repo`: that's where you will retrieve the package that have been built and add it to the custom repository.
### Testing the development chroot
You will be able to test these scripts when making the first Qubes packages. Don't forget that the first things that run when running `make somcomponent-vm` will be these two scripts, and that you will need to debug it at this point.
Qubes packages
--------------
* [vmm-xen](https://github.com/QubesOS/qubes-vmm-xen)
* [core-vchan-xen](https://github.com/QubesOS/qubes-core-vchan-xen)
* [linux-utils](https://github.com/QubesOS/qubes-linux-utils)
* [core-agent-linux](https://github.com/QubesOS/qubes-core-agent-linux)
* [gui-common](https://github.com/QubesOS/qubes-gui-common)
* [gui-agent-linux](https://github.com/QubesOS/qubes-gui-agent-linux)
Additional Installation scripts
-------------------------------
Again you need to work on scripts inside the `qubes-src/linux-template-builder` folder:
~~~
scripts_fedora
scripts_archlinux
scripts_yourOSname
~~~
### 02\_install\_groups.sh
The goal of this script is to install all the packages that you want to use in your template (eg: firefox, thunderbird, a file manager, Xorg...).
### 04\_install\_qubes.sh
The goal of this script is to install in your template all the packages you built previously. Also you need to edit the fstab file of your template to mount Qubes virtual hard drives.
### 09\_cleanup.sh
This script is use to finalize and to remove unnecessary things from your template, such as cached packages, unused development packages ...
Starting with an HVM
====================
If no Qubes packages are available for your selected OS. You could start to install an HVM with your OS. Your goals will be:
- to identify how to install the OS using command lines
- to create required Qubes packages
- to identify potential issue making all Qubes agents and scripts working correctly.
As soon as you manage to make `qrexec` and `qubes-gui-agent` working, it should be sufficient to start preparing a template VM.
### Xen libraries
Several Xen libraries are required for Qubes to work correctly. In fact, you need to make `xenstore` commands working before anything else. For this, Qubes git can be used as several patches have been selected by Qubes developers that could impact the activity inside a VM. Start be retrieving a recent git and identify how you can build a package from it: `git clone https://github.com/QubesOS/qubes-vmm-xen.git`.
Find the .spec file in the git repository (this is the file being used to build rpm packages), and try to adapt it to your OS in order to build a package similar to the target 'vmm-xen'. For example, a PKGBUILD has been created for [ArchLinux](/doc/templates/archlinux/) and can be found in the vmm-xen repository.
Don't be afraid with the complexity of the PKGBUILD, most of the code is almost a copy/paste of required sources and patches found in the .spec file provided in the git repository.
Note once the package has been successfully compiled and installed, you need to setup XEN filesystem. Add the following line to your fstab (you can create this line in your package install script): `xen /proc/xen xenfs defaults 0 0`.
Now install the package you built and mount `/proc/xen`. Verify that xenstore-read works by running: `xenstore-read name`. That should give you the current name.
### ArchLinux example PKGBUILDs
Qubes OS core agent (qrexec...) - [https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-core/PKGBUILD)
Qubes OS kernel modules - [https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-kernel-modules/PKGBUILD)
Qubes OS GUI agent - [https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD](https://aur.archlinux.org/packages/qu/qubes-vm-gui/PKGBUILD)

94
building/building-whonix-template.md Normal file
View File

@ -0,0 +1,94 @@
---
layout: doc
title: Building Whonix Templates
permalink: /doc/building-whonix-template/
redirect_from:
- /en/doc/building-whonix-template/
---
## Building Whonix Templates
The Whonix templates are easily downloaded and installed by following the [procedure here](https://www.whonix.org/wiki/Qubes/Install).
However, they are integrated into `qubes-builder` so they are straight-forward to build yourself if you prefer.
Many other Qubes templates can also be built by following this procedure.
Simply choose the appropriate builder(s) and template(s) you wish to build in the `./setup` procedure below.
Always include the `mgmt-salt` builder.
First, set up the [Build Environment](/doc/qubes-iso-building/#build-environment) (follow the build environment section only).
Next, configure the builder:
~~~
cd ~/qubes-builder
./setup
# Select Yes to add Qubes Master Signing Key
# Select Yes to add Qubes OS Signing Key
# Select 4.0 for version
# Stable
# Select Current (if you want the option to use pre-built packages)
# Yes (we want to build only templates)
# Select fc29 and stretch (for the currently shipping templates)
# Select builder-rpm, builder-debian, template-whonix, mgmt-salt
# Yes (to download)
~~~
Once it completes downloading, re-run `setup` to add the Whonix templates:
~~~
./setup
# Choose the same options as above, except at templates select:
# whonix-gateway-14, whonix-workstation-14
# If prompted, choose Yes to add adrelanos's third party key
~~~
Continue the build process with:
~~~
make install-deps
make get-sources
~~~
You will often need to edit/update `qubes-src/template-whonix/builder.conf` at this stage to specify the currently shipping Tor Browser version.
Open it in your favorite editor, then look for "Extra Whonix Build Options" and add/edit the `WHONIX_TBB_VERSION` variable to specify the current version.
For example:
```
################################################################################
# Extra Whonix Build Options
################################################################################
# Whonix repository.
WHONIX_APT_REPOSITORY_OPTS ?= stable
#WHONIX_APT_REPOSITORY_OPTS = off
# Use turbo mode to build template
BUILDER_TURBO_MODE ?= 1
# Enable Tor by default (0: disable; 1: enable)
WHONIX_ENABLE_TOR ?= 0
WHONIX_TBB_VERSION ?= 7.5.2
```
You can add/edit the `WHONIX_TBB_VERSION` variable in `~/qubes-builder/builder.conf` instead of this file if preferred.
Finally, use:
~~~
make qubes-vm
make template
~~~
Once the build is complete, the install packages for your newly built templates will be located in `~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch`.
Copy them from there to dom0 and install:
~~~
qvm-run --pass-io <src-vm> 'cat ~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch/qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm' > ~/qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm
qvm-run --pass-io <src-vm> 'cat ~/qubes-builder/qubes-src/linux-template-builder/rpm/noarch/qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm' > ~/qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm
sudo dnf install qubes-template-whonix-gw-4.0.0-201802250036.noarch.rpm
sudo dnf install qubes-template-whonix-ws-4.0.0-201802250145.noarch.rpm
~~~
And you are done!

36
configuration-guides/change-time-zone.md Normal file
View File

@ -0,0 +1,36 @@
---
layout: doc
title: Changing your Time Zone
permalink: /doc/change-time-zone/
---
# Changing your Time Zone #
## Qubes 4.0 ##
### Command line ###
If you use the i3 window manager or would prefer to change the system's time
zone in terminal you can issue the `timedatectl` command with the option
`set-timezone`.
For example, to set the system's time zone to Berlin, Germany type in a dom0
terminal:
$ sudo timedatectl set-timezone 'Europe/Berlin'
You can list the available time zones with the option `list-timezones` and show
the current settings of the system clock and time zone with option `status`.
Example output status of `timedatectl` on a system with time zone set to
Europe/Berlin:
[user@dom0 ~]$ timedatectl status
Local time: Sun 2018-10-14 06:20:00 CEST
Universal time: Sun 2018-10-14 04:20:00 UTC
RTC time: Sun 2018-10-14 04:20:00
Time zone: Europe/Berlin (CEST, +0200)
Network time on: no
NTP synchronized: no
RTC in local TZ: no

112
configuration-guides/disk-trim.md Normal file
View File

@ -0,0 +1,112 @@
---
layout: doc
title: Disk TRIM
permalink: /doc/disk-trim/
redirect_from:
- /en/doc/disk-trim/
- /doc/DiskTRIM/
- /wiki/DiskTRIM/
---
Disk Trim
=========
Disk trimming is the procedure by which the operating system informs the underlying storage device of which storage blocks are no longer in use.
It does this by issuing an `ATA_TRIM` command for the block. This is also known as a `discard`.
In this way, the storage device can perform garbage collection of the unused blocks and internally prepare them for reuse. SSDs in general benefit from this, while HDDs do not.
In a Linux system running on bare metal, this is relatively straight-forward.
When instructed by the operating system, discards are issued by the file-system driver directly to the storage driver and then to the SSD.
In Qubes, this gets more complex due to virtualization, LUKS, and LVM (and thin pools on R4.0 and up).
If you run `fstrim --all` inside a TemplateVM, in a worst case the `discard` can follow a path like:
OS -> File-system Driver -> Virtual Storage Driver -> Backend Storage Driver -> LVM Storage Driver -> LUKS Driver -> Physical Storage Driver -> Physical Storage Device
If discards are not supported at any one of those layers, it will not make it to the underlying physical device.
There are some security implications to permitting TRIM (read for example [this article](https://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but in most cases not exploitable.
Conversely, TRIM can improve security against local forensics when using SSDs, because with TRIM enabled deleting data (usually) results in the actual data being erased quickly, rather than remaining in unallocated space indefinitely.
However deletion is not guaranteed, and can fail to happen without warning for a variety of reasons.
Configuration
----------
In all versions of Qubes, you may want to set up a periodic job in `dom0` to trim the disk.
This can be done with either systemd (weekly only) or cron (daily or weekly).
* **Systemd**
From a terminal as a regular user:
```
systemctl enable fstrim.timer
systemctl start fstrim.timer
```
* **Cron**
This can be done from a terminal as root, by creating a `trim` file in `/etc/cron.daily` (or `/etc/cron.weekly`).
Add the following contents:
```
#!/bin/bash
/sbin/fstrim --all
```
And mark it as executable with `chmod 755 /etc/cron.daily/trim`.
**Note** Although discards can be issued on every delete inside `dom0` by adding the `discard` mount option to `/etc/fstab`, this option can hurt performance so the above procedure is recommended instead.
However, inside App and Template qubes, the `discard` mount option is on by default to notify the LVM thin pool driver that the space is no longer needed and can be zeroed and re-used.
If you are using Qubes with LVM, you may also want to set `issue_discards = 1` in `/etc/lvm/lvm.conf`.
Setting this option will permit LVM to issue discards to the SSD when logical volumes are shrunk or deleted.
In R4.x, LVM Logical volumes are frequently deleted (every time a disposable VM is shut down, for example) so you may want to set `issue_discards = 1` if using an SSD, but see the article linked in the first section of this page.
However, this is relatively rare in R3.x.
LUKS
----------
If you have enabled LUKS in dom0, discards will not get passed down to the storage device.
To enable TRIM support in dom0 with LUKS you need to:
1. Get your LUKS device UUID:
~~~
ls /dev/mapper/luks-*
~~~
2. Add entry to `/etc/crypttab` (replace luks-\<UUID\> with the device name and the \<UUID\> with UUID alone):
~~~
luks-<UUID> UUID=<UUID> none discard
~~~
3. Add `rd.luks.options=discard` to kernel cmdline (follow either GRUB2 or EFI, not both):
* GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and
Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`), then
Rebuild initrd (`dracut -f`)
* EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s), then
Rebuild initrd (`dracut -f /boot/efi/EFI/qubes/initramfs-$(uname -r).img $(uname -r)`)
4. Reboot the system.
5. To verify if discards are enabled you may use `dmsetup table` (confirm the line for your device mentions "discards") or just run `fstrim -av` (you should see a `/` followed by the number of bytes trimmed).
Swap Space
----------
By default TRIM is not enabled for swap.
To enable it add the `discard` flag to the options for the swap entry in `/etc/fstab`.
This may or may not actually improve performance.
If you only want the security against local forensics benefit of TRIM, you can use the `discard=once` option instead to only perform the TRIM operation once during at boot.
To verify that TRIM is enabled, check `dmesg` for what flags were enabled when the swap space was activated.
You should see something like the following:
Adding 32391164k swap on /dev/mapper/qubes_dom0-swap. Priority:-2 extents:1 across:32391164k SSDscFS
The `s` indicates that the entire swap device will be trimmed at boot, and `c` indicates that individual pages are trimmed after they are no longer being used.

55
configuration-guides/external-audio.md Normal file
View File

@ -0,0 +1,55 @@
---
layout: doc
title: External Audio
permalink: /doc/external-audio/
redirect_from:
- /en/doc/external-audio/
- /doc/ExternalAudio/
- /wiki/ExternalAudio/
---
Using External Audio Devices
============================
Why you want to use external audio devices
------------------------------------------
Qubes audio virtualization protocol does not implement latency reporting for security reasons, keeping the protocol as simple as possible.
Also, in a compromise between low latency and low CPU usage, latency may be around 200 ms.
So applications demanding higher audio quality (even Skype) need a better environment.
But Qubes flexibility fully allows that using external audio devices.
These are mostly USB audio cards, but firewire devices also might be used.
Implementing external audio devices
-----------------------------------
First you need to identify an user VM dedicated to audio and [assign a device](/doc/AssigningDevices) to it.
In the most common case the assigned device is the USB controller to which your USB audio card will be connected.
### Fedora VMs
In a terminal of the template from which you user VM depends, install pavucontrol with:
~~~
sudo dnf install pavucontrol
~~~
Close the template and start or restart your user VM, insert your external audio device, open a terminal and prepare pulseaudio to use it with:
~~~
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
~~~
Start the audio application that is going to use the external audio device.
Launch pavucontrol, for example using "run command in VM" of Qubes Manager and select your external audio card in pavucontrol.
You need to do that only the first time you use a new external audio device, then pulse audio will remember your selection.
If you detach your external audio device, then want to insert it again (or want to change it with another one), you need to repeat the previous commands in terminal adding another line at the beginning:
~~~
pactl unload-module module-udev-detect
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
~~~

93
configuration-guides/fetchmail.md Normal file
View File

@ -0,0 +1,93 @@
---
layout: doc
title: Fetchmail
permalink: /doc/fetchmail/
redirect_from:
- /en/doc/fetchmail/
- /doc/Fetchmail/
- /wiki/Fetchmail/
---
Fetchmail
=========
Fetchmail is standalone MRA (Mail Retrieval Agent) aka "IMAP/POP3 client". Its sole purpose is to fetch your messages and store it locally or feed to local MTA (Message Transfer Agent). It cannot "read" messages — for that, use a MUA like Thunderbird or [Mutt](/doc/mutt/).
Installation
------------
`dnf install fetchmail`
Configuration
-------------
Assuming you have more than one account (safe assumption these days), you need to spawn multiple fetchmail instances, one for each IMAP/POP3 server (though one instance can watch over several accounts on one server). The easiest way is to create template systemd unit and start it several times. Fedora does not supply any, so we have to write one anyway.
**NOTE:** this assumes you use [Postfix](/doc/postfix/) or Exim4 as your local MTA.
In TemplateVM create `/etc/systemd/system/fetchmail@.service`:
~~~
[Unit]
Description=Mail Retrieval Agent
After=network.target
Requires=postfix.service
[Service]
User=user
ExecStart=/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/etc/fetchmail/.%I.fetchids --pidfile /usr/local/etc/fetchmail/.%I.pid
RestartSec=1
~~~
Alternatively, in Debian with Exim4:
~~~
[Unit]
Description=Mail Retrieval Agent
After=network.target
Requires=exim4.service
[Service]
User=user
ExecStart=/usr/bin/fetchmail -f /usr/local/etc/fetchmail/%I.rc -d 60 -i /usr/local/etc/fetchmail/.%I.fetchids --pidfile /usr/local/etc/fetchmail/.%I.pid
RestartSec=1
~~~
Then shutdown TemplateVM, start AppVM and create directory `/usr/local/etc/fetchmail`. In it, create one `.rc` file for each instance of fetchmail, ie. `personal1.rc` and `personal2.rc`. Sample configuration file:
~~~
set syslog
set no bouncemail
#set daemon 600
poll mailserver1.com proto imap
no dns
uidl
tracepolls
user woju pass supersecret
ssl
sslproto "TLS1"
sslcertfile "/etc/pki/ca-trust/extracted/openssl/ca-bundle.trust.crt"
sslcertck
mda "/usr/sbin/sendmail -i -f %F -- user"
fetchall
idle
# vim: ft=fetchmail
~~~
Then `chown -R user:user /usr/local/etc/fetchmail` and `chmod 600 /usr/local/etc/fetchmail/*.rc`. **This is important**, fetchmail will refuse to run with wrong permissions on its rc-file.
Next, add this to `/rw/config/rc.local`:
~~~
#!/bin/sh
for rc in /usr/local/etc/fetchmail/*.rc; do
instance=${rc%.*}
instance=${instance##*/}
systemctl --no-block start fetchmail@${instance}
done
~~~
Now reboot your AppVM and you are done.

37
configuration-guides/gui-configuration.md Normal file
View File

@ -0,0 +1,37 @@
---
layout: doc
title: GUI Configuration and Troubleshooting
permalink: /doc/gui-configuration/
---
GUI Configuration and Troubleshooting
=====================================
Video RAM adjustment for high-resolution displays
-------------------------------------------------
**Problem:** You have a 4K external display, and when you connect it, you can't click on anything but a small area in the upper-right corner.
When a qube starts, a fixed amount of RAM is allocated to the graphics buffer called video RAM.
This buffer needs to be at least as big as the whole desktop, accounting for all displays that are or will be connected to the machine.
By default, it is as much as needed for the current display and an additional full HD (FHD) display (1920×1080 8 bit/channel RGBA).
This logic fails when the machine has primary display in FHD resolution and, after starting some qubes, a 4K display is connected.
The buffer is too small, and internal desktop resize fails.
**Solution:** Increase the minimum size of the video RAM buffer.
```sh
qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024))
qvm-features dom0 gui-videoram-overhead 0
```
Where `$WIDTH`×`$HEIGHT` is the maximum desktop size that you anticipate needing.
For example, if you expect to use a 1080p display and a 4k display side-by-side, that is `(1920 + 3840) × 2160 × 4 / 1024 = 48600`, or slightly more than 48 MiB per qube.
After making these adjustments, the qubes need to be restarted.
The amount of memory allocated per qube is the maximum of:
- `gui-videoram-min`
- current display + `gui-videoram-overhead`
Default overhead is about 8 MiB, which is enough for a 1080p display (see above).
So, the `gui-videoram-overhead` zeroing is not strictly necessary; it only avoids allocating memory that will not be used.

214
configuration-guides/multiboot.md Normal file
View File

@ -0,0 +1,214 @@
---
layout: doc
title: Multibooting
permalink: /doc/multiboot/
---
Multibooting Qubes
========================================
Introduction
---------------------
You should think carefully before dual booting Qubes on your box.
Read the [guidelines](/doc/security-guidelines) carefully.
One problem is that when you dual or multiboot, even if you are using
encryption on your Qubes installation, /boot is still unprotected and
could be maliciously modified by the other OS, possibly leading to Qubes
itself being maliciously modified.
The other problem is firmware security - for example the other system
could infect BIOS firmware, which might enable compromise or spying on
the Qubes system.
You can use [Anti Evil Maid](/doc/anti-evil-maid/), which would inform
you if /boot had been modified, but it cannot prevent or fix the problem.
If you have considered these issues, tried out the live system and want to
install Qubes alongside your existing OS, these notes should help.
They assume that you are installing Qubes on a PC where you already have
another OS installed.
The first thing to do is STOP.
Before you do anything else back up all your data.
If possible do a full system backup.
Back up the MBR.
Back up /boot.
If you are really paranoid clone your disc.
Make sure you have install discs to hand for the existing operating system.
Qubes by default does not include other systems in the generated grub menu,
because handling of other systems has been disabled. This means
that you will have to manually add grub entries for any other OS.
The general approach is:
* Enable legacy boot mode
* Ensure current OS boots in legacy mode.
* Install Qubes
* Manually add boot stanzas to /etc/grub.d/40_custom
* Update grub
Windows
----------------------
If you change boot mode to legacy boot almost certainly the Windows
installation will not boot.
You will either have to format the disk and reinitialise it, and then reinstall
Windows in legacy boot mode, or use a utility like Easy Recovery Essentials
which will change the existing installation to be bootable in both
UEFI/GPT and BIOS/MBR mode in-place, without losing any data.
At this stage you can install Qubes.
As noted above the default configuration will not add an entry for Windows to
the grub menu, so you will need to add one.
1. Boot into Qubes.
2. Identify the Windows system partition that has /bootmgr
In blkid output, the system partition is the one with LABEL='SYSTEM
RESERVED' or LABEL='SYSTEM' and is only about 100 to 200 MB in size
3. Add this stanza to /etc/grub.d/40_custom,
~~~
menuentry "Windows" {
insmod part_msdos
insmod ntldr
insmod ntfs
ntldr (hd1,X)/bootmgr
}
~~~
(Change `X` to reflect the relevant system partition.)
Then update the grub config:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
There is no need to reinstall grub itself.
If the above stanza does not work, you may try this one (at your own risk!)
instead:
~~~
menuentry "Windows" {
insmod part_msdos
insmod ntfs
set root='(hd0,msdosX)'
chainloader +1
}
~~~
(Change `X` to reflect the relevant system partition.)
Linux
----------------------
If you have had to change to legacy boot mode then you may have to reinstall grub in
the existing OS. (Make sure that you use grub rather than a grub-efi version).
Micah Lee
[suggests](https://micahflee.com/2014/04/dual-booting-qubes-and-ubuntu-with-encrypted-disks/)
installing grub to a partition, and then installing Qubes with grub
installed in MBR.
If you take this approach then you need to add to /etc/grub.d/40_custom in Qubes
dom0:
~~~
menuentry "Other Linux" {
set root=(hd1,X)
chainloader +1
}
(Change X to reflect the relevant partition where grub is installed.)
~~~
Then update the grub config:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
There is no need to reinstall grub itself.
Existing /boot partition, grub installed in MBR
----------------------
Most distros will have already installed grub to the MBR.
It is possible to use the *same* /boot for both OS.
To do this, do **NOT** choose the automatic configuration option when installing
Qubes.
Select 'custom' layout, and assign the existing /boot partition as /boot.
Deselect the 'Format' option.
Then continue with the installation.
This will install the qubes boot files in /boot *alongside* the existing files,
but overwrite the grub.cfg file in /boot/grub2.
If the other distro uses legacy grub you can simply copy the relevant sections
from /boot/grub/grub.cfg into /etc/grub.d/40_custom.
If the other distro uses grub2 then copy the relevant sections
from the backup you made into /etc/grub.d/40_custom.
Then update the grub config:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
Troubleshooting
----------------------
If you install Qubes without making any backups beforehand, don't worry.
If you didn't overwrite the original partitions, then it is usually
possible to recover your old systems relatively easily, as described above.
If you decided to use a shared /boot and *don't* have backups of your previous
grub config, it is quite easy to fix this.
This example may help.
* Boot into Qubes.
* Back up (at a minimum) /boot/grub2
* Identify the partition containing the other OS.
* Then mount the other OS and chroot in to it.
~~~
sudo mount /dev/sdX /mnt
sudo mount --bind /dev/sdY /mnt/boot
sudo mount --bind /dev /mnt/dev
sudo mount --bind /dev/pts /mnt/dev/pts
sudo mount --bind /proc /mnt/proc
sudo mount --bind /sys /mnt/sys
sudo chroot /mnt
~~~
* Update the grub config:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg.new
~~~
* Exit out the chroot, and reverse the mounts.
* Copy the relevant sections from /boot/grub2/grub.cfg.new in to
/etc/grub.d/40_custom.
* Update the grub config:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~

240
configuration-guides/multimedia.md Normal file
View File

@ -0,0 +1,240 @@
---
layout: doc
title: How to Make a Multimedia TemplateVM
permalink: /doc/multimedia/
redirect_from:
- /en/doc/multimedia/
- /doc/Multimedia/
- /wiki/Multimedia/
---
How to Make a Multimedia TemplateVM
===================================
Note: This Howto has been written and was tested under Qubes 4rc4
You can consolidate most of your media streaming tasks into one "multimedia" App-VM. This howto explains how to create a multimedia template which can be used to play multimedia content.
This includes:
- Spotify
- Amazon Prime
- Netflix
- DVDs
Installation
------------
Start by cloning the default debian template in dom0.
Hint:
t-multimedia is just the template VM where we will install all packages.
In the last step we will create an AppVM from this template.
`qvm-clone debian-9 t-multimedia`
Launch a Terminal in the new template VM:
`qvm-run --auto t-multimedia gnome-terminal`
Important:
Enter all the following commands in the terminal of the template VM
Become the root user to run all following command without the need to use sudo in the multimedia template VM
`sudo -i`
This howto assumes that you have xclip available in the AppVM where you download the Repository Signing keys.
xclip will be used to paste the content of the clipboard to a file.
You can install xclip via:
`apt-get install xclip` on Debian
`dnf install xclip` on Fedora
You can of course install xclip just into the AppVM where you download the signing keys to have it available for this howto and it will be deleted if you reboot the AppVM. To have xclip available also after a reboot you need to install it in the Template VM on which your Internet AppVM is based (make sure to reboot the AppVM after you've installed any package in its template)
Installation of Spotify
-----------------------
Import GPG-Key for spotify
As the template VM can't connect to internet you need to get the public key file from another AppVM and copy it to the template VM. The easiest way is to use the Qubes Clipboard to copy the keys from the AppVM where you get the key to the Template VM.
In an AppVM which has Internet access:
- Open <https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xA87FF9DF48BF1C90>
- Copy content of page to the Clipboard (Ctrl+A and Ctrl+C)
- open a Terminal in this AppVM and copy the content of the clipboard to a file
`xclip -o > spotify.pubkey`
Copy the public signing key over to the multimedia template VM
- copy the file via `qvm-copy-to-vm t-multimedia spotify.pubkey`
- or create a new file on the Template VM and copy the content of the clipboard (the public key)
Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C)
Switch to the gnome terminal in the Multimedia Template VM
`nano spotify.pubkey`
Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste)
Save the file (Ctrl+O <Enter> Ctrl+X)
Check the signature of the signing key (in the multimedia Template VM).
Hint: depending on your installed version of GnuPG the command to show a public might slightly be different.
See [this StackExchange question](https://unix.stackexchange.com/questions/391344/gnupg-command-to-show-key-info-from-file) for more information.
If this command doesn't show a fingerprint choose one of the other commands mentioned in the above link.
`gpg --with-fingerprint spotify.pubkey`
This should look like:
[user@t-multimedia ~]$ `gpg --with-fingerprint spotify.pubkey`
pub 4096R/48BF1C90 2018-05-23 Spotify Public Repository Signing Key <tux@spotify.com>
Key fingerprint = 931F F8E7 9F08 7613 4EDD BDCC A87F F9DF 48BF 1C90
You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated.
<https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0xA87FF9DF48BF1C90&fingerprint=on>
Add the public key to the repository keyring
`apt-key add spotify.pubkey`
Add the Spotify repository to your list of package sources:
`echo deb http://repository.spotify.com stable non-free > /etc/apt/sources.list.d/spotify.list`
Update the list of all known packages
`apt-get update`
Install Spotify
`apt-get install -y spotify-client`
Create a spotify desktop-entry
`cp -p /usr/share/spotify/spotify.desktop /usr/share/applications/`
`cp /usr/share/spotify/icons/spotify-linux-16.png /usr/share/icons/hicolor/16x16/apps/spotify.png`
Installation of VLC
-------------------
To play DVDs you can install VLC with the needed Codecs
Download the public key which signs the VLC package repositories
In an AppVM which has Internet access:
- Open <https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x6BCA5E4DB84288D9>
- Repeat all steps to save the public signing key on the AppVM (see above / Spotify example)
`xclip -o > videolan.pubkey`
Copy the public signing key over to the multimedia template VM
- copy the file via `qvm-copy-to-vm t-multimedia videolan.pubkey`
- or create a new file on the Template VM and copy the content of the clipboard (the public key)
Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C)
Switch to the gnome terminal in the Multimedia Template VM
`nano videolan.pubkey`
Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste)
Save the file (Ctrl+O <Enter> Ctrl+X)
Check the signature of the signing key
`gpg --with-fingerprint videolan.pubkey`
This should look like:
[user@t-multimedia ~]$ `gpg --with-fingerprint videolan.pubkey`
pub 2048R/B84288D9 2013-08-27 VideoLAN APT Signing Key <videolan@videolan.org>
Key fingerprint = 8F08 45FE 77B1 6294 429A 7934 6BCA 5E4D B842 88D9
sub 2048R/288D4A2C 2013-08-27
You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated.
<https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0x6BCA5E4DB84288D9&fingerprint=on>
Add the public key to the repository keyring
`apt-key add videolan.pubkey`
Add the new VLC package repositories to your list of sources
`echo "deb http://download.videolan.org/pub/debian/stable/ /" > /etc/apt/sources.list.d/vlc.list`
`echo "deb-src http://download.videolan.org/pub/debian/stable/ /" >> /etc/apt/sources.list.d/vlc.list`
Update package repositories
`apt-get update`
Install libdvdcss and VLC
`apt-get install -y libdvdcss2 vlc`
Installation Google Chrome
--------------------------
To play Videos with Netflix, Amazon Prime & Co using Chrome is a good option as it has all needed codecs included.
Hint: Using Chromium will not work for some reasons.
Download the public key which signs the Google package repositories
In an AppVM which has Internet access:
- Open <https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x7721F63BD38B4796>
- Repeat all steps to save the public signing key on the AppVM (see above / Spotify example)
`xclip -o > google.pubkey`
Copy the public signing key over to the multimedia template VM
- copy the file via `qvm-copy-to-vm t-multimedia google.pubkey`
- or create a new file on the Template VM and copy the content of the clipboard (the public key)
Copy content of page to the Qubes Clipboard (Ctrl+C and then Shift+Ctrl+C)
Switch to the gnome terminal in the Multimedia Template VM
`nano google.pubkey`
Paste the content from the Qubes Clipboard into nano (Shift+Ctrl+V and then Paste)
Save the file (Ctrl+O <Enter> Ctrl+X)
Check the signature of the signing key (still in the AppVM where you downloaded the key)
`gpg --with-fingerprint google.pubkey`
This should look like:
[user@t-multimedia ~]$ `gpg --with-fingerprint google.pubkey`
pub 4096R/D38B4796 2016-04-12 Google Inc. (Linux Packages Signing Authority)
<linux-packages-keymaster@google.com>
Key fingerprint = EB4C 1BFD 4F04 2F6D DDCC EC91 7721 F63B D38B 4796
sub 4096R/640DB551 2016-04-12 [expires: 2019-04-12]
sub 4096R/997C215E 2017-01-24 [expires: 2020-01-24]
You can (and should) lookup the fingerprint on at least one (or more) keyservers as the above information might be outdated.
<https://keyserver.ubuntu.com/pks/lookup?op=vindex&search=0x7721F63BD38B4796&fingerprint=on>
or
<https://www.google.com/linuxrepositories/>
Add the public key to the repository keyring
`apt-key add google.pubkey`
Add the Google package repositories to your list of sources
`echo "deb http://dl.google.com/linux/chrome/deb/ stable main"> /etc/apt/sources.list.d/google.list`
Update package repositories
`apt-get update`
Install Chrome
`apt-get install google-chrome-stable`
Create a Multimedia AppVM
-------------------------
The last step is to create a multimedia AppVM (named "my-multimedia" here) based on the new multimedia template.
`qvm-create --template t-multimedia --label orange my-multimedia`

222
configuration-guides/mutt.md Normal file
View File

@ -0,0 +1,222 @@
---
layout: doc
title: Mutt
permalink: /doc/mutt/
redirect_from:
- /en/doc/mutt/
- /doc/Mutt/
- /wiki/Mutt/
---
Mutt
====
Mutt is a fast, standards-compliant, efficient MUA (Mail User Agent). In some areas it works better than Thunderbird+Enigmail, and is certainly faster and more responsive.
Mutt lacks true MTA (Message Transfer Agent aka "SMTP client") and MRA (Mail
Retrieval Agent aka "IMAP/POP3 client"), thus there are some provisions
built-in. In principle it is only mail reader and composer. You may install
true MTA such as [Postfix](/doc/postfix/) or Exim and MRA such as
[Fetchmail](/doc/fetchmail/). Alternatively you can synchronize your mailbox
using [OfflineIMAP](https://github.com/OfflineIMAP/offlineimap) and just stick
to integrated SMTP support. You can even use integrated IMAP client, but it is
not very convenient.
Installation
------------
`dnf install mutt cyrus-sasl-plain`
`cyrus-sasl-plain` package is necessary for SMTP authentication to work.
Configuration
-------------
Mutt generally works out of the box. This configuration guide discusses only Qubes-specific setup. In this example we will have one TemplateVM and several AppVMs. It also takes advantage of [SplitGPG](/doc/split-gpg/), which is assumed to be already working.
**NOTE:** this requires `qubes-gpg-split >= 2.0.9`. 2.0.8 and earlier contains bug which causes this setup to hang in specific situations and does not allow to list keys.
First, paste this to `/etc/Muttrc.local` in TemplateVM:
~~~
# specify your key or override in ~/.mutt/muttrc in AppVM
set pgp_sign_as="0xDEADBEEF"
set pgp_use_gpg_agent = no
# this needs qubes-gpg-split >= 2.0.8; 2.0.7 end earlier has had a deadlock on this
set pgp_decode_command="qubes-gpg-client-wrapper --status-fd=2 --batch %f"
#set pgp_decode_command="gpg --status-fd=2 %?p?--passphrase-fd=0? --no-verbose --quiet --batch --output - %f"
set pgp_decrypt_command="$pgp_decode_command"
set pgp_verify_command="qubes-gpg-client-wrapper --status-fd=2 --no-verbose --quiet --batch --output - --verify %s %f"
set pgp_sign_command="qubes-gpg-client-wrapper --batch --armor --detach-sign --textmode %?a?-u %a? %f"
set pgp_clearsign_command="qubes-gpg-client-wrapper --batch --armor --textmode --clearsign %?a?-u %a? %f"
# I found no option to add Charset armor header when it is UTF-8, since this is
# default (as specified in RFC4880). This is needed to workaround bug in
# Enigmail, which ignores RFC and without this header Thunderbird interprets
# plaintext as us-ascii. See https://sourceforge.net/p/enigmail/bugs/38/.
### also note you must specify absolute path of pgpewrap when using debian
### e.g. /usr/lib/mutt/pgpewrap
set pgp_encrypt_only_command="pgpewrap qubes-gpg-client-wrapper --batch --textmode --armor --always-trust %?a?--encrypt-to %a? --encrypt -- -r %r -- %f | sed -e '2iCharset: UTF-8'"
set pgp_encrypt_sign_command="pgpewrap qubes-gpg-client-wrapper --batch --textmode --armor --always-trust %?a?--encrypt-to %a? --encrypt --sign %?a?-u %a? -- -r %r -- %f | sed -e '2iCharset: UTF-8'"
# we need to import both into vault and locally wrt $pgp_verify_command
set pgp_import_command="qubes-gpg-import-key %f; gpg --no-verbose --import %f"
# those are unsupported by split-gpg
set pgp_export_command="gpg --no-verbose --export --armor %r"
set pgp_verify_key_command="gpg --no-verbose --batch --fingerprint --check-sigs %r"
# read in the public key ring
set pgp_list_pubring_command="qubes-gpg-client-wrapper --no-verbose --batch --quiet --with-colons --list-keys %r"
# read in the secret key ring
set pgp_list_secring_command="qubes-gpg-client-wrapper --no-verbose --batch --quiet --with-colons --list-secret-keys %r"
# this set the number of seconds to keep in memory the passpharse used to encrypt/sign
# the more the less secure it will be
set pgp_timeout=600
# it's a regexp used against the GPG output: if it matches some line of the output
# then mutt considers the message a good signed one (ignoring the GPG exit code)
#set pgp_good_sign="^gpg: Good signature from"
set pgp_good_sign="^\\[GNUPG:\\] GOODSIG"
# mutt uses by default PGP/GPG to sign/encrypt messages
# if you want to use S-mime instead set the smime_is_default variable to yes
# automatically sign all outcoming messages
set crypt_autosign=yes
# sign only replies to signed messages
#set crypt_replysign
# automatically encrypt outcoming messages
#set crypt_autoencrypt=yes
# encrypt only replies to signed messages
set crypt_replyencrypt=yes
# encrypt and sign replies to encrypted messages
set crypt_replysignencrypted=yes
# automatically verify the sign of a message when opened
set crypt_verify_sig=yes
send-hook "~A" set pgp_autoinline=no crypt_autoencrypt=no
send-hook "~t @invisiblethingslab\.com" set crypt_autoencrypt=yes
# vim:ft=muttrc
~~~
Then shutdown your TemplateVM. Next open your AppVM, create file `/home/user/.mutt/muttrc` and adjust for your needs:
~~~
#
# accounts
#
set from = "Wojciech Zygmunt Porczyk <woju@invisiblethingslab.com>"
alternates '^woju@invisiblethingslab\.com$'
alternates '^wojciech@porczyk\.eu$'
#
# crypto
#
set pgp_sign_as = "0xDEADBEEF"
send-hook "~t @my\.family\.com" set crypt_autoencrypt=no
#
# lists
#
# google groups
lists .*@googlegroups\.com
subscribe (qubes-(users|devel)|othergroup)@googlegroups\.com
fcc-save-hook qubes-users@googlegroups\.com =list/qubes-users/
fcc-save-hook qubes-devel@googlegroups\.com =list/qubes-devel/
fcc-save-hook othergroup@googlegroups\.com =list/othergroup/
~~~
You may also create `/home/user/.signature`:
~~~
regards,
Wojciech Porczyk
~~~
Some additional useful settings
-------------------------------
In `muttrc`:
###qubes integration stuff
#open links in a dispvm using urlview
#see below for sample .urlview
macro pager \cb <pipe-entry>'urlview'<enter> 'Follow links with urlview'
#override default mailcap MIME settings with qvm-open-in-dvm calls
#see sample .mailcap below
set mailcap_path=~/.mailcap
bind attach <return> view-mailcap
Debian-specific options:
#use debian mutt-patched package for mailbox sidebar hack
set sidebar_width = 30
set sidebar_visible = no
set sidebar_delim='|'
#show/hide sidebar
macro index S '<enter-command>toggle sidebar_visible<enter>'
macro pager S '<enter-command>toggle sidebar_visible<enter>'
#navigate the sidebar folders
bind index CP sidebar-prev
bind index CN sidebar-next
bind index CO sidebar-open
bind pager CP sidebar-prev
bind pager CN sidebar-next
In `.urlview`:
### TODO: this doesn't work with encrypted emails --
### urlview can't find the links
###
COMMAND qvm-open-in-dvm %s
In `.mailcap`:
### TODO: override most/all default mailcap settings to prevent
### opening in muttvm
### is there a way to do this polymorphically? i.e. not
### listing every damn mimetype by hand
###
### also would be convenient to use mailcap's TEST feature to
### show some html in mutt pager (e.g. with w3m, links or html2text),
### else open others in dispvm
# MS Word documents
application/msword; qvm-open-in-dvm %s
application/vnd.oasis.opendocument.spreadsheet; qvm-open-in-dvm %s
application/vnd.oasis.opendocument.text; qvm-open-in-dvm %s
# Images
image/jpg; qvm-open-in-dvm %s
image/jpeg; qvm-open-in-dvm %s
image/png; qvm-open-in-dvm %s
image/gif; qvm-open-in-dvm %s
# PDFs
application/pdf; qvm-open-in-dvm %s
# HTML
text/html; qvm-open-in-dvm %s

146
configuration-guides/network-bridge-support.md Normal file
View File

@ -0,0 +1,146 @@
---
layout: doc
title: Network Bridge Support
permalink: /doc/network-bridge-support/
redirect_from:
- /en/doc/network-bridge-support/
- /doc/NetworkBridgeSupport/
- /wiki/NetworkBridgeSupport/
---
Network Bridge Support (EXPERIMENTAL and UNSUPPORTED)
=====================================================
The Qubes development team does not support bridging the network interfaces found in NetVM and don't plan to support it at all. Several reasons for that:
- Using a bridged VM is almost only necessary for developers testing or working on OSI layer 2 or layer 3 tools (MAC or routing protocols). If not for testing, such tools are almost only used directly on routers ...).
- Most of these tools can be anyway used directly inside the NetVM, which has direct access to the network card.
- It is also possible to use a secondary network card plugged into a specific development VM.
- Such a setup could break security features of Qubes such as AppVM firewalling.
Now if you really want to work with OSI layer2 / layer 3 tools, that you don't have a secondary network card, or that you want to completely expose services of a given AppVM (at your own risk), a bridged setup may help you.
Qubes manager patch (Qubes R2B2)
--------------------------------
The following patches can be applied to the Qubes Manager GUI in order to add an option to easily bridge a VM. Use it at your own risk. If the patch breaks the Qubes Manager, you can try to restore the Qubes packages:
~~~
# qubes-dom-update qubes-core-dom0 qubes-manager
# yum reinstall qubes-core-dom0
# yum reinstall qubes-manager
~~~
First, retrieve the attachment of this Wifi article in dom0. Then apply the three patches the following way after installing the patch tool :
~~~
# qubes-dom0-update patch
# patch /usr/lib64/python2.7/site-package/qubes/qubes.py < qubes.py-bridge.diff
# patch /usr/lib64/python2.7/site-package/qubesmanager/settings.py < settings.py-bridge.diff
# patch /usr/lib64/python2.7/site-package/qubesmanager/ui_settingsdlg.py < ui_settingsdlg.py-bridge.diff
~~~
Finally restart the qubes manager GUI.
An option is available in the AppVM Settings to enable setting the NetVM in bridge mode. For a bridged AppVM, you should then select a NetVM instead of a FirewallVM/ ProxyVM, enable the Bridge option, and restart your AppVM.
NetVM patch (Qubes R2B2)
------------------------
You need to modify manually the NetVM iptable script inside the NetVM. The reason is that by default the NetVM only accepts traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all traffic is NATed by default. In our case, we want to forward traffic from the bridge interface without modifying it, while NATing traffic coming from vif\* interfaces.
Modify manually the Template you use for your NetVM (not the NetVM itself). This is by default fedora-x86\_64. Edit the file /etc/sysconfig/iptables. You need to modify two parts of the file.
- Starting from the line -A POSTROUTING -j MASQUERADE that you need to comment :
~~~
# Bridge support
# Comment the following line
#-A POSTROUTING -j MASQUERADE
# Ensure packets coming from firewallVMs or AppVMs use NAT
-A POSTROUTING -m iprange --src-range 10.137.1.0-10.137.2.255 -j MASQUERADE
# Allow redirection of bridge packets (optional as POSTROUTING default is ACCEPT)
#-A POSTROUTING -o bridge+ -j ACCEPT
# End Bridge support
~~~
- Starting from the line -A FORWARD -i vif+ -j ACCEPT:
~~~
-A FORWARD -i vif+ -o vif+ -j DROP
-A FORWARD -i vif+ -j ACCEPT
# Bridge Support
-A FORWARD -i bridge+ -j ACCEPT
# End Bridge Support
-A FORWARD -j DROP
~~~
Ensure that the IP addresses used by default in Qubes are in the form 10.137.1.\* or 10.137.2.\* by running ifconfig. Of course, this setup won't work with IPv6.
Now you need to restart the NetVM and FirewallVM or only iptables in both VMs if you prefer:
~~~
# systemctl restart iptables
~~~
Create a Bridge inside the NetVM
--------------------------------
A bridge can be created inside the standard network manager (the network icon in the taskbar).
This requires:
- creating a bridge that will be your main IP (ex: setup the bridge with DHCP)
- attach eth0 to your bridge
Note: A wireless interface cannot be bridged.
The bridge edition GUI is somewhat buggy as it does not remember all the parameters you set up. You can fix it by editing manually the files in /etc/NetworkManager/system-connections/. Here is one example for these files:
- Bridge-DHCP
~~~
[connection]
id=Bridge-DHCP
uuid=fd68198b-313a-47cb-9155-52e95cdc67f3
type=bridge
autoconnect=false
timestamp=1363938302
[ipv6]
method=auto
[ipv4]
method=auto
[bridge]
interface-name=bridge0
stp=false
~~~
Note: Do not forget to put stp=false if you bridge only eth0 because sending BPDUs could make your admins angry :)
- bridge0-eth0
~~~
[802-3-ethernet]
duplex=full
mac-address=88:AE:1D:AE:30:31
[connection]
id=bridge0-eth0
uuid=38320e5b-226c-409e-9fd6-0fbf4d0460a0
type=802-3-ethernet
autoconnect=false
timestamp=1363601650
master=fd68198b-313a-47cb-9155-52e95cdc67f3
slave-type=bridge
~~~
If you do not manage to start your bridge, you can start it manually from a NetVM terminal:
~~~
$ nmcli con up id bridge0-eth0
~~~
Now that the bridge is ready, the bridged AppVM can be started...

55
configuration-guides/network-printer.md Normal file
View File

@ -0,0 +1,55 @@
---
layout: doc
title: Network Printer
permalink: /doc/network-printer/
redirect_from:
- /en/doc/network-printer/
- /doc/NetworkPrinter/
- /wiki/NetworkPrinter/
---
Configuring a network printer for Qubes AppVMs
==============================================
Where to configure printers and install drivers?
------------------------------------------------
One would normally want to configure a printer in a template VM, rather than in particular AppVMs.
This is because all the global settings made to AppVMs (those stored in its /etc, as well as binaries installed in /usr) would be discarded upon AppVM shutdown.
When printer is added and configured in a template VM, then all the AppVMs based on this template should automatically be able to use it (without the need for the template VM to be running, of course).
Alternatively one can add a printer in a standalone VM, but this would limit the printer usage to this particular VM.
Security considerations for network printers and drivers
--------------------------------------------------------
Some printers require third-party drivers, typically downloadable from the vendor's website.
Such drivers are typically distributed in a form of ready to install RPM packages.
However, they are often unsigned, and additionally the downloads are available via HTTP connections only.
As a result, installation of such third-party RPMs in a default template VM exposes a risk of compromise of this template VM, which, in turn, leads automatically to compromise of all the AppVMs based on the template.
(Again, it's not buggy or malicious drivers that we fear here, but rather malicious installation scripts for those drivers).
In order to mitigate this risk, one might consider creating a custom template (i.e. clone the original template) and then install the third-party, unverified drivers there.
Such template might then be made a DVM template for [DisposableVM creation](/doc/disposablevm/), which should allow one to print any document by right-clicking on it, choosing "Open in DisposableVM" and print from there.
This would allow to print documents from more trusted AppVMs (based on a trusted default template that is not poisoned by third-party printer drivers).
However, one should be aware that most (all?) network printing protocols are insecure, unencrypted protocols.
This means, that an attacker who is able to sniff the local network, or who is controlling the (normally untrusted) Qubes NetVM, will likely to be able to see the documents being printed.
This is a limitation of today's printers and printing protocols, something that cannot be solved by Qubes or any other OS.
Additionally, the printer drivers as well as CUPS application itself, might be buggy and might get exploited when talking to a compromised printer (or by an attacker who controls the local network, or the default NetVM).
Consider not using printing from your more trusted AppVMs for this reason.
Steps to configure a network printer in a template VM
----------------------------------------------------------
1. Start the "Printer Settings" App in a template VM (either via Qubes "Start Menu", or by launching the `system-config-printer` in the template).
2. Add/Configure the printer in the same way as one would do on any normal Linux.
You may need to allow network access from the template VM to your printer to complete configuration, as normally the template VM is not allowed any network access except to the Qubes proxy for software installation.
One can use Qubes Manager to modify firewall rules for particular VMs.
3. Optional: Test the printer by printing a test page. If it works, shut down the template VM.
4. Open an AppVM (make sure it's based on the template where you just installed the printer, normally all AppVMs are based on the default template), and test if printing works.
If it doesn't then probably the AppVM doesn't have networking access to the printer -- in that case adjust the firewall settings for that AppVM in Qubes Manager.
Also, make sure that the AppVM gets restarted after the template was shutdown.
5. Alternatively if you do not want to modify the firewall rules of the template VM (that have security scope) you can simply shut down the template VM without trying to print the test page (which will not work), start or restart an AppVM based on the template and test printing there.

155
configuration-guides/postfix.md Normal file
View File

@ -0,0 +1,155 @@
---
layout: doc
title: Postfix
permalink: /doc/postfix/
redirect_from:
- /en/doc/postfix/
- /doc/Postfix/
- /wiki/Postfix/
---
Postfix
=======
Postfix is full featured MTA (Message Transfer Agent). Here we will configure it in smarthost mode as part of common [Mutt](/doc/mutt/)+Postfix+[Fetchmail](/doc/fetchmail/) stack.
Installation
------------
`dnf install postfix procmail make cyrus-sasl cyrus-sasl-plain`
Cyrus-sasl is installed to authenticate to remote servers. Procmail is not strictly necessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not necessary, but is used to keep Postfix lookup tables.
You should also check `alternatives` command, to see if it is the default `mta`. It probably is not. You may need to `dnf remove ssmtp` or something
Configuration
-------------
In TemplateVM open `/etc/aliases` and add line:
~~~
root: user
~~~
and run `newaliases`.
This is the only thing to do in TemplateVM, as MTA configuration is AppVM specific, so we will keep it in `/usr/local` (ie. `/rw/usrlocal`) in each AppVM.
Now shutdown TemplateVM, start AppVM. Create directory `/usr/local/etc/postfix` and copy `/etc/postfix/master.cf` and `/etc/postfix/postfix-files` there.
### Makefile
Postfix keeps its lookup tables in bdb hash databases. They need to be compiled from source files. Postfix admins like to keep track of them by means of `/usr/local/etc/postfix/Makefile`:
~~~
all: $(addsuffix .db,$(shell sed -n -e '/^[^#].*hash:\/etc\/postfix/s:.*/::p' main.cf))
newaliases
clean:
$(RM) *.db
.PHONY: all clean
%.db: %
/usr/sbin/postmap hash:$<
~~~
### Postfix main configuration
`/usr/local/etc/postfix/main.cf` (`/etc/postfix` is intentional, don't correct it):
~~~
mydestination = $myhostname, $myhostname.$mydomain, $myhostname.localdomain, localhost, localhost.$mydomain, localhost.localdomain, $mydomain, localdomain
mynetworks_style = host
inet_protocols = ipv4
smtp_generic_maps = hash:/etc/postfix/generic
local_header_rewrite_clients =
smtp_sender_dependent_authentication = yes
sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/saslpass
smtp_sasl_security_options =
smtp_tls_security_level = encrypt
smtp_sasl_mechanism_filter = plain, login
smtpd_relay_restrictions = permit_mynetworks,permit_sasl_authenticated,defer_unauth_destination
smtpd_sender_restrictions = check_sender_access hash:/etc/postfix/sender_access
home_mailbox = .maildir/
setgid_group = postdrop
mail_owner = postfix
html_directory = no
manpage_directory = /usr/share/man
queue_directory = /var/spool/postfix
readme_directory = no
mailbox_command = /usr/bin/procmail
sendmail_path = /usr/sbin/sendmail
newaliases_path = /usr/bin/newaliases
mailq_path = /usr/bin/mailq
alias_maps = hash:/etc/aliases
~~~
### Lookup tables
`/usr/local/etc/postfix/generic` (put there your primary address):
~~~
@localhost your.mail@example.com
~~~
`/usr/local/etc/postfix/sender_relay`. This is an important file. Put all your SMTP servers there. Pay attention to port (smtp/submission). Square brackets have their special meaning, they are almost certainly needed. For more info consult Postfix manual.
~~~
your.mail@exmaple.com [mail.example.com]:submission
your.other@mail.com [smtp.mail.com]:smtp
~~~
`/usr/local/etc/postfix/saslpass`. Here you put passwords to above mentioned servers. It depends on your provider if you need to put whole email as username or just the part before `@`.
~~~
[mail.example.com]:submission your.mail:y0urP4ssw0rd
[smtp.mail.com]:smtp your.other@mail.com:supers3cret
~~~
`/usr/local/etc/postfix/sender_access`. I use it to nullroute known spam domains. If you do not need it, comment respective line in `main.cf`.
~~~
spamdomain1.com DISCARD
spamdomain2.com DISCARD
~~~
Now run `make` in `/usr/local/etc/postfix`. It will hopefully compile four above mentioned lookup tables (`generic.db`, `sender_relay.db`, `saslpass.db` and `sender_access`).
### procmail
Don't start postfix or fetchmail yet, first create `/home/user/.procmailrc`:
~~~
MAILDIR = "${HOME}/.maildir"
ORGMAIL = "${MAILDIR}/"
DEFAULT = "${MAILDIR}/"
:0
* ^List-Id:.*qubes-users\.googlegroups\.com
list/qubes-users/
:0
* ^List-Id:.*qubes-devel\.googlegroups\.com
list/qubes-devel/
~~~
Run
---
Open `/rw/config/rc.local` and add those two lines (before fetchmail lines, if you have them):
~~~
#!/bin/sh
mount --bind /usr/local/etc/postfix /etc/postfix
systemctl --no-block start postfix
~~~
Make sure `/rw/config/rc.local` is executable (i.e., `chmod a+x /rw/config/rc.local`). Reboot your AppVM and you are done.

76
configuration-guides/resize-disk-image.md Normal file
View File

@ -0,0 +1,76 @@
---
layout: doc
title: Resize Disk Image
permalink: /doc/resize-disk-image/
redirect_from:
- /en/doc/resize-disk-image/
- /en/doc/resize-root-disk-image/
- /doc/ResizeDiskImage/
- /doc/ResizeRootDiskImage/
- /wiki/ResizeDiskImage/
- /wiki/ResizeRootDiskImage/
---
Resize Disk Image
-----------------
There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images.
In most cases, the GUI tool Qube Settings (available for every qube from the Start menu, and also in the Qube Manager) will allow you to easily increase maximum disk image size.
![vm-settings-disk-image.png](/attachment/wiki/DiskSize/vm-settings-disk-image.png)
In case of standalone qubes and templates, just change the Disk Storage settings above.
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/#appvms-qubes-and-templatevms), and so it must be changed in the template settings.
If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below.
See also the OS-specific follow-up instructions below.
### Resize disk image
Use either GUI tool Qube Settings (`qubes-vm-settings`) or the CLI tool `qvm-volume`.
Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you need more, use `qvm-volume`:
~~~
qvm-volume extend <vm_name>:root <size>
~~~
OR
~~~
qvm-volume extend <vm_name>:private <size>
~~~
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
If you have run out of space for software in your Template, you need to increase *root image* of the Template (not private storage!).
**Make sure changes in the Template between reboots don't exceed 10G.**
It is recommended to restart (or start and then shutdown, if it is not running) the template after resizing the root image.
If you are **not** using Linux in the qube, you will also need to:
1. Start the template.
2. Resize the filesystem using OS appropriate tools.
3. Verify available space in the template using `df -h` or OS specific tools.
4. Shutdown the template.
#### Windows 7
1. Click Start
2. type "diskmgmt.msc" - this takes you to Disk Management
3. Right-click on your existing volume, select "Extend Volume..."
4. Click through the wizard.
No reboot required.
#### FreeBSD
~~~
gpart recover ada0
sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
~~~
#### Linux
Qubes will automatically grow the filesystem for you on all AppVMs with Qubes packages installed (which are all AppVMs installed from templates, cloned from templates etc. - if you have not created an empty HVM and installed a Linux distribution in it, without using Qubes repositories, you are almost certainly safe).
Otherwise, you will see that there is unallocated free space at the end of your primary disk.
You can use standard linux tools like `fdisk` and `resize2fs` to make this space available.

152
configuration-guides/rxvt.md Normal file
View File

@ -0,0 +1,152 @@
---
layout: doc
title: Rxvt
permalink: /doc/rxvt/
redirect_from:
- /en/doc/rxvt/
- /doc/Rxvt/
- /wiki/Rxvt/
---
Rxvt
====
`rxvt-unicode` is an advanced and efficient vt102 emulator. Here is a quick guide to configuration in both dom0 and guest VM.
Installation
------------
`dnf install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension.
Let me also recommend excellent Terminus font: `dnf install terminus-fonts`.
Xresources
----------
In TemplateVM create file `/etc/X11/Xresources.urxvt` and paste config below.
`!`-lines are comments and may be left out.
`#`-lines are directives to CPP (C preprocessor) and are necessary.
This shouldn't go to `/etc/X11/Xresources`, because that file is not preprocessed by default.
~~~
! CGA colour palette
!*color0: #000000
!*color1: #AA0000
!*color2: #00AA00
!*color3: #AA5500
!*color4: #0000AA
!*color5: #AA00AA
!*color6: #00AAAA
!*color7: #AAAAAA
!*color8: #555555
!*color9: #FF5555
!*color10: #55FF55
!*color11: #FFFF55
!*color12: #5555FF
!*color13: #FF55FF
!*color14: #55FFFF
!*color15: #FFFFFF
! Qubes' favourite tango palette (improved with cyan)
#define TANGO_Butter1 #c4a000
#define TANGO_Butter2 #edd400
#define TANGO_Butter3 #fce94f
#define TANGO_Orange1 #ce5c00
#define TANGO_Orange2 #f57900
#define TANGO_Orange3 #fcaf3e
#define TANGO_Chocolate1 #8f5902
#define TANGO_Chocolate2 #c17d11
#define TANGO_Chocolate3 #e9b96e
#define TANGO_Chameleon1 #4e9a06
#define TANGO_Chameleon2 #73d216
#define TANGO_Chameleon3 #8ae234
#define TANGO_SkyBlue1 #204a87
#define TANGO_SkyBlue2 #3465a4
#define TANGO_SkyBlue3 #729fcf
#define TANGO_Plum1 #5c3566
#define TANGO_Plum2 #75507b
#define TANGO_Plum3 #ad7fa8
#define TANGO_ScarletRed1 #a40000
#define TANGO_ScarletRed2 #cc0000
#define TANGO_ScarletRed3 #ef2929
#define TANGO_Aluminium1 #2e3436
#define TANGO_Aluminium2 #555753
#define TANGO_Aluminium3 #888a85
#define TANGO_Aluminium4 #babdb6
#define TANGO_Aluminium5 #d3d7cf
#define TANGO_Aluminium6 #eeeeec
*color0: TANGO_Aluminium1
*color1: TANGO_ScarletRed2
*color2: TANGO_Chameleon1
*color3: TANGO_Chocolate2
*color4: TANGO_SkyBlue1
*color5: TANGO_Plum2
*color6: #06989a
*color7: TANGO_Aluminium4
*color8: TANGO_Aluminium3
*color9: TANGO_ScarletRed3
*color10: TANGO_Chameleon3
*color11: TANGO_Butter3
*color12: TANGO_SkyBlue3
*color13: TANGO_Plum3
*color14: #34e2e2
*color15: TANGO_Aluminium6
URxvt.foreground: #E0E0E0
!URxvt.background: black
!URxvt.cursorColor: rgb:ffff/0000/0000
URxvt.cursorColor: TANGO_ScarletRed3
!URxvt.font: -*-terminus-*-*-*-*-14-*-*-*-*-*-iso8859-2
!URxvt.boldFont: -*-terminus-*-*-*-*-14-*-*-*-*-*-iso8859-2
URxvt.font: xft:Terminus:pixelsize=14:style=Bold
URxvt.boldFont: xft:Terminus:pixelsize=14:style=Bold
URxvt.italicFont: xft:Terminus:pixelsize=14:style=Regular
URxvt.boldItalicFont: xft:Terminus:pixelsize=14:style=Regular
URxvt.scrollBar: False
URxvt.visualBell: False
! Qubes X11 passthrough does not support those, but in dom0 they are nice.
URxvt.background: rgba:0000/0000/0000/afff
URxvt.depth: 32
URxvt.urgentOnBell: True
! TODO: write qubes-rpc to handle printing
URxvt.print-pipe: cat > $(TMPDIR=$HOME mktemp urxvt.XXXXXX)
! selection-to-clipboard violates
! http://standards.freedesktop.org/clipboards-spec/clipboards-latest.txt [1],
! but it does for greater good: urxvt has no other means to move PRIMARY to
! CLIPBOARD, so Qubes' clipboard won't work without it. Also the rationale given
! in [1] has little relevance to advanced terminal emulator, specifically there
! is no need for w32-style intuition and virtually no need to "paste over".
URxvt.perl-ext-common: default,selection-to-clipboard
! Prevent rxvt from entering Keyboard symbols entry mode whenever you press
! ctrl+shift, e.g. to copy or paste something to/from Qubes' clipboard.
URxvt.iso14755_52: false
URxvt.insecure: False
! some termcap-aware software sometimes throw '$TERM too long'
!URxvt.termName: rxvt-256color
~~~
Then create script to automatically merge those to xrdb.
File `/etc/X11/xinit/xinitrc.d/urxvt.sh`:
~~~
#!/bin/sh
[ -r /etc/X11/Xresources.urxvt ] && xrdb -merge /etc/X11/Xresources.urxvt
~~~
Shortcuts
---------
For each AppVM, go to *Qubes Manager \> VM Settings \> Applications*.
Find `rxvt-unicode` (or `rxvt-unicode (256-color) multi-language`) and add.

62
configuration-guides/tips-and-tricks.md Normal file
View File

@ -0,0 +1,62 @@
---
layout: doc
title: Tips and Tricks
permalink: /doc/tips-and-tricks/
---
Tips and Tricks
===============
This section provides user suggested tips that aim to increase Qubes OS usability, security or that allow users to discover new ways to use your computer that are unique to Qubes OS.
Opening links in your preferred AppVM
-------------------------------------
To increase both security and usability you can set an AppVM so that it automatically opens any link in an different AppVM of your choice. You can do this for example in the email AppVM, in this way you avoid to make mistakes like opening links in it. To learn more you can check [security guidelines](/doc/security-guidelines/) and [security goals](/security/goals/).
The command `qvm-open-in-vm` lets you open a document or a URL in another VM. It takes two parameters: vmname and filename.
For example, if you launch this command from your email AppVM:
`qvm-open-in-vm untrusted https://duckduckgo.com`
it will open duckduckgo.com in the `untrusted` AppVM (after you confirmed the request).
If you want this to happen automatically you can create a .desktop file that advertises itself as a handler for http/https links, and then set this as your default browser.
Open a text editor and copy and paste this into it:
[Desktop Entry]
Encoding=UTF-8
Name=BrowserVM
Exec=qvm-open-in-vm APPVMNAME %u
Terminal=false
X-MultipleArgs=false
Type=Application
Categories=Network;WebBrowser;
MimeType=x-scheme-handler/unknown;x-scheme-handler/about;text/html;text/xml;application/xhtml+xml;application/xml;application/vnd.mozilla.xul+xml;application/rss+xml;application/rdf+xml;image/gif;image/jpeg;image/png;x-scheme-handler/http;x-scheme-handler/https;
Replace `APPVMNAME` with the AppVM name you want to open links in. Now save, in the AppVM that you want to modify, this file to `~/.local/share/applications/browser_vm.desktop`
Finally, set it as your default browser:
`xdg-settings set default-web-browser browser_vm.desktop`
Credit: [Micah Lee](https://micahflee.com/2016/06/qubes-tip-opening-links-in-your-preferred-appvm/)
Preventing data leaks
---------------------
First make sure to read [Understanding and Preventing Data Leaks](/doc/data-leaks/) section to understand the limits of this tip.
Suppose that you have within a not so trusted environment - for example, a Windows VM - an application that tracks and reports its usage, or you simply want to protect your data.
Start the Windows TemplateVM (which has no user data), install/upgrade apps; then start Windows AppVM (with data) in offline mode. So, if you worry (hypothetically) that your Windows or app updater might want to send your data away, this Qubes OS trick will prevent this.
This applies also to any TemplateBasedVM relative to its parent TemplateVM, but the privacy risk is especially high in the case of Windows.
Credit: [Joanna Rutkovska](https://twitter.com/rootkovska/status/832571372085850112)
Trim for standalone AppVMs
---------------------
The `qvm-trim-template` command is not available for a standalone AppVM.
It is still possible to trim the AppVM disks by using the `fstrim --all` command from the appvm.
You can also add the `discard` option to the mount line in `/etc/fstab` inside the standalone AppVM if you want trimming to be performed automatically, but there may be a performance impact on writes and deletes.

324
configuration-guides/vpn.md Normal file
View File

@ -0,0 +1,324 @@
---
layout: doc
title: VPN
permalink: /doc/vpn/
redirect_from:
- /doc/privacy/vpn/
- /en/doc/vpn/
- /doc/VPN/
- /wiki/VPN/
---
How To make a VPN Gateway in Qubes
==================================
Although setting up a VPN connection is not by itself Qubes specific, Qubes includes a number of tools that can make the client-side setup of your VPN more versatile and secure. This document is a Qubes-specific outline for choosing the type of VM to use, and shows how to prepare a ProxyVM for either NetworkManager or a set of fail-safe VPN scripts.
Please refer to your guest OS and VPN service documentation when considering the specific steps and parameters for your connection(s); The relevant documentation for the Qubes default guest OS (Fedora) is [Establishing a VPN Connection.](https://docs.fedoraproject.org/en-US/Fedora/23/html/Networking_Guide/sec-Establishing_a_VPN_Connection.html)
### NetVM
The simplest case is to set up a VPN connection using the NetworkManager service inside your NetVM. Because the NetworkManager service is already started, you are ready to set up your VPN connection. However this has some disadvantages:
- You have to place (and probably save) your VPN credentials inside the NetVM, which is directly connected to the outside world
- All your AppVMs which are connected to the NetVM will be connected to the VPN (by default)
### AppVM
While the NetworkManager service is not started here (for a good reason), you can configure any kind of VPN client in your AppVM as well. However this is only suggested if your VPN client has special requirements.
### ProxyVM
One of the best unique features of Qubes OS is its special type of VM called a ProxyVM. The special thing is that your AppVMs see this as a NetVM (or uplink), and your NetVMs see it as a downstream AppVM. Because of this, you can place a ProxyVM between your AppVMs and your NetVM. This is how the default sys-firewall VM functions.
Using a ProxyVM to set up a VPN client gives you the ability to:
- Separate your VPN credentials from your NetVM.
- Separate your VPN credentials from your AppVM data.
- Easily control which of your AppVMs are connected to your VPN by simply setting it as a NetVM of the desired AppVM.
Set up a ProxyVM as a VPN gateway using NetworkManager
------------------------------------------------------
1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template.
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
2. Add the `network-manager` service to this new VM.
![Settings-services.png](/attachment/wiki/VPN/Settings-services.png)
3. Set up your VPN as described in the NetworkManager documentation linked above.
4. (Optional) Make your VPN start automatically.
Edit `/rw/config/rc.local` and add these lines:
```bash
# Automatically connect to the VPN once Internet is up
while ! ping -c 1 -W 1 1.1.1.1; do
sleep 1
done
PWDFILE="/rw/config/NM-system-connections/secrets/passwd-file.txt"
nmcli connection up file-vpn-conn passwd-file $PWDFILE
```
You can find the actual "file-vpn-conn" in `/rw/config/NM-system-connections/`.
Create directory `/rw/config/NM-system-connections/secrets/` (You can put your `*.crt` and `*.pem` files here too).
Create a new file `/rw/config/NM-system-connections/secrets/passwd-file.txt`:
```
vpn.secrets.password:XXXXXXXXXXXXXX
```
And substitute "XXXXXXXXXXXXXX" for the actual password.
The contents of `passwd-file.txt` may differ depending on your VPN settings. See the [documentation for `nmcli up`](https://www.mankier.com/1/nmcli#up).
5. (Optional) Make the network fail-close for the AppVMs if the connection to the VPN breaks.
Edit `/rw/config/qubes-firewall-user-script` and add these lines:
```bash
# Block forwarding of connections through upstream network device
# (in case the vpn tunnel breaks)
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
ip6tables -I FORWARD -o eth0 -j DROP
ip6tables -I FORWARD -i eth0 -j DROP
```
6. Configure your AppVMs to use the new VM as a NetVM.
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
7. Optionally, you can install some [custom icons](https://github.com/Zrubi/qubes-artwork-proxy-vpn) for your VPN
Set up a ProxyVM as a VPN gateway using iptables and CLI scripts
----------------------------------------------------------------
This method is more involved than the one above, but has anti-leak features that also make the connection _fail closed_ should it be interrupted.
It has been tested with Fedora 23 and Debian 8 templates.
1. Create a new VM, name it, click the ProxyVM radio button, and choose a color and template.
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
Note: Do not enable NetworkManager in the ProxyVM, as it can interfere with the scripts' DNS features.
If you enabled NetworkManager or used other methods in a previous attempt, do not re-use the old ProxyVM...
Create a new one according to this step.
If your choice of TemplateVM doesn't already have the VPN client software, you'll need to install the software in the template before proceeding.
Disable any auto-starting service that comes with the software package.
For example for OpenVPN.
sudo systemctl disable openvpn.service
You may also wish to install `nano` or another simple text editor for entering the scripts below.
2. Set up and test the VPN client.
Make sure the VPN VM and its TemplateVM is not running.
Run a terminal (CLI) in the VPN VM -- this will start the VM.
Then create a new `/rw/config/vpn` folder with.
sudo mkdir /rw/config/vpn
Copy your VPN config files to `/rw/config/vpn`.
Your VPN config file should be named `openvpn-client.ovpn`) so you can use the scripts below as is without modification.
Otherwise you would have to replace the file name.
`openvpn-client.ovpn` contents:
* Files accompanying the main config such as `*.crt` and `*.pem` should also go to `/rw/config/vpn` folder.
* Files referenced in `openvpn-client.ovpn` should not use absolute paths such as `/etc/...`.
The VPN scripts here are intended to work with commonly used `tun` interfaces, whereas `tap` mode is untested.
Also, the config should route all traffic through your VPN's interface after a connection is created; For OpenVPN the directive for this is `redirect-gateway def1`.
sudo nano /rw/config/vpn/openvpn-client.ovpn
Make sure it already includes or add:
redirect-gateway def1
The VPN client may not be able to prompt you for credentials when connecting to the server.
Create a file in the `/rw/config/vpn` folder with your credentials and using a directive.
For example for OpenVPN, add:
auth-user-pass pass.txt
Save file `/rw/config/vpn/openvpn-client.ovpn`.
Make sure a `/rw/config/vpn/pass.txt` file actually exists.
sudo nano /rw/config/vpn/pass.txt
Add:
username
password
Replace `username` and `password` with your actual username and password.
**Test your client configuration:**
Run the client from a CLI prompt in the 'vpn' folder, preferably as root.
For example:
sudo openvpn --cd /rw/config/vpn --config openvpn-client.ovpn
Watch for status messages that indicate whether the connection is successful and test from another VPN VM terminal window with `ping`.
ping 8.8.8.8
`ping` can be aborted by pressing the two keys `ctrl` + `c` at the same time.
DNS may be tested at this point by replacing addresses in `/etc/resolv.conf` with ones appropriate for your VPN (although this file will not be used when setup is complete).
Diagnose any connection problems using resources such as client documentation and help from your VPN service provider.
Proceed to the next step when you're sure the basic VPN connection is working.
3. Create the DNS-handling script.
sudo nano /rw/config/vpn/qubes-vpn-handler.sh
Edit and add:
~~~
#!/bin/bash
set -e
export PATH="$PATH:/usr/sbin:/sbin"
case "$1" in
up)
# To override DHCP DNS, assign DNS addresses to 'vpn_dns' env variable before calling this script;
# Format is 'X.X.X.X Y.Y.Y.Y [...]'
if [[ -z "$vpn_dns" ]] ; then
# Parses DHCP foreign_option_* vars to automatically set DNS address translation:
for optionname in ${!foreign_option_*} ; do
option="${!optionname}"
unset fops; fops=($option)
if [ ${fops[1]} == "DNS" ] ; then vpn_dns="$vpn_dns ${fops[2]}" ; fi
done
fi
iptables -t nat -F PR-QBS
if [[ -n "$vpn_dns" ]] ; then
# Set DNS address translation in firewall:
for addr in $vpn_dns; do
iptables -t nat -A PR-QBS -i vif+ -p udp --dport 53 -j DNAT --to $addr
iptables -t nat -A PR-QBS -i vif+ -p tcp --dport 53 -j DNAT --to $addr
done
su - -c 'notify-send "$(hostname): LINK IS UP." --icon=network-idle' user
else
su - -c 'notify-send "$(hostname): LINK UP, NO DNS!" --icon=dialog-error' user
fi
;;
down)
su - -c 'notify-send "$(hostname): LINK IS DOWN !" --icon=dialog-error' user
;;
esac
~~~
Save the script.
Make it executable.
sudo chmod +x /rw/config/vpn/qubes-vpn-handler.sh
4. Configure client to use the DNS handling script. Using openvpn as an example, edit the config.
sudo nano /rw/config/vpn/openvpn-client.ovpn
Add the following.
script-security 2
up 'qubes-vpn-handler.sh up'
down 'qubes-vpn-handler.sh down'
Remove other instances of lines starting with `script-security`, `up` or `down` should there be any others.
Save the script.
**Restart the client and test the connection again** ...this time from an AppVM!
5. Set up iptables anti-leak rules.
Edit the firewall script.
sudo nano /rw/config/qubes-firewall-user-script
Clear out the existing lines and add:
~~~
#!/bin/bash
# Block forwarding of connections through upstream network device
# (in case the vpn tunnel breaks):
iptables -I FORWARD -o eth0 -j DROP
iptables -I FORWARD -i eth0 -j DROP
ip6tables -I FORWARD -o eth0 -j DROP
ip6tables -I FORWARD -i eth0 -j DROP
# Block all outgoing traffic
iptables -P OUTPUT DROP
iptables -F OUTPUT
iptables -I OUTPUT -o lo -j ACCEPT
# Add the `qvpn` group to system, if it doesn't already exist
if ! grep -q "^qvpn:" /etc/group ; then
groupadd -rf qvpn
sync
fi
sleep 2s
# Allow traffic from the `qvpn` group to the uplink interface (eth0);
# Our VPN client will run with group `qvpn`.
iptables -I OUTPUT -p all -o eth0 -m owner --gid-owner qvpn -j ACCEPT
~~~
Save the script.
Make it executable.
sudo chmod +x /rw/config/qubes-firewall-user-script
5. Set up the VPN's autostart.
sudo nano /rw/config/rc.local
Clear out the existing lines and add:
~~~
#!/bin/bash
VPN_CLIENT='openvpn'
VPN_OPTIONS='--cd /rw/config/vpn/ --config openvpn-client.ovpn --daemon'
su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user
groupadd -rf qvpn ; sleep 2s
sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS"
~~~
If you are using anything other than OpenVPN, change the `VPN_CLIENT` and `VPN_OPTIONS` variables to match your VPN software.
Save the script.
Make it executable.
sudo chmod +x /rw/config/rc.local
6. Restart the new VM!
The link should then be established automatically with a popup notification to that effect.
Usage
-----
Configure your AppVMs to use the VPN VM as a NetVM...
![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)
If you want to be able to use the [Qubes firewall](/doc/firewall), create a new FirewallVM (as a ProxyVM) and set it to use the VPN VM as its NetVM.
Then, configure AppVMs to use your new FirewallVM as their NetVM.
If you want to update your TemplateVMs through the VPN, enable the `qubes-updates-proxy` service in your new FirewallVM.
You can do this in the Services tab in Qubes VM Manager or on the command-line:
qvm-service -e <name> qubes-updates-proxy
Then, configure your templates to use your new FirewallVM as their NetVM.
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.
* For scripting: Ping external IP addresses from inside the VPN VM using `sudo sg qvpn -c 'ping ...'`, then from an appVM using just `ping ...`. Once the firewall rules are in place, you will have to use `sudo sg` to run any IP network commands in the VPN VM.
* 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.

40
configuration-guides/w3m.md Normal file
View File

@ -0,0 +1,40 @@
---
layout: doc
title: Reducing the fingerprint of the text-based web browser w3m
permalink: /doc/w3m/
redirect_from:
- /en/doc/mutt/
- /doc/W3m/
- /wiki/W3m/
---
Reducing the fingerprint of the text-based web browser w3m
====
TL;DR: You can reduce the amount of information w3m gives about itself and the environment it is running in (and, by extension, you). **It will not make you anonymous; your fingerprint will still be unique.** But it may improve your privacy.
[w3m](http://w3m.sourceforge.net/) 'is a text-based web browser as well as a pager like `more` or `less`. With w3m you can browse web pages through a terminal emulator window (xterm, rxvt or something like that). Moreover, w3m can be used as a text formatting tool which typesets HTML into plain text.'
You can reduce the [browser fingerprint](https://panopticlick.eff.org/about#browser-fingerprinting) by applying the following changes to `~/.w3m/config` in any AppVM you want to use w3m in. (If you have not run w3m yet, you might need to copy the config file from elsewhere.) You can also apply the same changes to `/etc/w3m/config` in the relevant TemplateVM(s) to have them apply to multiple AppVMs; but make sure they are not reversed by the contents of `~/.w3m/config` in any of the AppVMs. (w3m reads `~/.w3m/config` after `/etc/w3m/config`).
* Set `user_agent` to `user_agent Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0`.
By default w3m identifies itself as `w3m/` + version number. The user agent `Mozilla/5.0 (Windows NT 6.1; rv:45.0) Gecko/20100101 Firefox/45.0` is the most common and the one used by the Tor Browser Bundle (TBB). One in fourteen browsers fingerprinted by Panopticlick has this value.
* Make w3m use the same HTTP_ACCEPT headers the TBB by adding the following lines at the end of the file:
accept_language en-US,en;q=0.5
accept_encoding gzip, deflate
accept_media text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
These changes will hide your computer's locale and some other information that may or may not be unique to the VM in which it is running. With the modifications above w3m will have the same headers as about one in fifteen browsers fingerprinted by Panopticlick.
Testing these settings on <https://browserprint.info> returns a fingerprint that is distinguishable from that of the TBB (with JavaScript disabled) only by 'Screen Size (CSS)' and 'Browser supports HSTS?'.\* (<https://panopticlick.eff.org> does not work with w3m.) Due to the low number of w3m users it is highly likely that you will have an unique browser fingerprint among the visitors of a website using somewhat sophisticated browser fingerprinting technology. But at least your browser fingerprint will not reveal your computer's locale settings or other specifics about it in the HTTP_ACCEPT headers. And while it may be inferred from your fingerprint that you use w3m, it is not be explicitly stated in the User-Agent header.
**Reminder: Do not rely on these settings for anonymity. Using w3m is all but guaranteed to make you stand out in the crowd.**
PS: You still need to delete cookies manually (`~/.w3m/cookie`) if you are not running w3m in a DispVM anyway. If you set w3m to not accept cookies, its fingerprint will change. (You can configure w3m to not use store cookies or accept new ones (or both), but the setting `use_cookie` seems to really mean `accept_cookie` and vice-versa, so maybe it is best to delete them manually for now.)
* * *
\* Does someone know how to fix this?

197
configuration-guides/zfs.md Normal file
View File

@ -0,0 +1,197 @@
---
layout: doc
title: ZFS
permalink: /doc/zfs/
redirect_from:
- /en/doc/zfs/
- /doc/ZFS/
- /wiki/ZFS/
---
ZFS in Qubes
============
**Use at your own risk**!
Beware: Dragons might eat your precious data!
Install ZFS in Dom0
===================
Install DKMS style packages for Fedora <sup>(defunct in 0.6.2 due to spl/issues/284)</sup>
----------------------------------------------------------------------------------------------------
Fetch and install repository for DKMS style packages for your Dom0 Fedora version [http://zfsonlinux.org/fedora.html](http://zfsonlinux.org/fedora.html):
~~~
disp1# wget http://archive.zfsonlinux.org/fedora/zfs-release-1-1$(rpm -E %dist).noarch.rpm
dom0# qvm-run --pass-io disp1 'cat /home/user/zfs-release-1-1.fc18.noarch.rpm' > /home/user/zfs-release-1-1.fc18.noarch.rpm
dom0# sudo yum localinstall /home/user/zfs-release-1-1.fc18.noarch.rpm
dom0# sudo sed -i 's/$releasever/18/g' /etc/yum.repo.d/zfs.repo
dom0# sudo qubes-dom0-update @development-tools
dom0# sudo qubes-dom0-update zfs
~~~
Install DKMS style packages from git-repository
-----------------------------------------------
Build and install your DKMS or KMOD packages as described in [http://zfsonlinux.org/generic-rpm.html](http://zfsonlinux.org/generic-rpm.html).
### Prerequisites steps in AppVM <sup>(i.e. disp1)</sup>
Checkout repositories for SPL and ZFS:
~~~
mkdir ~/repositories && cd ~/repositories
git clone https://github.com/zfsonlinux/spl.git
git clone https://github.com/zfsonlinux/zfs.git
~~~
Revert changes in SPL repository due to this bug: [https://github.com/zfsonlinux/spl/issues/284](https://github.com/zfsonlinux/spl/issues/284)
~~~
cd ~/repositories/spl
git config --global user.email "user@example.com"
git config --global user.name "user"
git revert e3c4d44886a8564e84aa697477b0e37211d634cd
~~~
### Installation steps in Dom0
Copy repositories over to Dom0:
~~~
mkdir ~/repositories
qvm-run --pass-io disp1 'tar -cf - -C ~/repositories/ {spl,zfs}' | tar -xpf - -C ~/repositories/
~~~
Installing build requirements for SPL and ZFS DKMS modules:
~~~
sudo qubes-dom0-update dkms kernel-devel zlib-devel libuuid-devel libblkid-devel lsscsi bc autoconf automake binutils bison flex gcc gcc-c++ gdb gettext libtool make pkgconfig redhat-rpm-config rpm-build strace
~~~
Configure and build SPL DKMS packages:
~~~
cd ~/repositories/spl
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
~~~
Configure and build ZFS DKMS packages:
~~~
cd ~/repositories/zfs
./autogen.sh
./configure --with-config=user
make rpm-utils rpm-dkms
~~~
Install SPL and ZFS packages (i.e. version 0.6.2):
~~~
sudo yum localinstall \
~/repositories/spl/spl-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/spl/spl-dkms-0.6.2-1.qbs2.noarch.rpm \
~/repositories/zfs/zfs-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/zfs/zfs-dkms-0.6.2-1.qbs2.noarch.rpm \
~/repositories/zfs/zfs-dracut-0.6.2-1.qbs2.x86_64.rpm \
~/repositories/zfs/zfs-test-0.6.2-1.qbs2.x86_64.rpm
~~~
Configure ZFS
=============
Automatically load modules
--------------------------
/etc/sysconfig/modules/zfs.modules
~~~
#!/bin/sh
for module in spl zfs; do
modprobe ${module} >/dev/null 2>&1
done
~~~
Make this file executable.
Tuning
------
Tame the memory-eating dragon (i.e. 512 Mb zfs\_arc\_max):
/etc/modprobe.d/zfs.conf
~~~
options zfs zfs_arc_max=536870912
~~~
Setup a zpool with ZFS datasets
-------------------------------
You can create a ZFS dataset for each AppVM, ServiceVM, HVM or TemplateVM or just use a pool as your backup location.
Move your existing directory to a temporary location, or the ZFS mount will overlay your directory.
Beware: VMs on a ZFS dataset aren't working, if your ZFS installation deserts you.
So keep netvm, firewallvm and your templates on your root file-system (preferably on a SSD).
~~~
zpool create -m none -o ashift=12 -O atime=off -O compression=lz4 qubes mirror /dev/mapper/<cryptname1> /dev/mapper/<cryptname2>
zfs create -p qubes/appvms
zfs create -m /var/lib/qubes/backup-zfs qubes/backup
zfs create -m /var/lib/qubes/appvms/banking qubes/appvms/banking
zfs create -m /var/lib/qubes/appvms/personal qubes/appvms/personal
zfs create -m /var/lib/qubes/appvms/untrusted qubes/appvms/untrusted
zfs create -m /var/lib/qubes/appvms/work qubes/appvms/work
~~~
Have fun with zpool and zfs.
Tips and Hints
==============
Backup your data
----------------
You're depending on an huge amount of code for this file system, keep this in mind and backup your precious data.
Encrypt underlying devices
--------------------------
~~~
dom0# cryptsetup -c aes-xts-plain64 luksFormat <device1>
dom0# cryptsetup luksOpen <device1> <cryptname1>
~~~
With the use of cryptsetup a keyfile can be specified to decrypt devices.
~~~
dom0# head -c 256 /dev/random > /root/keyfile1
dom0# chmod 0400 /root/keyfile1
dom0# cryptsetup luksAddKey <device1> /root/keyfile1
~~~
Decrypt devices on boot
-----------------------
Add your devices to /etc/crypttab.
~~~
<cryptname1> <device1> <keyfile1>
<cryptname2> <device2> none
~~~
Specifying a keyfile is especially useful, if ZFS should be ready during boot.
Further Reading
---------------
- [http://www.open-zfs.org](http://www.open-zfs.org)
- [http://zfsonlinux.org](http://zfsonlinux.org)

187
customization-guides/awesome.md Normal file
View File

@ -0,0 +1,187 @@
---
layout: doc
title: awesome
permalink: /doc/awesome/
redirect_from:
- /en/doc/awesome/
- /doc/awesome/
---
# Using awesome in dom0
## Qubes-specific features
* support for the Qubes OS window colors
* rudimentary support for the Qubes application menu entries following the freedesktop standard
* support for custom filters and menu entries
## Installation
awesome can be installed with the standard dom0 installation mechanisms.
$ sudo qubes-dom0-update awesome
That's it. After logging out, you can select awesome in the login manager.
## Development
To [contribute code](/doc/contributing/) you may clone the awesome repository as follows:
$ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome
For build instructions please check the repository _README_.
The repository attempts to follow the upstream Fedora repository.
## Common customizations
This section focuses on Qubes-specific customizations. For generic awesome customizations you might want to have a look at the [awesome website](https://awesomewm.org).
Customizations for awesome are usually done at `~/.config/awesome/rc.lua`. The default file can be found at `/etc/xdg/awesome/rc.lua`.
### Application menu
Starting from Qubes 4.0 application menu entries specific to awesome can be put into `~/.config/awesome/xdg-menu/` following the freedesktop standard. The folder might have to be created.
### Focus steal hardening
The default Qubes OS awesome installation comes with the defaults set by the awesome developers for focus changes. Some users may want more tight control over window focus changes - especially since focus changes can have security implications when sensitive data is provided to an incorrect application or even qube.
#### Definition
For the below example we'll define _wanted focus changes_ as one of the below:
* mouse move & click afterwards
* workspace/tag change
* pre-defined key combinations for focus changes (e.g. Mod-j & Mod-k)
* tag assignments and unassignments
Everything else is considered an unwanted _focus steal_.
In particular the following events are not meant to cause a focus change:
* new window created
* a window was closed
* application request
* mouse move without click (sloppy focus)
For the below example other requests from applications to the window manager are meant to be ignored in general as well, e.g.:
* windows shouldn't be able to maximize themselves without the user giving a respective command to the WM (simple test: Firefox F11 next to another window)
* windows shouldn't be able to change their size themselves
* windows shouldn't be able to modify their borders in any way
Users may want to adjust their definitions and respective implementations according to their needs.
#### Implementation
The implementation may be specific to the awesome version you're running. This guide refers to awesome version 3.5.9 which is available to Qubes 4.0 users.
Please keep in mind that this guide may not be conclusive. Your mileage may vary.
##### Change the autofocus implementation
The line `require("awful.autofocus")` in your _rc.lua_ implements various focus-related features for your awesome instance.
In order to customise these, you can copy the file `/usr/share/awesome/lib/awful/autofocus.lua` to e.g. `~/.config/awesome/autofocus_custom.lua` and replace the line above with `require("autofocus_custom")`.
Then you can customise the focus behavior. According to our above definitions it would look as follows:
```lua
---autofocus_custom.lua
local client = client
local screen = screen
local aclient = require("awful.client")
local atag = require("awful.tag")
--- When loaded, this module makes sure that there's always a client that will have focus
-- on events such as tag switching, client unmanaging, etc.
-- awful.autofocus
-- Give focus when clients appear/disappear and no one else has focus.
-- @param obj An object that should have a .screen property.
function check_focus(obj)
-- When no visible client has the focus...
if not client.focus or not client.focus:isvisible() then
local c = aclient.focus.history.get(obj.screen, 0)
if c then client.focus = c end
end
end
-- Give focus on tag selection change.
-- @param tag A tag object
function check_focus_tag(t)
local s = atag.getscreen(t)
if not s then return end
check_focus({ screen = s })
if client.focus and client.focus.screen ~= s then
local c = aclient.focus.history.get(s, 0)
if c then client.focus = c end
end
end
--made above functions global & removed some focus switches below (user interaction required instead)
--clear any focus
function clear_focus()
--unfortunately this doesn't work at the moment
--cf. https://github.com/awesomeWM/awesome/issues/164
--(Qubes uses an older awesome version that doesn't have the fix yet)
--client.focus = nil
end
atag.attached_connect_signal(nil, "property::selected", check_focus_tag)
client.connect_signal("unmanage", clear_focus)
client.connect_signal("tagged", check_focus)
client.connect_signal("untagged", check_focus)
client.connect_signal("property::hidden", clear_focus)
client.connect_signal("property::minimized", clear_focus)
```
##### Remove unwanted focus changing key bindings
The mouse bindings
```lua
awful.button({ }, 4, awful.tag.viewnext),
awful.button({ }, 5, awful.tag.viewprev)
```
in the default _rc.lua_ may cause tag and thus focus changes without keyboard interaction and tend to happen accidentally. This doesn't suit our definition from above and should therefore be removed or commented out.
##### Adjust client rules
The default client rule allows certain focus changes via `focus = awful.client.focus.filter`. These changes can be prevented entirely by setting `focus = false`.
Alternatively users may provide their own focus filter functions.
##### Disable sloppy focus
In your _rc.lua_ you'll find a section such as
```lua
-- Enable sloppy focus
c:connect_signal("mouse::enter", function(c)
if awful.layout.get(c.screen) ~= awful.layout.suit.magnifier
and awful.client.focus.filter(c) then
client.focus = c
end
end)
```
These enable _sloppy focus_ aka focus changes on mouse movements (without clicking) and should be removed or commented out to disable that behaviour.
##### Ignore requests from applications to the window manager
Handling of such requests is currently mostly implemented by awesome in the file `/usr/share/awesome/lib/awful/ewmh.lua`. You can either comment out the respective `client.connect_singal()` lines in that file (it will change back after each awesome update though) or disconnect the signals in your _rc.lua_.
As of awesome 3.5.9 this however is apparently only possible for signals connected to global functions, i.e. currently only the below signals can be disconnected in the _rc.lua_:
```lua
local ewmh = require("awful.ewmh")
client.disconnect_signal("request::activate", ewmh.activate)
client.disconnect_signal("request::tag", ewmh.tag)
```
The signal names may change across awesome versions.

187
customization-guides/dark-theme.md Normal file
View File

@ -0,0 +1,187 @@
---
layout: doc
title: Dark Theme in Dom0 and DomU
permalink: /doc/dark-theme/
---
Dark Theme in Dom0
==================
Dark KDE in Dom0
----------------
The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste.
The image below shows the default light theme after installation.
![begin light theme](/attachment/wiki/Dark-Theme/kde-fresh-installed-standard.png)
This is the result after applying the steps described here.
![end result dark theme](/attachment/wiki/Dark-Theme/kde-end-result.png)
1. Change `Workspace Appearance`
1. Open the `Workspace Appearance` window
Qubes Menu -> System Tools -> System Settings -> Workspace Appearance
![Workspace Appearance](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-style.png)
2. Go to `Desktop Theme`
![Desktop Menu](/attachment/wiki/Dark-Theme/kde-appearance-settings-desktop-theme-oxygen.png)
3. Select `Oxygen` and `Apply` the change
2. (Optional) Remove blue glowing task items
![blue glowing task bar items](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-border.png)
1. Adjust Oxygen `Details`
Qubes Menu -> System Tools -> System Settings -> Workspace Appearance -> Desktop Theme -> Details (Tab)
2. Select `Oxygen`
3. Change `Theme Item -> Task Items` from `Oxygen Task Items` to `Air Task Items`
![Change Task items look](/attachment/wiki/Dark-Theme/kde-desktop-theme-details.png)
4. Apply changes
![task bar items blue glowing removed](/attachment/wiki/Dark-Theme/kde-taskbar-blue-glowing-removed.png)
3. Change `Application Appearance`
1. Open the `Application Appearance` window
Qubes Menu -> System Tools -> System Settings -> Application Appearance
2. Go to `Colors`
![colors tab](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors.png)
3. Select `Obsidian Coast`
![set to Obsidian Coast](/attachment/wiki/Dark-Theme/kde-app-appearance-menu-colors-set.png)
4. Apply Changes
Qubes VM Manager should now look like the image below.
![result black Qubes Manager](/attachment/wiki/Dark-Theme/kde-black-qubes-manager.png)
**Note:** Changing the `Window Decorations` from `Plastik for Qubes` will remove the border color and the VM name. The problem with `Plastik for Qubes` is, that it does not overwrite the background and text color for Minimize, Maximize and Close buttons. The three button are therefore hard to read.
Dark XCFE in Dom0
-----------------
The following text describes how to change the default light theme to a dark theme. This is just an example, feel free to adjust the appearance to your taste.
The image below shows the default light theme after installation.
![begin light theme](/attachment/wiki/Dark-Theme/xfce-fresh-installed.png)
This is the result after applying the steps described here.
![end result dark theme](/attachment/wiki/Dark-Theme/xfce-end-result.png)
1. Change Appearance
1. Open the `Appearance` dialog
Qubes Menu -> System Tools -> Appearance
![appearance dialog](/attachment/wiki/Dark-Theme/xfce-appearance-dialog.png)
2. Change Style to `Albatross`
**Note:** The black appearance theme `Xfce-dusk` makes the VM names in the `Qubes OS Manager` unreadable.
2. *(Optional)* Change Window Manager Style
1. Open the `Window Manager` dialog
Qubes Menu -> System Tools -> Appearance
![window manager dialog](/attachment/wiki/Dark-Theme/xfce-window-manager-theme.png)
2. Change the Theme in the `Style` Tab (e. g. Defcon-IV). All available themes work.
Dark App VM, Template VM, Standalone VM, HVM (Linux Gnome)
==========================================================
Almost all Qubes VMs use default applications based on the GTK toolkit. Therefore the description below is focused on tools from the Gnome Desktop Environment.
Using "Gnome-Tweak-Tool"
------------------------
The advantage of creating a dark themed Template VM is, that each AppVM which is derived from the Template VM will be dark themed by default.
**Note:** Gnome-Tweak-Tool crashes under Archlinux. A workaround is to assign the AppVM to another TemplateVM (Debian, Fedora) which has Gnome-Tweak-Tool installed. Start the AppVM and configure the settings. Shutdown the machine and switch the template VM back to Archlinux.
1. Start VM
**Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM.
2. Install `Gnome-Tweak-Tool`
- Fedora
sudo dnf install gnome-tweak-tool
- Debian
sudo apt-get install gnome-tweak-tool
3. *(Only AppVM)* Stop template and start AppVM
4. Add `Gnome-Tweak-Tool` to the Application Menu
1. `Right-click` on VM entry in `Qubes VM Manager` select `Add/remove app shortcuts`
2. Select `Tweak Tool` and press the `>` button to add it
![Application Dialog](/attachment/wiki/Dark-Theme/dialog-add-gnome-tweak-tool.png)
5. Enable `Global Dark Theme`
1. *Debian only*
cd ~/.config/
mkdir gtk-3.0
cd gtk-3.0/
touch settings.ini
2. Start `Tweak Tool` from the VM application menu and set the `Global Dark Theme` switch to `on`
![Global Dark Theme enabled](/attachment/wiki/Dark-Theme/gnome-tweak-tool.png)
6. *(Optional)* Modify Firefox
**Note:** Firefox uses GTK style settings by default. This can create side effects such as unusable forms or search fields. One way to avoid this is to add the following line to `/rw/config/rc.local`:
sed -i.bak "s/Exec=firefox %u/Exec=bash -c 'GTK_THEME=Adwaita:light firefox %u'/g" /usr/share/applications/firefox.desktop
7. Restart VM or all application
Manually
--------
Manually works for Debian, Fedora and Archlinux.
1. Start VM
**Note:** Remember that if you want to make the change persistent, the change needs to be made in the TemplateVM, not the AppVM.
2. Enable `Global Dark Theme`
cd ~/.config/
mkdir gtk-3.0
cd gtk-3.0/
touch settings.ini
add the following lines to `settings.ini`
[Settings]
gtk-application-prefer-dark-theme=1
3. follow step 6 and 7 in: Using `Gnome-Tweak-Tool`

294
customization-guides/fedora-minimal-template-customization.md Normal file
View File

@ -0,0 +1,294 @@
---
layout: doc
title: Fedora Minimal Template Customization
permalink: /doc/fedora-minimal-template-customization/
redirect_from: /en/doc/fedora-minimal-template-customization/
---
FEDORA Packages Recommendations
======================
(starting from a minimal template)
Template installation
------------------------------
> [dom0]#qubes-dom0-update qubes-template-fedora-26-minimal
*Note*: If you have doubts about a set of tools or package you want to install, start installing and testing it in an AppVM.
You can then reproduce it later in your TemplateVM if you are satisfied.
That is the template philosophy in QubesOS.
For more information on the uses of a minimal template read [this page][Minimal].
Standard tools installation
================
Administration (documented)
---------------------------------------------
> sudo pciutils vim-minimal less tcpdump telnet psmisc nmap nmap-ncat usbutils
*Notes*: nmap can be used to discover hosts on a network (nmap -sP [network]), especially if you are inside a Microsoft network, because your AppVM will be protected/NATted behind the Qubes firewall.
(Microsoft / home networks make heavy use of autodiscovery technologies which require clients to be in the same local network (no firewall/no NAT), eg: your printer.)
Some recommendations here: check your current network using the Network manager applet (eg: 192.168.1.65).
Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipment:
nmap -sP 192.168.1.-.
Don't forget to temporarily allow traffic via the Qubes Firewall if you are doing this in a TemplateVM.
Administration (undocumented)
-------------------------------------------------
> openssh keepassx openssl gnome-keyring man
Dependency note: keepassx rely on qt which takes ~30MB
Network VM (documented)
----------------------------------------
> NetworkManager NetworkManager-wifi network-manager-applet wireless-tools dbus-x11 tar tinyproxy iptables
Network VM (undocumented)
--------------------------------------------
> which dconf dconf-editor
*Notes*: which is required for autostart scripts
*Notes*: dconf is required to remember the VM settings that are changed (the gsetting backend will be in memory only if gconf is not installed).
Network VM (manual operations - documented)
------------------------------------------------------------------------
Search for wireless firmware matching your wireless card (to be launched in network VM)
> lspci; dnf search firmware
ProxyVM/NetworkVM for 3G Modems
--------------------------------------------
> ModemManager NetworkManager-wwan usb_modeswitch modem-manager-gui
Dependency note: modem-manager-gui relies on webkit-gtk and is optional (NetworkManager can handle the modem alone)
Source: [3GMODEM]
ProxyVM for VPNs
--------------------------------------------
Search for a VPN package for your particular vpn solution then [configure][VPNNM] NetworkManager
> dnf search NetworkManager [openvpn\|openconnect\|openswat\|...]
OR
Refer to [this guide][VPN] which includes instructions for failsafe anti-leak VPN configuration using CLI scripts. (An early discussion about OpenVPN configuration can be viewed [here][OPENVPNSETUP].) Required packages will be `iptables` in addition to VPN software such as `openvpn`.
Printer Setup
--------------------------------------------
> system-config-printer system-config-printer-applet cups
Dependency Note: depends on python3 + python3 additional libraries which takes more than 40 M once installed.
Dependency Note: cups depends on ghostscript and require installing additional printing fonts (not documented here), so it can takes several dozen of MB
Manual operations
---------------------------
- Don't forget to restart your TemplateVM or only the cups service when you installed cups (systemctl start cups)
- First you need to search for your printer. If you don't know its name or IP, search for it using nmap: check your current network using the Network manager applet (eg: 192.168.1.65). Then run nmap in your current AppVM/TemplateVM to search for the selected printer/equipement: nmap -sP 192.168.1.-. Don't forget to temporarily allow traffic via the Qubes Firewall if you are inside a TemplateVM.
- Once you identified your printer, run system-config-printer GUI to install your printer
- You may need to cancel the operation to install more adapted printer drivers (eg: if the driver cannot be found automatically). Use dnf search printername to find potential drivers (eg dnf search photosmart)
GUI recommendations
======================
Lightweight packages recommendations
---------------------------------------------------------------
> lxterminal dejavu-sans-mono-fonts dejavu-sans-fonts gnome-settings-daemon
*Note*: You need to install sans-mono fonts for the terminal or it will be unreadable (overlapping characters....), while the sans fonts are just to get nicer GUI menus.
*Scite* is a nice notepad that can also highlight scripts with very light dependencies
> scite
*Meld* allows easy comparison of two text files/ two configuration files.
> meld
*Thunar* is a light file manager usually used by xfce
> thunar thunar-volman ntfs-3g
Dependency Note: xfce4 dependencies (but still quite light ~1.4M downloads)
Miscellaneous packages
--------------------------
*pycairo* package is needed for file's contextual menu "Send to VM" to function (to actually popup dialog box and enter VM's name where the file will be sent to).
*pinentry-gtk* package is responsible for pop-up dialog window where you enter password for your password protected gpg key.
Install this package in the qube holding your password protected gpg keys.
If you do not use password protected gpg keys, there is no need to install this package.
GUI themes
-----------------
Managing GUI theme / appearance is often complex because when you do not want to depend on a specific desktop system.
For this reason, we need to customize themes for each GUI framework that our application depends on.
This often includes GTK2, GTK3 (which us a different configuration/themes than GTK2), Qt.
The appearance of Windows can only be changed in dom0, however, the appearance of all buttons, menus, icons, widgets are specific to each AppVM.
### Packages
Choose theme packages for each framework. I recommend the following documentation [THEMEPACKAGES]
> clearlooks-phenix-gtk2-theme clearlooks-phenix-gtk3-theme
You can search for other themes using `dnf search theme gtk`.
You can check your currently installed theme packages (to eventually remove them) using `rpm -qa | grep theme`.
### Tweaking theme and appearance
First you can get an insight of installed Gtk theme and see how it will appear using lxappearance.
I recommend not applying settings using lxappearance (do not click on apply) because it will create multiple configuration files.
To remove these files, follow cleanup notes.
#### Cleanup notes
~~~
rm ~/.gtkrc-2.0
rm ~/.icons/default/index.theme
rm ~/.config/gtk-3.0/settings.ini
rm ~/.config/Trolltech.conf
~~~
Cleaning the whole dconf settings is also possible by removing the following file. Please note that it will remove all preferences set for gnome application (not only the themes)
~~~
rm ~/.config/dconf/user
~~~
*Note*: lxappearance only has an effect on gtk3 themes so it won't work to change gtk2 themes (used by Firefox, Thunderbird ...).
However, it is very lightweight and can be used to identify the name and look of themes you are interested in.
Once you have the name, you can apply it using gsetting command line or gconf-editor.
*Note*: if you really want a GUI theme editor, you can install gnome-tweak-tools, but this tool has a lot
of gnome dependencies (~150MB of dependencies). You can install it and uninstall it as soon as you change your theme.
#### Testing notes
The following programs can be used to see if theme has been correctly applied:
* GTK2 program: scite, thunderbird, firefox
* GTK3 program: lxterminal
* Qt program: keepassx
*Note*: testing in a TemplateVM will not work as expected because gnome-settings-daemon is not started in TemplateVM.
so test your themes in an AppVM and then update the TemplateVM accordingly.
### Forcing theme change for all AppVM depending on a TemplateVM
This can be done for gtk themes by creating dconf global settings. I recommend reading these articles:
[DCONF1]
[DCONF2]
#### Creating global file
* Setup global config file:
> mkdir /etc/dconf/db/qubes.d
Edit/Create the following file: /etc/dconf/db/qubes.d/10-global-theme-settings:
~~~
[org/gnome/desktop/interface]
cursor-theme="Adwaita"
gtk-theme="Clearlooks-Phenix"
icon-theme="Adwaita"
font-name="Cantarell 11"
monospace-font-name="Monospace 11"
~~~
* Generate global config database
> dconf update
* Configure default user profile
Edit/Create the following file: /etc/dconf/profile/user:
~~~
user-db:user
system-db:qubes
~~~
#### Locking configuration
It should be noted that the user dconf settings stored in ~/.config/dconf/user always takes precedence over the global dconf settings.
User dconf settings can be browsed using dconf-editor GUI.
If you want to force specific settings to be applied for all user (so in our case for all AppVMs depending on the template), you need to create locks:
> mkdir /etc/dconf/db/qubes.d/locks
Edit/Create the following file: /etc/dconf/db/qubes.d/locks/theme.lock:
~~~
/org/gnome/desktop/interface/gtk-theme
~~~
Finally, regenerate the dconf database
> dconf update
### Uniform look for Qt & GTK
Getting an uniform look for Qt & GTK is not achieved yet. A good source is on the following link [UNIFORMTHEME]
Two case:
1. You installed packages of the theme you selected both for Qt, GTK2 and GTK3.
(eg: Adwaita which is the default theme. I have not found another cross framework theme on fedora default packages).
2. You want to use the GTK theme you selected for Qt but there is no qt package.
In this case QGtkStyle will take precedence and convert the style automatically.
You can verify if it is enabled by searching for "style=GTK+" in /etc/xdg/Trolltech.conf.
If style is changed to another name, it will be used instead of your GTK theme.
*Note*: check that ~/.config/Trolltech.conf in your AppVMs is not defining another "style=" because it will take precedence over your global Qt theme.
[3GMODEM]: https://www.codeenigma.com/community/blog/installing-3g-usb-modems-linux
[OPENVPNSETUP]: https://groups.google.com/forum/#!searchin/qubes-users/openvpn$20setup/qubes-users/UbY4-apKScE/lhB_ouTnAwAJ
[THEMEPACKAGES]: https://groups.google.com/forum/#!search/appvm$20theme/qubes-users/RyVeDiEZ6D0/YR4ITjgdYX0J
[DCONF1]: http://www.mattfischer.com/blog/?p=431
[DCONF2]: https://wiki.gnome.org/Projects/dconf/SystemAdministrators
[UNIFORMTHEME]: https://wiki.archlinux.org/index.php/Uniform_look_for_Qt_and_GTK_applications
[Minimal]: ../templates/fedora-minimal/
[VPNNM]: ../vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-networkmanager
[VPN]: ../vpn/#set-up-a-proxyvm-as-a-vpn-gateway-using-iptables-and-cli-scripts

90
customization-guides/i3.md Normal file
View File

@ -0,0 +1,90 @@
---
layout: doc
title: i3
permalink: /doc/i3/
redirect_from:
- /en/doc/i3/
- /doc/i3/
- "/doc/UserDoc/i3/"
- "/wiki/UserDoc/i3/"
---
# i3 installation in dom0
i3 is part of the stable repository (as of Qubes R3.1) and can be installed by
using the [dom0 update mechanism](/doc/software-update-dom0/). To install the i3
window manager and the its Qubes specific configuration:
$ sudo qubes-dom0-update i3 i3-settings-qubes
The Qubes-specific configuration (package `i3-settings-qubes`) can be installed
optionally in case you would prefer writing your own configuration (see
[customization](#customization) section for scripts and configuration).
That's it. After logging out, you can select i3 in the login manager.
### Customization
* [xdg_autostart_script](https://gist.github.com/SietsevanderMolen/7b4cc32ce7b4884513b0a639540e454f)
* [i3bar_script](https://gist.github.com/SietsevanderMolen/e7f594f209dfaa3596907e427b657e30)
* [terminal_start_script](https://gist.github.com/SietsevanderMolen/7c6f2b5773dbc0c08e1509e49abd1e96)
* [i3 config with dmenu-i3-window-jumper](https://github.com/anadahz/qubes-i3-config/blob/master/config)
## Compilation and installation from source
Note that the compilation from source is done in a Fedora based domU (could
be dispvm). The end result is always an `.rpm` that is copied to dom0 and then
installed through the package manager.
### Getting the code
Clone the i3-qubes repository here:
$ git clone https://github.com/QubesOS/qubes-desktop-linux-i3
In this case, the most interesting file is probably
`i3/0001-Show-qubes-domain-in-non-optional-colored-borders.patch` It's the patch
with changes that are necessary to make i3 work nicely with Qubes OS. The code
should not need much explanation, it just gets the vmname and label from Qubes
OS and changes some defaults so the user can't override decisions.
If you want to make any changes to the package, this is the time and place to do
it.
### Building
You'll need to install the build dependencies, which are listed in
build-deps.list. You can verify them and then install them with:
$ sudo dnf install -y $(cat build-deps.list)
This used to be more complicated, but I finally redid this and use the same
buildsystem that's used by Qubes OS for XFCE. It's just a Makefile that helps
you get the sources and start off the build:
$ make rpms
### Installing
**Warning**: Manually installing software in dom0 is inherently risky, and the method described here circumvents the usual security mechanisms of qubes-dom0-update.
You should now have your i3 rpm in `./rpm/x86_64/i3-4.8-3.fc20.x86_64.rpm`.
Protip: copying this file to `~/i3.rpm` now will save you some typing in the
next step.
Now in dom0, copy in the rpm:
$ qvm-run --pass-io <src_domain> 'cat </path/to/rpm_in_src_domain>' > i3.rpm
Now that the rpm is in dom0 we can proceed with installing it. i3 has some
dependencies that we can easily install with:
$ sudo qubes-dom0-update perl-AnyEvent-I3 xorg-x11-apps \\
rxvt-unicode xcb-util-wm perl-JSON-XS xcb-util-cursor \\
dzen2 dmenu xorg-x11-fonts-misc libev
After that you can just install the generated rpm like any other local package:
$ sudo yum localinstall i3.rpm
Log out, select i3, then log in again.

88
customization-guides/kde.md Normal file
View File

@ -0,0 +1,88 @@
---
layout: doc
title: KDE
permalink: /doc/kde/
redirect_from: /en/doc/kde/
---
Using KDE in dom0
=================
Installation
------------
Prior to R3.2, KDE was the default desktop environment in Qubes. Beginning with
R3.2, however, [XFCE is the new default desktop environment](/doc/releases/3.2/release-notes/). Nonetheless, it is
still possible to install KDE by issuing this command in dom0:
$ sudo qubes-dom0-update @kde-desktop-qubes
You can also change your default login manager (lightdm) to the new KDE default: sddm
* first you need to edit the `/etc/sddm.conf` to make sure if the custom X parameter is set according to Qubes needs:
~~~
[XDisplay]
ServerArguments=-nolisten tcp -background none
~~~
* disable the lightdm service:
~~~
$ sudo systemctl disable lightdm
~~~
* enable the sddm service:
~~~
$ sudo systemctl enable sddm
~~~
* reboot
If you encounter performance issues with KDE, try switching back to LightDM.
Window Management
-----------------
You can set each window's position and size like this:
~~~
Right click title bar --> More actions --> Special window settings...
Window matching tab
Window class (application): Exact Match: <vm_name>
Window title: Substring Match: <partial or full program name>
Size & Position tab
[x] Position: Apply Initially: x,y
[x] Size: Apply Initially: x,y
~~~
You can also use `kstart` to control virtual desktop placement like this:
~~~
kstart --desktop 3 --windowclass <vm_name> -q --tray -a <vm_name> '<run_program_command>'
~~~
(Replace "3" with whichever virtual desktop you want the window to be
on.)
This can be useful for creating a simple shell script which will set up your
workspace the way you like.
Removal
------------
If you decide to remove KDE do **not** use `dnf remove @kde-desktop-qubes`. You will almost certainly break your system.
The safest way to remove (most of) KDE is:
~~~
sudo dnf remove kdelibs,plasma-workspace
~~~
Mailing List Threads
--------------------
* [Nalu's KDE customization thread](https://groups.google.com/d/topic/qubes-users/KhfzF19NG1s/discussion)

46
customization-guides/language-localization.md Normal file
View File

@ -0,0 +1,46 @@
---
layout: doc
title: Language Localization
permalink: /doc/language-localization/
redirect_from:
- /en/doc/language-localization/
- /doc/LanguageLocalization/
- /wiki/LanguageLocalization/
---
Language Localization
=====================
How to set up pinyin input in Qubes
-----------------------------------
The pinyin input method will be installed in a TemplateVM to make it available after restarts and across multiple AppVMs.
1. In a TemplateVM, install `ibus-pinyin` via the package manager or terminal.
If the template is Fedora-based, run `sudo dnf install ibus-pinyin`.
If the template is Debian-based, run `sudo apt install ibus-pinyin`
2. Shut down the TemplateVM.
3. Start or restart an AppVM based on the template in which you installed `ibus-pinyin` and open a terminal.
4. Run `ibus-setup`.
5. You will likely get an error message telling you to paste the following into your bashrc:
export GTK_IM_MODULE=ibus
export XMODIFIERS=@im=ibus
export QT_IM_MODULE=ibus
Copy the text into your `~/.bashrc` file with your favorite text editor.
You will need to do this for any AppVM in which you wish to use pinyin input.
6. Set up ibus input as you like using the graphical menu (add pinyin or intelligent pinyin to selections).
You can bring the menu back by issuing `ibus-setup` from a terminal.
7. Set up your shortcut for switching between inputs.
By default it is super-space.
If `ibus-pinyin` is not enabled when you restart one of these AppVMs, open a terminal and run `ibus-setup` to activate ibus again.
For further discussion, see [this qubes-users thread](https://groups.google.com/forum/#!searchin/qubes-users/languge/qubes-users/VcNPlhdgVQM/iF9PqSzayacJ).

93
customization-guides/removing-templatevm-packages.md Normal file
View File

@ -0,0 +1,93 @@
---
layout: doc
title: Removing TemplateVM Packages
permalink: /doc/removing-templatevm-packages/
---
# Removing TemplateVM Packages
When removing any packages from a default TemplateVM, be sure to check what's being removed by `apt autoremove` or `dnf`.
When removing certain packages, for instance Thunderbird, `apt` and `dnf` will attempt to remove many packages required by qubes for the template to function correctly under qubes.
As an example from a terminal in a TemplateVM:
```shell_session
$ sudo apt remove thunderbird
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following packages were automatically installed and are no longer required:
debugedit libjs-sphinxdoc libjs-underscore librpm3 librpmbuild3 librpmio3
librpmsign3 libsqlite0 linux-headers-4.9.0-6-amd64
linux-headers-4.9.0-6-common linux-image-4.9.0-6-amd64 python-backports-abc
python-cffi-backend python-concurrent.futures python-croniter
python-cryptography python-dateutil python-enum34 python-idna
python-iniparse python-ipaddress python-jinja2 python-libxml2 python-lzma
python-markupsafe python-msgpack python-openssl python-pyasn1 python-pycurl
python-requests python-rpm python-singledispatch python-six python-sqlite
python-sqlitecachec python-tornado python-tz python-urlgrabber
python-urllib3 python-xpyb python-yaml qubes-core-agent-dom0-updates
qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter
qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter
qubes-usb-proxy rpm rpm-common rpm2cpio salt-common salt-ssh usbutils yum
yum-utils
Use 'sudo apt autoremove' to remove them.
The following packages will be REMOVED:
icedove lightning qubes-thunderbird qubes-vm-recommended thunderbird
0 upgraded, 0 newly installed, 5 to remove and 0 not upgraded.
After this operation, 151 MB disk space will be freed.
Do you want to continue? [Y/n]
```
Note all of the qubes packages are tracked as dependencies that will no longer be required. `apt remove` will only remove the packages listed, which is ok.
If, however you also run `apt autoremove` the other qubes packages necessary for TemplateVMs will be removed.
If you'd still like to remove one of these applications without breaking your TemplateVM you have a couple different options.
## Removing Only Packages Not Needed for a Qubes TemplateVM
### Debian
1. In your TemplateVM terminal run:
```shell_session $ apt remove package-name```
Note the packages "no longer required"
2. If the list of "no longer required" packages includes anything beginning with `qubes-` or `salt-` make a note to yourself to **never** run `$ sudo apt autoremove` on this TemplateVM
**Recommended but optional:** Use `apt-mark` to make `apt autoremove` safe again.
```shell_session
$ sudo apt mark-manual package-name package-name
```
Replace package-names with actual `qubes-*` and `salt-*` packages you'd like to retain.
For example, still in your TemplateVM terminal:
```shell_session
$ sudo apt-mark manual qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh qubes-usb-proxy
```
`$ apt autoremove` should now be safe to use.
### Fedora
In your TemplateVM terminal, run:
```shell_session
$ dnf remove --noautoremove package-name
```
## Recovering A TemplateVM which you've already removed needed qubes-* packages
If you've already removed packages, run `apt autoremove` and restarted your VM you've lost passwordless sudo access.
You can login as root, open a terminal in dom0 and run:
```shell_session
$ qvm-run -u root vmname xterm
```
This will open an xterm terminal in the TemplateVM named `vmname`
Once you're logged in as root, reinstall these packages & their dependencies:
### Debian
```shell_session
$ sudo apt install qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh
```
### Fedora
Similar to Debian for example (package names may vary):
```shell_session
$ sudo dnf install qubes-core-agent-dom0-updates qubes-core-agent-passwordless-root qubes-gpg-split qubes-img-converter qubes-input-proxy-sender qubes-mgmt-salt-vm-connector qubes-pdf-converter salt-common salt-ssh
```

168
customization-guides/windows-template-customization.md Normal file
View File

@ -0,0 +1,168 @@
---
layout: doc
title: Windows Template Customization
permalink: /doc/windows-template-customization/
redirect_from: /en/doc/windows-template-customization/
---
Disable/Uninstall unnecessary features/services
=============================
Windows features
----------------------------
Uninstall windows features from Control Panel > Turn windows features On/Off.
Generally, it will be required to reboot after features are uninstalled.
If you do not manage to uninstall some features, it is sometimes necessary to uninstall them one by one or two by two.
Only keep:
* Print and Document Service => Internet Printing Client
* Print and Document Service => Windows Fax and Scan (apparently it cannot be uninstalled)
* Windows search
*Note*: Windows search is recommended because it is a nightmare to find something in menus if it is not enabled (it removes the search bar from the start menu, from the explorer, and from the control panel).
*Note*: Unselecting windows media, .Net and Internet Explorer will uninstall these components. On a new install they are generally old versions anyway and it will be quicker to install directly the new versions later.
Windows services
---------------------------
Disable the following services that are not required or have no sense in a VM context:
* Base Filtering Engine (only required if you want to use Microsoft IPSEC)
* DHCP Client
* Function Discovery Provider Host
this will not work anyway because SSDP discovery uses multicast - need to be on the same network which is not the case because of Qubes firewall
* Peer Name Resolution Protocol
* Peer Netwoking Grouping
* Peer Networking Identity Manager
* SSDP Discovery
* Security Center (is it only notifications ?)
* TCP/IP Netbios Help (is Netbios still really used by Windows ? Maybe for discovery only ?)
* Themes (if you don't care about theme)
* Volume Shadow Copy (see next note in the performance section)
* Windows defender
* Windows Firewall
*Notes*: IP Helper is required as it is used by Qubes Agent to configure the IP address.
Windows update
--------------------------
I recommend disabling windows update (Never Check for Update) because checking for updates will start every time you start an AppVM if you haven't started your template in a while.
Running windows update is also apparently IO hungry.
Of course I recommend starting the template regularly and checking manually for updates.
System properties
---------------------------
Right click on computer and go to Properties > Advanced > Performance:
* If you don't care about visual effect, in Visual Effect select "Adjust for best performance"
* I personally tweak the page file size to gain some space on my root.
In Advanced>Performances>Advanced tab, change Virtual memory:
1. unselect automatically manage paging file size for all drive
2. click on drive C:
3. select no paging file
4. click on set
5. click on drive d:
6. select customer size
7. use an initial size of 500 and a max size of 1000. If the page file is too small, you will notice a low memory pop up when working on windows. In this case, it often means that you should extend your AppVM RAM.
* System Protection
Here you can disable Shadow Folder because it has little sense in the case of Qubes because
* we do regular backups of AppVMs/TemplateVMs;
* we can revert at least one template change if we break something.
Select drives where system protection is enabled and click Configure. "Turn off system protection" "Delete all restore points"
* Remote
Unselect Allow Remote Assistance connections to this computer.
Task scheduler
-----------------------
Open the task scheduler and *disable* the following tasks.
If you remove these tasks they may be recreated automatically by various windows management tools (such as defragmentation)
* Autochk: All
* Application Experience: All
* Customer Experience Improvement Program: All
* Defrag: All
* DiskDiagnosis: All (the disk is virtual anyway so S.M.A.R.T. has no sense)
* Maintenance: All
* SystemRestore: All
* WindowsBackup: All
Power options
-------------
First, enable the "Power" Windows service. Then, set all of the following:
* Put the computer to sleep: `Never`
* Turn the display off: `Never`
* Turn off hard disk after: Setting (Minutes): `0`
Turn off hibernation. Open a command prompt (`cmd.exe`) as an administrator,
then execute:
powercfg -h off
The hibernation file (`C:\hyberfil.sys`) should now be deleted.
Manual tasks that can/should be started in the template
-------------------------------------------------------
* Disk defragmentation
* Windows Update
* Windows file cleaning
1. Run windows drive cleaner as Administrator.
2. Enable all the task and run the cleaner
* CCleaner file cleaning
1. Install CCleaner free
2. Copy the attached ccleaner configuration file in CCleaner program file folder
3. Run ccleaner with all option set except "wipe free space" (it will also remove user history and preferences)
4. Run ccleaner only with the option "wipe free space".
It will write zeros in all unused space. This will allow you to strip the root.img file later
* TemplateVM stripping
Ensure that you know what you are doing in this section as you may destroy by error your template root.img file.
* If you ran ccleaner with "wipe free space", follow the following procedure
1. from dom0, go to /var/lib/templates-vm/yourtemplate
2. copy root.img using the following command
> cp --sparse=always root.img root.img.clean
3. if the copy worked, you can move the new root file by running this command
> mv root.img.clean root.img
* If it doesn't manage to fill the free space with zeros, you can follow the following *unsafe* undocumented procedure
1. from dom0, go to /var/lib/templates-vm/yourtemplate
2. check the partitioning to identify the filesystem offset of root.img
3. mount the filesystem
4. create a file with zeros inside the filesystem until the mounted filesystem is full
5. remove the file
6. unmount the partition
7. make a copy of root.img in sparse mode.

434
managing-os/archlinux.md Normal file
View File

@ -0,0 +1,434 @@
---
layout: doc
title: Archlinux Template
permalink: /doc/templates/archlinux/
redirect_from:
- /doc/archlinux/
- /en/doc/templates/archlinux/
- /doc/Templates/Archlinux/
- /wiki/Templates/Archlinux/
---
# Archlinux Template
Archlinux template is one of the templates made by Qubes community. It should
be considered experimental as Qubes developers team use mainly Fedora-based VMs
to test new features/updates.
Main maintainer of this template is [Olivier Médoc](mailto:o_medoc@yahoo.fr).
Updates for this template are provided by [Olivier Médoc](mailto:o_medoc@yahoo.fr) and are signed by the following key:
pub 2048R/2043E7ACC1833B9C 2014-03-27 [expires: 2018-03-29]
Key fingerprint = D85E E12F 9678 51CC F433 515A 2043 E7AC C183 3B9C
uid Olivier MEDOC (Qubes-OS signing key) <o_medoc@yahoo.fr>
## Installation
A prebuilt template is available only for Qubes 3.2. Before Qubes 3.2, it should be compiled from source as described in [building-archlinux-template](/doc/building-archlinux-template/).
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-templates-community qubes-template-archlinux
## Binary packages activation
The Qubes update repository is disabled by default in the Archlinux template. You can however choose to trust it by registering it into pacman.
Since November 2017, an activation package is present in the template. The update repository can thus be activated by running the following command inside the template:
# pacman -sU /etc/pacman.d/qubes-vm-keyring*.pkg.tar.xz
It should be noted to this command will create a trust for packages provided by [Olivier Médoc](mailto:o_medoc@yahoo.fr) and signed by the PGP key above.
If the qubes-vm-keyring package is not present in `/etc/pacman.d/`, please refer to the section #Activating binary packages manually.
## Optional Qubes packages
Several Qubes packages are not necessarily installed by default in the Archlinux Template. These packages can be installed to add additional functionnalities to the template:
* `qubes-vm-networking`: Contains Qubes tools and dependencies required to use the template as a NetVM/ProxyVM
* `qubes-vm-pulseaudio`: Contains `Pulseaudio` agent enabling sound support in the template
## Default template packages
In order to keep the template as small and simple as possible, default installed package have been arbitrarily selected based on multiple subjective criterias that however essentially include libraries dependencies. This packages are:
* Some font packages to keep good user experience
* leafpad: a note pad
* xfce4-terminal: a terminal
* thunar: a file browser that supports mounting usb keys
* firefox: web browser
* thunderbird: a mail browser
* evince: a document viewer
Note that Archlinux does not install GUI packages by default as this decision is left to users. These packages have only been selected to have a usable template.
## Activating binary packages manually
Enable the repository by running the following command:
# rm /etc/pacman.d/99-qubes-repository-3.2.conf
# ln -s /etc/pacman.d/99-qubes-repository-3.2.disabled /etc/pacman.d/99-qubes-repository-3.2.conf
Then you need to install and sign the public GPG key of the package maintainer (note that accessing to GPG servers requires to temporarily disable the firewall in your template):
# pacman-key --recv-key 2043E7ACC1833B9C
# pacman-key --finger 2043E7ACC1833B9C
If the fingerprint is correct, you can then sign the key:
# pacman-key --lsign-key 2043E7ACC1833B9C
## Updating a Qubes-3.2 Archlinux Template
Because of changes in the Qubes-4.0 partition layout, and usage of XEN HVMs instead of pv-guests. It is not straightforward to update a Qubes-3.2 template to Qubes-4.0.
For this reason, it is recommended to start from a new template in Qubes-4.0.
## Updating a Qubes-3.1 Archlinux Template
If you decide to use binary packages but that you were using a Qubes-3.1 Template, you can follow these instructions to enable Qubes 3.2 agents.
You can use a template that you built for Qubes 3.1 in Qubes 3.2. The qrexec and gui agent functionalities should still be working so that you can at least open a terminal.
In order to enable binary packages for Qubes 3.2, add the following lines to the end of /etc/pacman.conf
```
[qubes-r3.2]
Server = http://olivier.medoc.free.fr/archlinux/current/
```
You should then follow the instruction related to pacman-key in order to sign the binary packages PGP key. With the key enabled, a pacman update will update qubes agents:
` # pacman -Suy `
The two lines that have just been added to /etc/pacman.conf should then be removed as they have been included in the qubes-vm-core update in the file `/etc/pacmand.d/99-qubes-repository-3.2.conf`
## Known Issues
### Package cannot be updated because of errors related to xorg-server or pulseaudio versions
The Qubes GUI agent must be rebuilt whenever xorg-server or pulseaudio make major changes.
If an update of one of these packages causes your template to break, simply [revert it](https://www.qubes-os.org/doc/software-update-vm/#reverting-changes-to-a-templatevm) and wait for corresponding Qubes package updates to be available (or attempt to build them yourself, if you're so inclined).
This should not happen frequently.
### qubes-vm is apparently starting properly (green dot) however graphical applications do not appear to work
They are multiple potential reasons. Some of them are described in the following issue:
* https://github.com/QubesOS/qubes-issues/issues/2612
In issue 2612, check that the option `noauto` is present for all lines in /etc/fstab related to /rw or /home. This bug can appear if you come from an old Archlinux Template (pre February 2017).
## Debugging a broken VM
In order to identify the issue, you should start by getting a console access to the VM:
* Either by running in dom0 `qvm-run --pass-io --nogui yourbrokenvm 'your command here'`
* Or by running in dom0 `sudo xl console yourbrokenvm`
Start by trying to run a GUI application such as xfce4-terminal in order to identify any error message.
Then you can check potential broken systemd service by running the following command inside the broken vm: `systemctl | grep fail`.
If you identified a broken service check `journalctl -la -u yourbrokenservice`. If not check `journalctl -b` for errors.
Finally, errors related to the GUI agent can be found inside the VM in `/home/user/.xsession-errors`
## Packages manager wrapper
Powerpill is a full Pacman wrapper that not only gives easy proxy configuration but further offers numerous other advantages.
Please check out:
[Archlinux Powerpill](https://wiki.archlinux.org/index.php/powerpill)
[XYNE's (dev) Powerpill](http://xyne.archlinux.ca/projects/powerpill/)
**Important Note:** As you are working in a template vm, by default, you will have to open network access to the template to download files manually, except for managed packages which should be handled by the Qubes proxy. You can use the "allow full access for" a given time period in the FW settings of the template in the VMM or open up the various services through the same window. Remember to change it back if you choose the later route. Actions needing network access will be noted with (needs network access)
<br>
<br>
##### **1: Editing Pacman's configuration file (pacman.conf)** #####
* Open archlinux terminal app
* edit /etc/pacman.conf
* **$ sudo nano -w /etc/pacman.conf**
* Below is the output of a correct pacman.conf file Make the changes so your file matches this one or rename the original and create a new one and copy and paste this text into it. Text should be justified left in the file. The changes from your default are to make gpg signing mandatory for packages but not required for DBs for the archlinux repos. Also to add the repo (at the end) for the Powerpill package.
<br>
<br>
# /etc/pacman.conf
#
# See the pacman.conf(5) manpage for option and repository directives
#
# GENERAL OPTIONS
#
[options]
# The following paths are commented out with their default values listed.
# If you wish to use different paths, uncomment and update the paths.
# RootDir = /
# DBPath = /var/lib/pacman/
# CacheDir = /var/cache/pacman/pkg/
# LogFile = /var/log/pacman.log
GPGDir = /etc/pacman.d/gnupg/
HoldPkg = pacman glibc
# XferCommand = /usr/bin/curl -C - -f %u > %o
# XferCommand = /usr/bin/wget --passive-ftp -c -O %o %u
# CleanMethod = KeepInstalled
# UseDelta = 0.7
Architecture = auto
# Pacman won't upgrade packages listed in IgnorePkg and members of IgnoreGroup
# IgnorePkg =
# IgnoreGroup =
# NoUpgrade =
NoUpgrade = /etc/X11/xinit/xinitrc.d/pulseaudio
NoUpgrade = /etc/X11/xinit/xinitrc.d/pulseaudio
NoUpgrade = /etc/X11/xinit/xinitrc.d/pulseaudio
# NoExtract =
# Misc options
# UseSyslog
# Color
# TotalDownload
CheckSpace
# VerbosePkgLists
# By default, pacman accepts packages signed by keys that its local keyring
# trusts (see pacman-key and its man page), as well as unsigned packages.
**Edited Line:** `# SigLevel = Required DatabaseOptional`
LocalFileSigLevel = Optional
# RemoteFileSigLevel = Required
# NOTE: You must run `pacman-key --init` before first using pacman; the local
# keyring can then be populated with the keys of all official Arch Linux
# packagers with `pacman-key --populate archlinux`.
#
# REPOSITORIES
# - can be defined here or included from another file
# - pacman will search repositories in the order defined here
# - local/custom mirrors can be added here or in separate files
# - repositories listed first will take precedence when packages
# have identical names, regardless of version number
# - URLs will have $repo replaced by the name of the current repo
# - URLs will have $arch replaced by the name of the architecture
#
# Repository entries are of the format:
# [repo-name]
# Server = ServerName
# Include = IncludePath
#
# The header [repo-name] is crucial - it must be present and
# uncommented to enable the repo.
#
# The testing repositories are disabled by default. To enable, uncomment the
# repo name header and Include lines. You can add preferred servers immediately
# after the header, and they will be used before the default mirrors.
# [testing]
# SigLevel = PackageRequired
# Include = /etc/pacman.d/mirrorlist
[core]
**Edited Line:** `SigLevel = PackageRequired`
Include = /etc/pacman.d/mirrorlist
[extra]
**Edited Line:** `SigLevel = PackageRequired`
Include = /etc/pacman.d/mirrorlist
# [community-testing]
# SigLevel = PackageRequired
# Include = /etc/pacman.d/mirrorlist
[community]
**Edited Line:** `SigLevel = PackageRequired`
Include = /etc/pacman.d/mirrorlist
# If you want to run 32 bit applications on your x86_64 system,
# enable the multilib repositories as required here.
# [multilib-testing]
# Include = /etc/pacman.d/mirrorlist
# [multilib]
# Include = /etc/pacman.d/mirrorlist
# An example of a custom package repository. See the pacman manpage for
# tips on creating your own repositories.
# [custom]
# SigLevel = Optional TrustAll
# Server = file:///home/custompkgs
[multilib]
**Edited Line:** `SigLevel = PackageRequired`
Include = /etc/pacman.d/mirrorlist
**Edited Line:** `# [qubes]`
**Edited Line:** `# Server = http://olivier.medoc.free.fr/archlinux/pkgs/`
**Add Section Below:**
[xyne-x86_64]
# A repo for Xyne's own projects: http://xyne.archlinux.ca/projects/
# Packages for the "x86_64" architecture.
# Added for PowerPill app
# Note that this includes all packages in [xyne-any].
SigLevel = Required
Server = http://xyne.archlinux.ca/repos/xyne
----------
<br>
##### **2: Setting Up GPG** (needs network access) #####
* Initialize GPG Keyring
* **$ sudo pacman-key --init**
* Populate the keyring with Archlinux master keys
* **$ sudo pacman-key --populate archlinux**
* Confirm keys with those at [Archlinux Master Keys](https://www.archlinux.org/master-keys/)
* For more information on Pacman key signing: [Pacman Package Key Signing](https://wiki.archlinux.org/index.php/Pacman/Package_signing)
<br>
<br>
##### **3: Install Powerpill (Pacman wrapper)** #####
* **$ sudo pacman -S powerpill**
<br>
<br>
##### **4: Install Reflector** #####
*Note: It scripts mirror updating. Grabbing the most up to date gen mirror list. It ranks them by most recently sync'd. Then ranks them on fastest speed. Also can be used by Powerpill config to allow a once stop conf file for all if so wanted.*
* **$ sudo pacman -S reflector**
Note: You can combine package downloads: **$ sudo pacman -S powerpill reflector**
<br>
<br>
##### **5: Backup mirrorlist prior to first running Reflector.** #####
Note: For info on Reflector and its configs: [Reflector](https://wiki.archlinux.org/index.php/Reflector)
* **$ sudo cp /etc/pacman.d/mirrorlist /etc/pacman.d/mirrorlist.bkup**
<br>
<br>
##### **6: Setup mirrolist with Reflector** (needs network access)** #####
*Note: Look at the Reflector page to decide what filter and argument string you wish to run. Below is a default string that will work for most all to setup a working basic mirrorlist.
*Look to Reflector pages or --help for more info on args and filters.*
* **$ sudo reflector --verbose -l 5 --sort rate --save /etc/pacman.d/mirrorlist**
* The above ranks all the most up to date and sorts for the 5 fastest
* You can confirm the new list by opening the newly created mirrorlist.
<br>
<br>
##### **7: Configure Powerpill configuration file to use Qubes Proxy Service** #####
* Qubes Proxy Address: **10.137.255.254:8082**
* Edit **powerpill.json** (powerpill config file)
* **$ sudo nano -w /etc/powerpill/powerpill.json**
* Add line '**--all-proxy=10.137.255.254:8082**' at the bottom of the list under the **"aria2"** section under the **"args"** line. Example below:
<br>
{
"aria2": {
"args": [
"--allow-overwrite=true",
"--always-resume=false",
"--auto-file-renaming=false",
"--check-integrity=true",
"--conditional-get=true",
"--continue=true",
"--file-allocation=none",
"--log-level=error",
"--max-concurrent-downloads=100",
"--max-connection-per-server=5",
"--min-split-size=5M",
"--remote-time=true",
"--show-console-readout=true",
"--all-proxy=10.137.255.254:8082"
],
"path": "/usr/bin/aria2c"
},
<br>
<br>
##### **8: Test Powerpill Configuration** #####
*Note: Powerpill uses and passes the same syntax as pacman*
* Configure Archlinux Template to only use the Qubes Proxy Update Service
* In the Qubes VM Manager under Archlinux FW tab make sure only the access check box for update proxy is on. All others should be set to deny.
* **$ sudo powerpill -Syu**
* You should get a similar output as below:
<br>
<br>
![arch-template-26](/attachment/wiki/ArchlinuxTemplate/arch-template-26.png)
<br>
<br>
**Remember you must open up network access anytime you wish to run the Reflector script to update the mirrorlist. This page will be updated when/if this situation changes.**
### **If the above checks out, you can start using your new Archlinux Template** ###
<br>
<br>
## Want to contribute?
* [How can I contribute to the Qubes Project?](/doc/contributing/)
* [Guidelines for Documentation Contributors](/doc/doc-guidelines/)
<br>

96
managing-os/linux-hvm-tips.md Normal file
View File

@ -0,0 +1,96 @@
---
layout: doc
title: Linux HVM Tips
permalink: /doc/linux-hvm-tips/
redirect_from:
- /en/doc/linux-hvm-tips/
- /doc/LinuxHVMTips/
- /wiki/LinuxHVMTips/
---
Tips for Linux in HVM domain
============================
How to fix bootup kernel error
-------------------------------
The HVM may pause on boot, showing a fixed cursor.
After a while a series of warnings may be shown similar to this:
BUG: soft lockup - CPU#0 stuck for 23s! [systemd-udevd:244]
To fix this:
1. Kill the HVM.
1. Start the HVM
1. Press "e" at the grub screen to edit the boot parameters
1. Find the /vmlinuz line, and edit it to replace "rhgb" with "modprobe.blacklist=bochs_drm"
1. Press "Ctrl-x" to start the HVM
If this solves the problem then you will want to make the change permanent:
1. Edit the file `/etc/default/grub`.
1. Find the line which starts:
~~~
GRUB_CMDLINE_LINUX=
~~~
1. Remove this text from that line:
~~~
rhgb
~~~
1. Add this text to that line:
~~~
modprobe.blacklist=bochs_drm
~~~
1. Run this command:
~~~
grub2-mkconfig --output=/boot/grub2/grub.cfg
~~~
The HVM should now start normally.
Screen resolution
-----------------
Some kernel/Xorg combinations use only 640x480 in HVM, which is quite small.
To enable maximum resolution, some changes in the Xorg configuration are needed:
1. Force "vesa" video driver
2. Provide wide horizontal synchronization range
To achieve it (all commands to be run as root):
1. Generate XOrg configuration (if you don't have it):
~~~
X -configure :1 && mv ~/xorg.conf.new /etc/X11/xorg.conf
~~~
1. Add HorizSync line to Monitor section, it should look something like:
~~~
Section "Monitor"
Identifier "Monitor0"
VendorName "Monitor Vendor"
ModelName "Monitor Model"
HorizSync 30.0 - 60.0
EndSection
~~~
1. Change driver to "vesa" in Device section:
~~~
Section "Device"
# (...)
Identifier "Card0"
Driver "vesa"
VendorName "Technical Corp."
BoardName "Unknown Board"
BusID "PCI:0:2:0"
EndSection
~~~
Now you should get resolution of at least 1280x1024 and should be able to choose other modes.
Qubes agents
------------
Linux Qubes agents are written primarily for PV qubes, but it is possible to run them also in a HVM qube.
However some work may be required to achieve this. Check [this thread](https://groups.google.com/group/qubes-devel/browse_thread/thread/081df4a43e49e7a5).

23
managing-os/netbsd.md Normal file
View File

@ -0,0 +1,23 @@
---
layout: doc
title: How to Create a NetBSD VM
permalink: /doc/netbsd/
---
How to Create a NetBSD VM
=========================
1. Create a StandaloneVM with the default template.
2. Replace `vmlinuz` with the `netbsd-INSTALL_XEN3_DOMU` kernel.
3. During setup, choose to install on the `xbd1` hard disk.
4. Attach the CD to the VM.
5. Configure the networking.
6. Optionally enable SSHD during the post-install configuration.
7. Replace the kernel with `netbsd-XEN3_DOMU`.
8. The VM may fail to boot automatically, in which case you must explicitly
specify `xbd1a` as the root device when prompted.
For further discussion, please see this [thread] and this [guide].
[thread]: https://groups.google.com/group/qubes-devel/msg/4015c8900a813985
[guide]: https://wiki.xen.org/wiki/How_to_install_a_NetBSD_PV_domU_on_a_Debian_Squeeze_host_%28Xen_4.0.1%29

30
managing-os/pentesting.md Normal file
View File

@ -0,0 +1,30 @@
---
layout: doc
title: Penetration Testing
permalink: /doc/pentesting/
---
**Legal notice:**
The usage of penetration testing tools outside your own laboratory environment requires the permission of the organization you attack. Penetration testing without permission can have legal consequences.
To avoid such legal conflicts please refer to the [EC-Council: Code of Ethics](https://www.eccouncil.org/Support/code-of-ethics).
Penetration Testing
===================
"A penetration test, colloquially known as a pen test, is an authorised simulated attack on a computer system that looks for security weaknesses, potentially gaining access to the system's features and data." (Source: [Wikipedia](https://en.wikipedia.org/wiki/Penetration_test)).
Penetration Testing Distributions
---------------------------------
The following instructions explain how to install a penetration testing distribution within Qubes OS.
- [BlackArch](/doc/pentesting/blackarch/)
- [Kali](/doc/pentesting/kali/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
Using Qubes OS to host a "hacking" laboratory
---------------------------------------------
Qubes OS is a hypervisor based operating system. Qubes OS can host various operating systems such as Linux, Unix or Windows and run them in parallel. Qubes OS can therefore be used to host your own "hacking" laboratory.

96
managing-os/pentesting/blackarch.md Normal file
View File

@ -0,0 +1,96 @@
---
layout: doc
title: How to Create a BlackArch VM
permalink: /doc/pentesting/blackarch/
redirect_from:
- /doc/blackarch/
---
**General reminder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool providers.
Please keep in mind that using such a VM or VMs based on the template for security and privacy critical tasks is not recommended.
How to Create a BlackArch VM
============================
[BlackArch](https://www.blackarch.org) Linux is an [Arch Linux](https://www.archlinux.org)-based distribution for penetration testers and security researchers. The repository contains [1434](https://www.blackarch.org/tools.html) tools.
- List of [tools](https://www.blackarch.org/tools.html)
- [Installation Instructions](https://www.blackarch.org/downloads.html)
Create ArchLinux Based BlackArch Template
-----------------------------------------
1. Create ArchlLinux Template
- Follow the [Archlinux Template instructions](/doc/templates/archlinux/)
2. Update Template
sudo pacman -Syyu
3. Clone template
1. Via Qubes VM Manager
2. Via command line
qvm-clone archlinux blackarch
4. Install BlackArch repository
$ curl -O https://blackarch.org/strap.sh
# The SHA1 sum should match: 34b1a3698a4c971807fb1fe41463b9d25e1a4a09
$ sha1sum strap.sh
# Set execute bit
$ chmod +x strap.sh
# Run strap.sh
$ sudo ./strap.sh
5. Install tools
- install all tools
sudo pacman -S blackarch
- or by category:
# list available categories
pacman -Sg | grep blackarch
# install category
sudo pacman -S blackarch-<category>
# example
sudo pacman -S blackarch-forensic
- or specific tool
# Search for tool
pacman -Ss <tool-name>
# Install tool
sudo pacman -S <tool-name>
# Example
pacman -Ss burpsuite
sudo pacman -S burpsuite
6. Create a AppVMs based on the `blackarch` template
- (Optional) Attach necessary devices
Alternative Options to BlackArch
--------------------------------
- [Kali](/doc/pentesting/kali/)
- [PenTester Framework (PTF)](/doc/pentesting/ptf/)
- [Pentesting](/doc/pentesting/)

616
managing-os/pentesting/kali.md Normal file
View File

@ -0,0 +1,616 @@
---
layout: doc
title: How to create a Kali Linux VM
permalink: /doc/pentesting/kali/
redirect_from:
- /doc/kali/
---
# How to create a Kali Linux VM
## Warnings
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool providers.
- Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
- Kali Linux distribution is a rolling distribution based constantly on Debian testing release, so it always will have newer software base than available in Qubes OS debian template. Keep in mind that it may result in problems (especially in regard to package dependency) not covered by this tutorial.
## Qubes 3.2
### How to Create a Kali Linux VM
This guide is being created to give guidance on ways in which you could create a [Kali Linux][kali] penetration testing VM (qube) in Qubes OS.
Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM:
1. Create a HVM and use the official ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm3_2).
2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution:
- using [katoolin]. Explained [here](#katoolin3_2).
- manually. Explained [here](#templatevm-from-debian3_2).
### Kali Linux HVM <a name="hvm3_2"/>
1. Download the Kali installation DVD
2. Create a new HVM
3. Start the HVM with attached CD/DVD
[user@dom0 ~]$ qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
### Debian based Kali Template with Katoolin <a name="katoolin3_2"/>
**Note:** The prompt on each line indicates where each command should be entered (`@dom0`, `@debian-<X>` or `@kali`).
1. (Optional) Check for latest Debian stable template and install it (if not already done)
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
2. Start, update and close your latest Debian template
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
3. Clone `debian-<X>` template (two options)
1. Via Qubes VM Manager
![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png)
2. Via command line
[user@dom0 ~]$ qvm-clone debian-<X> kali
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali` template to latest Debian testing release
[user@kali ~]$ sudo apt-get update
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed.
If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Install Katoolin and add Kali Linux repositories
1. Install Katoolin
[user@kali ~]$ sudo apt-get install git
[user@kali ~]$ git clone https://github.com/LionSec/katoolin.git
[user@kali ~]$ sudo cp katoolin/katoolin.py /usr/bin/katoolin
[user@kali ~]$ sudo chmod +x /usr/bin/katoolin
[user@kali ~]$ rm -rf katoolin
2. Add Kali Linux repositories
- start katoolin
[user@kali ~]$ sudo katoolin
- select 'Add Kali repositories & Update'
1) Add Kali repositories & Update
2) View Categories
3) Install classicmenu indicator
4) Install Kali menu
5) Help
kat > 1
![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png)
- select 'Add kali linux repositories'
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 1
![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png)
- update Kali repositories
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 2
- quit katoolin by pressing `CRTL` + `c` keys
What do you want to do ?> ^CShutdown requested...Goodbye...
7. Clean up and update `kali` template
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
8. Shutdown and trim `kali` template
- Shutdown `kali` template
[user@kali ~]$ sudo shutdown -h now
- In `dom0` console:
[user@dom0 ~]$ qvm-trim-template kali
9. Start image
[user@dom0 ~]$ qvm-start kali
10. Install tools
**Note** [Resize the template disk image][qubes-resize-disk-image] to at least 20GB if you plan on installing all packages from Kali distribution.
1. View Categories
- start katoolin
[user@kali ~]$ sudo katoolin
- select `2) View Categories`
2. Select the categories/tools you want to install
- For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu][katoolin-howto].
- **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`.
11. Create a AppVMs based on the `kali` template
- (Optional) Attach necessary devices
### Kali Linux TemplateVM from a Debian template <a name="templatevm-from-debian3_2"/>
This section will explain how to create your own [Kali] Linux TemplateVM based
on a current stable Debian TemplateVM. The basic idea is to personalize the
template with all the tools needed, and then spin up isolated AppVMs based on
the template.
The steps can be summarised as:
1. Install Qubes stable Debian template
2. Upgrade the template to Debian testing release
3. Install Kali Linux through the ``kali-linux-full`` package
4. Use the template to build AppVM so that you can maintain isolation between
e.g. pentesting jobs
#### Get Kali Linux GPG key
**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures].
This website cannot guarantee that any PGP key you download from the Internet is authentic.
Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint.
This step is required since by (security) default a TemplateVM do not have a
direct Internet connectivity. Users understanding the risks of enabling such
access can change this configuration in firewall settings for the TemplateVM.
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0`, `@kali-rolling`, `@xxxx-dvm` or `@debian-<X>`).
1. Retrive the Kali Linux GPG key using a DispVM.
[user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc
2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to
the Kali Linux template in a further step.
3. Make sure the key is the authentic Kali key.
See the [Kali website] for further advice and instructions on verification.
#### Create a Kali Linux (rolling) template
These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux.
1. (Optional) Check for latest Debian stable template and install it (if not already done)
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
2. Start, update and close your latest Debian template
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
3. Clone `debian-X` template
[user@dom0 ~]$ qvm-clone debian-<X> kali-rolling
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali-rolling` template to latest Debian testing release
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Copy the Kali GPG key from the DispVM to the new template:
[user@xxxx-dvm ~]$ qvm-copy-to-vm kali-rolling kali-key.asc
The DispVM can now be turned off.
7. Add the Kali GPG key to the list of keys trusted to authenticate packages:
[user@kali-rolling ~]$ cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add -
This command should return `OK` on a line by itself.
8. Attempt the upgrade process in the new template.
[user@kali-rolling ~]$ sudo cat <<EOF > /etc/apt/sources.list.d/kali.list
# Kali Linux repository
deb http://http.kali.org/kali kali-rolling main non-free contrib
EOF
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
9. Shut down and trim the new template.
[user@dom0 ~]$ qvm-shutdown kali-rolling
[user@dom0 ~]$ qvm-trim-template kali-rolling
10. Ensure a terminal can be opened in the new template.
[user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal
#### Install the Kali tools
At this point you should have a working template and you can install the tools you need.
1. [Resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB.
2. Install Kali Linux tools:
[user@kali-rolling ~]$ sudo apt-get install kali-linux-full
3. (Optional) Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional)
#### Use the template
The template is ready to be used. You can now spin up AppVMs based on the `kali-rolling` template.
## Qubes 4.0
### How to Create a Kali Linux VM
This guide is being created to give guidance on ways in which you could create a [Kali Linux][kali] penetration testing VM (qube) in Qubes OS.
Kali Linux is the most widely used penetration testing Linux distribution.
There are multiple ways to create a Kali Linux VM:
1. Create a HVM and use the official ISO to install the system or convert a [Virtual Image][kali-vbox]. Explained [here](#hvm4_0).
2. Clone the Qubes OS latest Debian template image and turn it into a Kali Linux distribution:
- using [katoolin]. Explained [here](#katoolin4_0).
- manually. Explained [here](#templatevm-from-debian4_0).
### Kali Linux HVM <a name="hvm4_0"/>
1. Download the Kali installation DVD
2. Create a new HVM
3. Start the HVM with attached CD/DVD
[user@dom0 ~]$ qvm-start <hvm-name> --cdrom <vm-name>:/home/user/Downloads/<iso-name>.iso
### Debian based Kali Template with Katoolin <a name="katoolin4_0"/>
**Note:** The prompt on each line indicates where each command should be entered (`@dom0`, `@debian-<X>` or `@kali`).
1. (Optional) Check for latest Debian stable template and install it (if not already done)
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
2. Start, update and close your latest Debian template
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
3. Clone `debian-<X>` template (two options)
1. Via Qubes VM Manager
![Clone Debian Template](/attachment/wiki/Kali/clone-kali.png)
2. Via command line
[user@dom0 ~]$ qvm-clone debian-<X> kali
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly.
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali` template to latest Debian testing release
[user@kali ~]$ sudo apt-get update
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed.
If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Install Katoolin and add Kali Linux repositories
1. Install Katoolin
[user@kali ~]$ sudo apt-get install git
[user@kali ~]$ git clone https://github.com/LionSec/katoolin.git
[user@kali ~]$ sudo cp katoolin/katoolin.py /usr/bin/katoolin
[user@kali ~]$ sudo chmod +x /usr/bin/katoolin
[user@kali ~]$ rm -rf katoolin
2. Add Kali Linux repositories
- start katoolin
[user@kali ~]$ sudo katoolin
- select 'Add Kali repositories & Update'
1) Add Kali repositories & Update
2) View Categories
3) Install classicmenu indicator
4) Install Kali menu
5) Help
kat > 1
![Add Kali repositories and Update menu](/attachment/wiki/Kali/katoolin-add-update-repo-menu.png)
- select 'Add kali linux repositories'
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 1
![Add Kali repositories](/attachment/wiki/Kali/katoolin-add-repos-menu.png)
- update Kali repositories
1) Add kali linux repositories
2) Update
3) Remove all kali linux repositories
4) View the contents of sources.list file
What do you want to do ?> 2
- quit katoolin by pressing `CRTL` + `c` keys
What do you want to do ?> ^CShutdown requested...Goodbye...
7. Clean up and update `kali` template
[user@kali ~]$ sudo apt-get dist-upgrade
[user@kali ~]$ sudo apt-get autoremove
8. Install tools
**Note** [Resize the template disk image][qubes-resize-disk-image] to at least 20GB if you plan on installing all packages from Kali distribution.
1. View Categories
- start katoolin
[user@kali ~]$ sudo katoolin
- select `2) View Categories`
2. Select the categories/tools you want to install
- For more information on how to use Katoolin see [How to Auto Install All Kali Linux Tools Using “Katoolin” on Debian/Ubuntu][katoolin-howto].
- **Note:** The `all` option does not work for `Information Gathering`, `Web Apps`, `Forensic Tools`, `Reverse Engineering` and `Extra`.
9. Create a AppVMs based on the `kali` template
- (Optional) Attach necessary devices
### Kali Linux TemplateVM from a Debian template <a name="templatevm-from-debian4_0"/>
This section will explain how to create your own [Kali] Linux TemplateVM based
on a current stable Debian TemplateVM. The basic idea is to personalize the
template with all the tools needed, and then spin up isolated AppVMs based on
the template.
The steps can be summarised as:
1. Install Qubes stable Debian template
2. Upgrade the template to Debian testing release
3. Install Kali Linux through the ``kali-linux-full`` package
4. Use the template to build AppVM so that you can maintain isolation between
e.g. pentesting jobs
#### Get Kali Linux GPG key
**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures].
This website cannot guarantee that any PGP key you download from the Internet is authentic.
Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint.
This step is required since by (security) default a TemplateVM do not have a
direct Internet connectivity. Users understanding the risks of enabling such
access can change this configuration in firewall settings for the TemplateVM.
**Note:** The prompt on each line indicates where each command should be entered
(`@dom0`, `@kali-rolling`, `@xxxx-dvm` or `@debian-<X>`).
1. Retrive the Kali Linux GPG key using a DispVM.
[user@xxxx-dvm ~]$ gpg --keyserver hkp://keys.gnupg.net --recv-key 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --list-keys --with-fingerprint 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6
[user@xxxx-dvm ~]$ gpg --export --armor 44C6513A8E4FB3D30875F758ED444FF07D8D0BF6 > kali-key.asc
2. **DO NOT TURN OFF** the DispVM, the `kali-key.asc` file will be copied to
the Kali Linux template in a further step.
3. Make sure the key is the authentic Kali key.
See the [Kali website] for further advice and instructions on verification.
#### Create a Kali Linux (rolling) template
These instructions will show you how to upgrade a Debian TemplateVM to Kali Linux.
1. (Optional) Check for latest Debian stable template and install it (if not already done)
[user@dom0 ~]$ sudo qubes-dom0-update --action="search all" qubes-template-debian
[user@dom0 ~]$ sudo qubes-dom0-update <latest Debian template>
2. Start, update and close your latest Debian template
[user@dom0 ~]$ qvm-start debian-<X>
[user@dom0 ~]$ qvm-run -a debian-<X> gnome-terminal
[user@debian-<X> ~]$ sudo apt-get update
[user@debian-<X> ~]$ sudo apt-get upgrade
[user@dom0 ~]$ qvm-shutdown debian-<X>
3. Clone `debian-X` template
[user@dom0 ~]$ qvm-clone debian-<X> kali-rolling
4. Check the name of currently used repository in `/etc/apt/sources.list` and current testing [Debian release][Debian-releases]. Update repository list accordingly
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/<current stable>/<current testing>/g' /etc/apt/sources.list.d/qubes-r<X>.list
e.g. in this example we update `stretch` stable repository to `buster` testing repository
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list
[user@kali-rolling ~]$ sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list.d/qubes-r<X>.list
5. Upgrade `kali-rolling` template to latest Debian testing release
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
**Note:** During execution of a `dist-upgrade` command read carefully list of packages to be removed. If it contains `qubes-*` packages, terminate operation and try to resolve `qubes-*` packages missing dependencies first.
6. Copy the Kali GPG key from the DispVM to the new template:
[user@xxxx-dvm ~]$ qvm-copy kali-key.asc
The DispVM can now be turned off.
7. Add the Kali GPG key to the list of keys trusted to authenticate packages:
[user@kali-rolling ~]$ cat /home/user/QubesIncoming/dispXXX/kali-key.asc | sudo apt-key add -
This command should return `OK` on a line by itself.
8. Attempt the upgrade process in the new template.
[user@kali-rolling ~]$ sudo cat <<EOF > /etc/apt/sources.list.d/kali.list
# Kali Linux repository
deb http://http.kali.org/kali kali-rolling main non-free contrib
EOF
[user@kali-rolling ~]$ sudo apt-get update
[user@kali-rolling ~]$ sudo apt-get dist-upgrade
[user@kali-rolling ~]$ sudo apt-get autoremove
9. Ensure a terminal can be opened in the new template.
[user@dom0 ~]$ qvm-run -a kali-rolling gnome-terminal
#### Install the Kali tools
At this point you should have a working template and you can install the tools you need.
1. [Resize the template disk image][qubes-resize-disk-image] if you plan on installing the full Kali distribution. For example to install `kali-linux-full` you must **grow** the size of the VM system from 10GB to at least 20GB.
2. Install Kali Linux tools:
[user@kali-rolling ~]$ sudo apt-get install kali-linux-full
3. (Optional) Customise the template's home directory (e.g. install your licensed copy of Burp Suite Professional)
#### Use the template
The template is ready to be used. You can now spin up AppVMs based on the `kali-rolling` template.
### Alternative Options to Kali Linux
* [PenTester Framework][PTF], with [PTF Qubes OS guide][qubes-ptf]
* BlackArch Linux, with [BA Qubes OS guide][qubes-blackarch]
* [KATOOLIN][katoolin-howto]
* more on the [Penetration Testing page][qubes-pentesting]
## Notes
Thanks to the people in [the discussion thread](https://github.com/QubesOS/qubes-issues/issues/1981).
[qubes-verifying-signatures]: /security/verifying-signatures/
[qubes-pentesting]: /doc/pentesting/
[qubes-blackarch]: /doc/pentesting/blackarch/
[qubes-ptf]: /doc/pentesting/ptf/
[qubes-template-debian-install]: /doc/templates/debian/#install
[qubes-resize-disk-image]: /doc/resize-disk-image/
[kali]: https://www.kali.org/
[kali-vbox]: https://www.offensive-security.com/kali-linux-vmware-virtualbox-image-download/
[kali website]: https://docs.kali.org/introduction/download-official-kali-linux-images
[PTF]: https://www.trustedsec.com/may-2015/new-tool-the-pentesters-framework-ptf-released/
[katoolin]: https://github.com/LionSec/katoolin
[katoolin-howto]: http://www.tecmint.com/install-kali-linux-tools-using-katoolin-on-ubuntu-debian/
[Debian-releases]: https://www.debian.org/releases/

121
managing-os/pentesting/ptf.md Normal file
View File

@ -0,0 +1,121 @@
---
layout: doc
title: How to create Penetration Testers Framework (PTF) VM
permalink: /doc/pentesting/ptf/
redirect_from:
- /doc/ptf/
---
**General reminder:**
- The installation scripts and provided tools may have bugs, be vulnerable to Man in the Middle (MitM) attacks or other vulnerabilities.
- Adding additional repositories or tools for installing software extends your trust to those tool providers.
Please keep in mind that using such a VM or VM's based on the template for security and privacy critical tasks is not recommended.
How to create Penetration Testers Framework (PTF) VM
====================================================
"The PenTesters Framework (PTF) is a Python script designed for Debian/Ubuntu/ArchLinux based distributions to create a similar and familiar distribution for Penetration Testing.
PTF attempts to install all of your penetration testing tools (latest and greatest), compile them, build them, and make it so that you can install/update your distribution on any machine." (source [PTF Readme](https://github.com/trustedsec/ptf/blob/master/README.md))
**Note** PTF works on Debian testing as well as on Debian 8. PTF itself works with Debian 8, but the software tools will have missing dependencies. Metasploit for example requires a newer Ruby version than Debian 8 has in the repositories. Therefore the best way to install PTF is by upgrading a Debian 8 into Debian testing with additional Kali repositories. Instead of installing the tools from Kali, PTF will install and update the newest tools.
Create Debian Based Penetration Testers Framework (PTF) Template
----------------------------------------------------------------
1. Create PTF template
1. Follow [Create Debian Based Kali Template](/doc/pentesting/kali/) till step 7.
2. (Optional) Rename the cloned template to `ptf`
2. Download PTF
sudo apt-get install git
cd /opt
sudo git clone https://github.com/trustedsec/ptf.git
- (Optional) Configure PTF
1. Go to configuration directory
cd /opt/ptf/config
2. Edit the configuration file
for example by using vim:
sudo vim ptf.config
the configuration options are described in the `ptf.config` file
3. Install PTF
cd /opt/ptf
sudo ./ptf
**Note:** the config file has to be in the same directory as the executable. It is not
possible to do sudo ptf/ptf
PTF will put itself into `/usr/local/bin/ptf`. You can use `ptf` from now on.
4. Install/Update modules (tools)
1. Start PTF
sudo ptf
![PTF start banner](/attachment/wiki/PTF/ptf-banner.png)
2. Show available modules (tools)
ptf> show modules
3. Install/Update modules (all/)
- Install/Update all tools
ptf> use modules/install_update_all
- or by category Install/Update
ptf> use modules/code-audit/install_update_all
- or individually (example Metasploit)
1. Search for module
ptf> search metasploit
[*] Search results below:
modules/exploitation/metasploit
2. Use module
ptf> use modules/exploitation/metasploit
ptf:(modules/exploitation/metasploit)>
3. Install module
ptf:(modules/exploitation/metasploit)>install
4. Run Metasploit
ptf:(modules/exploitation/metasploit)>exit
ptf> quit
[*] Exiting PTF - the easy pentest platform creation framework.
sudo msfconsole
5. Create an AppVM based on the `ptf` template
- (Optional) Attach necessary devices
Alternative Options to PTF
--------------------------
- [BlackArch](/doc/pentesting/blackarch/)
- [Kali](/doc/pentesting/kali/)
- [Pentesting](/doc/pentesting/)

41
managing-os/ubuntu.md Normal file
View File

@ -0,0 +1,41 @@
---
layout: doc
title: Ubuntu Template
permalink: /doc/templates/ubuntu/
redirect_from:
- /doc/ubuntu/
- /en/doc/templates/ubuntu/
- /doc/Templates/Ubuntu/
- /wiki/Templates/Ubuntu/
---
Ubuntu template(s)
==================
If you would like to use Ubuntu Linux distribution in your AppVMs, you can build and
install one of the available Ubuntu templates. These templates are currently not
available in ready to use binary packages, because Canonical does not allow
redistribution of a modified Ubuntu. The redistribution is not allowed by their
[Intellectual property rights policy](https://www.ubuntu.com/legal/terms-and-policies/intellectual-property-policy).
Install
-------
It can be built using [Qubes Builder](/doc/qubes-builder/). You can also access its
documentation in the [source code
repository](https://github.com/QubesOS/qubes-builder/blob/master/README.md).
To quickly prepare the builder configuration, you can use the `setup` script
available in the repository - it will interactively ask you which templates you
want to build.
The build for Ubuntu 14.04 LTS (Trusty) should be straightforward.
The build for Ubuntu 16.04 LTS (Xenial) is straightforward. Note that packages perl-Digest-MD5 and perl-Digest-SHA are required for the build to succeed.
----------
If you want to help in improving the template, feel free to
[contribute](/doc/contributing/).

158
managing-os/windows/windows-tools.md Normal file
View File

@ -0,0 +1,158 @@
---
layout: doc
title: Qubes Windows Tools
permalink: /doc/windows-tools/
redirect_from:
- /doc/windows-appvms/
- /en/doc/windows-appvms/
- /doc/WindowsAppVms/
- /wiki/WindowsAppVms/
---
Qubes Windows Tools
===================
Qubes Windows Tools are a set of programs and drivers that provide integration of Windows AppVMs with the rest of the Qubes system. Currently the following features are available for Windows VMs after installation of those tools:
- Seamless GUI mode that integrates apps windows onto the common Qubes trusted desktop
- Support for [secure clipboard copy/paste](/doc/copy-paste/) between the Windows VM and other AppVMs
- Support for [secure file exchange](/doc/copying-files/) between the Windows VM and other AppVMs
- Support for qvm-run and generic qrexec for the Windows VM (e.g. ability to run custom service within/from the Windows VM)
- Xen PV drivers for Windows that increase performance compared to qemu emulated devices
Qubes Windows Tools are open source and are distributed under a GPL license.
NOTES:
- Qubes Windows Tools are currently unmaintained
- Currently only 64-bit versions of Windows 7 are supported by Qubes Windows Tools. Only emulated SVGA GPU is supported (although [there has been reports](https://groups.google.com/forum/#!topic/qubes-users/cmPRMOkxkdA) on working GPU passthrough).
- There is currently no audio support for Windows HVMs.
- There is currently no USB pass-through support for Windows HVMs.
- __This page documents the process of installing Qubes Windows Tools on versions up to R3.2.__. Installation on Qubes R4.0 is possible but is a work in progress and there are limitations/bugs (see [issue #3585](https://github.com/QubesOS/qubes-issues/issues/3585)).
Installing Windows OS in a Qubes VM
-----------------------------------
Please refer to [this page](/doc/windows-vm/) for instructions on how to install Windows in a Qubes VM.
NOTE: It is strongly suggested to enable autologon for any Windows HVMs that will have Qubes Tools installed. To do so, run `netplwiz` command from the `Win+R`/Start menu and uncheck the *Users must enter a user name and password to use this computer* option.
Installing Qubes guest tools in Windows 7 VMs
---------------------------------------------
First, make sure that `qubes-windows-tools` is installed in your system:
~~~
sudo qubes-dom0-update qubes-windows-tools
~~~
(If the above command does not work, it could be that the Qubes Tools are not in the stable repo yet. Try installing from the testing repo instead.)
You can also install the package from testing repositories, where we usually publish new versions first:
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing qubes-windows-tools
~~~
This package brings the ISO with Qubes Windows Tools that is passed to the VM when `--install-windows-tools` is specified for the `qvm-start` command. Please note that none of this software ever runs in Dom0 or any other part of the system except for the Windows AppVM in which it is to be installed.
Before proceeding with the installation we need to disable Windows mechanism that allows only signed drivers to be installed, because currently (beta releases) the drivers we provide as part of the Windows Tools are not digitally signed with a publicly recognizable certificate. To do that:
- Start command prompt as Administrator, i.e. right click on the Command Prompt icon (All Programs -> Accessories) and choose "Run as administrator"
- In the command prompt type `bcdedit /set testsigning on`
- Reboot your Windows VM
In the future this step will not be necessary anymore, because we will sign our drivers with a publicly verifiable certificate. However, it should be noted that even now, the fact that those drivers are not digitally signed, this doesn't affect security of the Windows VM in 'any' way. This is because the actual installation ISO (the `qubes-windows-tools-*.iso` file) is distributed as a signed RPM package and its signature is verified by the `qubes-dom0-update` utility once it's being installed in Dom0. The only downside of those drivers not being signed is the inconvenience to the user that he or she must disable the signature enforcement policy before installing the tools.
To install the Qubes Windows Tools in a Windows VM one should start the VM passing the additional option `--install-windows-tools`:
~~~
qvm-start lab-win7 --install-windows-tools
~~~
Once the Windows VM boots, a CDROM should appear in the 'My Computer' menu (typically as `D:`) with a setup program in its main directory.
After successful installation, the Windows VM must be shut down and started again, possibly a couple of times.
Qubes will automatically detect the tools has been installed in the VM and will set appropriate properties for the VM, such as `qrexec_installed`, `guiagent_installed`, and `default_user`. This can be verified (but is not required) using qvm-prefs command:
~~~
qvm-prefs <your-appvm-name>
~~~
NOTE: it is recommended to increase the default value of Windows VM's `qrexec_timeout` property from 60 (seconds) to, for example, 300. During one of the first reboots after Windows Tools installation Windows user profiles are moved onto the private VM's virtual disk (private.img) and this operation can take some time. Moving profiles is performed in an early boot phase when qrexec is not yet running, so timeout may occur with the default value. To change the property use this command in dom0:
~~~
qvm-prefs -s <vm-name> qrexec_timeout 300
~~~
Using Windows AppVMs in seamless mode
-------------------------------------
Once you start a Windows-based AppVM with Qubes Tools installed, you can easily start individual applications from the VM (note the `-a` switch used here, which will auto-start the VM if it is not running):
~~~
qvm-run -a my-win7-appvm explorer.exe
~~~
![windows-seamless-4.png](/attachment/wiki/WindowsAppVms/windows-seamless-4.png) ![windows-seamless-1.png](/attachment/wiki/WindowsAppVms/windows-seamless-1.png)
Also, the inter-VM services work as usual -- e.g. to request opening a document or URL in the Windows AppVM from another VM:
~~~
[user@work ~]$ qvm-open-in-vm work-win7 roadmap.pptx
~~~
~~~
[user@work ~]$ qvm-open-in-vm work-win7 https://invisiblethingslab.com
~~~
... just like in the case of Linux AppVMs. Of course all those operations are governed by central policy engine running in Dom0 -- if the policy doesn't contain explicit rules for the source and/or target AppVM, the user will be asked whether to allow or deny the operation.
Inter-VM file copy and clipboard works for Windows AppVMs the same way as for Linux AppVM (except that we don't provide a command line wrapper, `qvm-copy-to-vm` in Windows VMs) -- to copy files from Windows AppVMs just right-click on the file in Explorer, and choose: Send To-\> Other AppVM.
To simulate CTRL-ALT-DELETE in the HVM (SAS, Secure Attention Sequence), press Ctrl-Alt-Home while having any window of this VM in the foreground.
![windows-seamless-7.png](/attachment/wiki/WindowsAppVms/windows-seamless-7.png)
Changing between seamless and full desktop mode
-----------------------------------------------
You can switch between seamless and "full desktop" mode for Windows HVMs in their settings in Qubes Manager. The latter is the default.
Using template-based Windows AppVMs
-----------------------------------
Qubes allows HVM VMs to share a common root filesystem from a select Template VM, just as for Linux AppVMs. This mode is not limited to Windows AppVMs, and can be used for any HVM (e.g. FreeBSD running in a HVM).
In order to create a HVM TemplateVM one can use the following command, suitably adapted:
~~~
qvm-create --class TemplateVM win7-x64-template --property virt_mode=HVM --property kernel='' -l green
~~~
... , set memory as appropriate, and install Windows OS (or other OS) into this template the same way as you would install it into a normal HVM -- please see instructions on [this page](/doc/hvm-create/).
If you use this Template as it is, then any HVMs that use it will effectively be DisposableVMs - the User directory will be wiped when the HVN is closed down.
If you want to retain the User directory between reboots, then it would make sense to store the `C:\Users` directory on the 2nd disk which is automatically exposed by Qubes to all HVMs.
This 2nd disk is backed by the `private.img` file in the AppVMs' and is not reset upon AppVMs reboot, so the user's directories and profiles would survive the AppVMs reboot, unlike the "root" filesystem which will be reverted to the "golden image" from the Template VM automatically.
To facilitate such separation of user profiles, Qubes Windows Tools provide an option to automatically move `C:\Users` directory to the 2nd disk backed by `private.img`.
It's a selectable feature of the installer, enabled by default.
If that feature is selected during installation, completion of the process requires two reboots:
- The private disk is initialized and formatted on the first reboot after tools installation. It can't be done **during** the installation because Xen mass storage drivers are not yet active.
- User profiles are moved to the private disk on the next reboot after the private disk is initialized.
Reboot is required because the "mover utility" runs very early in the boot process so OS can't yet lock any files in there.
This can take some time depending on the profiles' size and because the GUI agent is not yet active dom0/Qubes Manager may complain that the AppVM failed to boot.
That's a false alarm (you can increase AppVM's default boot timeout using `qvm-prefs`), the VM should appear "green" in Qubes Manager shortly after.
It also makes sense to disable Automatic Updates for all the template-based AppVMs -- of course this should be done in the Template VM, not in individual AppVMs, because the system-wide settings are stored in the root filesystem (which holds the system-wide registry hives).
Then, periodically check for updates in the Template VM and the changes will be carried over to any child AppVMs.
Once the template has been created and installed it is easy to create AppVMs based on it:
~~~
qvm-create --hvm <new windows appvm name> --template <name of template vm> --label <label color>
~~~

188
managing-os/windows/windows-vm.md Normal file
View File

@ -0,0 +1,188 @@
---
layout: doc
title: Installing a Windows VM
permalink: /doc/windows-vm/
---
Installing a Windows VM
=======================
Qubes 4.0 - importing a Windows VM from R3.2
-------------------------------------------
Importing should work, simply make sure that you are not using Xen's newer linux stubdomain and that the VM is in HVM mode (these steps should be done automatically when importing the VM):
~~~
qvm-features VMNAME linux-stubdom ''
qvm-prefs VMNAME virt_mode hvm
~~~
Note however that you are better off creating a new Windows VM to benefit from the more recent emulated hardware: R3.2 uses a MiniOS based stubdomain with an old and mostly unmaintained 'qemu-traditional' while R4.0 uses a Linux based stubdomain with a recent version of upstream qemu (see [this post](https://groups.google.com/d/msg/qubes-devel/tBqwJmOAJ94/xmFCGJnuAwAJ)).
Windows VM installation
-----------------------
### Summary ###
~~~
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
qvm-prefs win7new kernel ''
qvm-volume extend win7new:root 25g
qvm-prefs win7new debug true
qvm-features win7new video-model cirrus
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
# restart after the first part of the windows installation process ends
qvm-start win7new
# once Windows is installed and working
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
qvm-features --unset win7new video-model
qvm-prefs win7new qrexec_timeout 300
# with Qubes Windows Tools installed:
qvm-prefs win7new debug false
~~~
To install Qubes Windows Tools, follow instructions [below](#xen-pv-drivers-and-qubes-windows-tools).
### Detailed instructions ###
MS Windows versions considerations:
- The instructions *may* work on other versions than Windows 7 x64 but haven't been tested.
- Qubes Windows Tools (QWT) only supports Windows 7 x64. Note that there are [known issues](https://github.com/QubesOS/qubes-issues/issues/3585) with QWT on Qubes 4.x
Create a VM named win7new in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH):
~~~
qvm-create --class StandaloneVM --label red --property virt_mode=hvm win7new
~~~
Windows' installer requires a significant amount of memory or else the VM will crash with such errors:
`/var/log/xen/console/hypervisor.log`:
> p2m_pod_demand_populate: Dom120 out of PoD memory! (tot=102411 ents=921600 dom120)
> (XEN) domain_crash called from p2m-pod.c:1218
> (XEN) Domain 120 (vcpu#0) crashed on cpu#3:
So, increase the VM's memory to 4096MB (memory = maxmem because we don't use memory balancing).
~~~
qvm-prefs win7new memory 4096
qvm-prefs win7new maxmem 4096
~~~
Disable direct boot so that the VM will go through the standard cdrom/HDD boot sequence:
~~~
qvm-prefs win7new kernel ''
~~~
A typical Windows 7 installation requires between 15GB up to 19GB of disk space depending on the version (Home/Professional/...). Windows updates also end up using significant space. So, extend the root volume from the default 10GB to 25GB (note: it is straightforward to increase the root volume size after Windows is installed: simply extend the volume again in dom0 and then extend the system partition with Windows's disk manager).
~~~
qvm-volume extend win7new:root 25g
~~~
Set the debug flag in order to have a graphical console:
~~~
qvm-prefs win7new debug true
~~~
The second part of the installation process will crash with the standard VGA video adapter and the VM will stay in "transient" mode with the following error in `guest-win7new-dm.log`:
> qemu: /home/user/qubes-src/vmm-xen-stubdom-linux/build/qemu/exec.c:1187: cpu_physical_memory_snapshot_get_dirty: Assertion `start + length <= snap->end' failed.
To avoid that error we temporarily have to switch the video adapter to 'cirrus':
~~~
qvm-features win7new video-model cirrus
~~~
The VM is now ready to be started; the best practice is to use an installation ISO [located in a VM](/doc/hvm/#installing-an-os-in-an-hvm-domain):
~~~
qvm-start --cdrom=untrusted:/home/user/windows_install.iso win7new
~~~
Given the higher than usual memory requirements of Windows, you may get a `Not enough memory to start domain 'win7new'` error. In that case try to shutdown unneeded VMs to free memory before starting the Windows VM.
At this point you may open a tab in dom0 for debugging, in case something goes amiss:
~~~
tailf /var/log/qubes/vm-win7new.log \
/var/log/xen/console/hypervisor.log \
/var/log/xen/console/guest-win7new-dm.log
~~~
The VM will shutdown after the installer completes the extraction of Windows installation files. It's a good idea to clone the VM now (eg. `qvm-clone win7new win7newbkp1`). Then, (re)start the VM with `qvm-start win7new`.
The second part of Windows' installer should then be able to complete successfully. You may then perform the following post-install steps:
Decrease the VM's memory to a more reasonable value (memory balancing on Windows is unstable so keep `memory` equal to `maxmen`).
~~~
qvm-prefs win7new memory 2048
qvm-prefs win7new maxmem 2048
~~~
Revert to the standard VGA adapter :
~~~
qvm-features --unset win7new video-model
~~~
Finally, increase the VM's `qrexec_timeout`: in case you happen to get a BSOD or a similar crash in the VM, utilities like chkdsk won't complete on restart before qrexec_timeout automatically halts the VM. That can really put the VM in a totally unrecoverable state, whereas with higher qrexec_timeout, chkdsk or the appropriate utility has plenty of time to fix the VM. Note that Qubes Windows Tools also require a larger timeout to move the user profiles to the private volume the first time the VM reboots after the tools' installation.
~~~
qvm-prefs win7new qrexec_timeout 300
~~~
At that point you should have a functional and stable Windows VM, although without updates, Xen's PV drivers nor Qubes integration (see sections [Windows Update](#windows-update) and [Xen PV drivers and Qubes Windows Tools](#xen-pv-drivers-and-qubes-windows-tools) below). It is a good time to clone the VM again.
Windows update
--------------
Depending on how old your installation media is, fully updating your Windows VM may take *hours* (this isn't specific to Xen/Qubes) so make sure you clone your VM between the mandatory reboots in case something goes wrong. This [comment](https://github.com/QubesOS/qubes-issues/issues/3585#issuecomment-366471111) provides useful links on updating a Windows 7 SP1 VM.
Note: if you already have Qubes Windows Tools installed the video adapter in Windows will be "Qubes video driver" and you won't be able to see the Windows Update process when the VM is being powered off because Qubes services would have been stopped by then. Depending on the size of the Windows update packs it may take a bit of time until the VM shutdowns by itself, leaving one wondering if the VM has crashed or still finalizing the updates (in dom0 a changing CPU usage - eg. shown with `xentop` - usually indicates that the VM hasn't crashed).
To avoid guessing the VM's state enable debugging (`qvm-prefs -s win7new debug true`) and in Windows' device manager (My computer -> Manage / Device manager / Display adapters) temporarily re-enable the standard VGA adapter and disable "Qubes video driver". You can disable debugging and revert to Qubes' display once the VM is updated.
Xen PV drivers and Qubes Windows Tools
------------------------------------
Installing Xen's PV drivers in the VM will lower its resources usage when using network and/or I/O intensive applications, but *may* come at the price of system stability (although Xen's PV drivers on a Win7 VM are usually very stable). There are two ways of installing the drivers:
1. installing the drivers independently, from Xen's [official site](https://www.xenproject.org/developers/teams/windows-pv-drivers.html)
2. installing Qubes Windows Tools (QWT), which bundles Xen's PV drivers.
Notes about using Xen's VBD (storage) PV driver:
- Windows 7: installing the driver requires a fully updated VM or else you'll likely get a BSOD and a VM in a difficult to fix state. Updating Windows takes *hours* and for casual usage there isn't much of a performance between the disk PV driver and the default one; so there is likely no need to go through the lengthy Windows Update process if your VM doesn't have access to untrusted networks and if you don't use I/O intensive apps. If you plan to update your newly installed Windows VM it is recommended that you do so *before* installing Qubes Windows Tools (QWT). If QWT are installed, you should temporarily re-enable the standard VGA adapter in Windows and disable Qubes' (see the section above).
- the option to install the storage PV driver is disabled by default in Qubes Windows Tools
- in case you already had QWT installed without the storage PV driver and you then updated the VM, you may then install the driver from Xen's site (xenvbd.tar).
Installing Qubes Windows Tools:
- on R3.2: see [this page](/doc/windows-tools/)
- R4.0: you'll have to install QWT for Qubes R3.2. Be warned that QWT on R4.0 is a work in progress though (see [issue #3585](https://github.com/QubesOS/qubes-issues/issues/3585) for instructions and known issues).
With Qubes Windows Tools installed the early graphical console provided in debugging mode isn't needed anymore since Qubes' display driver will be used instead of the default VGA driver:
~~~
qvm-prefs -s win7new debug false
~~~
Further customization
---------------------
Please see the [Customizing Windows 7 templates](/doc/windows-template-customization/) page (despite the focus on preparing the VM for use as a template, most of the instructions are independent from how the VM will be used - ie. TemplateVM or StandaloneVM).

69
privacy-guides/anonymizing-your-mac-address.md Normal file
View File

@ -0,0 +1,69 @@
---
layout: doc
title: Anonymizing your MAC Address
permalink: /doc/anonymizing-your-mac-address/
redirect_from:
- /doc/randomizing-your-mac-address/
---
Anonymizing your MAC Address
============================
Although it is not the only metadata broadcast by network hardware, changing the default [MAC Address](https://en.wikipedia.org/wiki/MAC_address) of your hardware could be [an important step in protecting privacy](https://tails.boum.org/contribute/design/MAC_address/#index1h1).
Currently, Qubes OS *does not* automatically "anonymize" or spoof the MAC Address, so unless this gets implemented by default you can randomize your MAC Address with the following guide.
## Upgrading and configuring Network Manager in Qubes
Newer versions of Network Manager have a robust set of options for randomizing MAC addresses, and can handle the entire process across reboots, sleep/wake cycles and different connection states.
In particular, versions 1.4.2 and later should be well suited for Qubes. Qubes R4.0's default sys-net should have 1.8.2-4 by default.
Network Manager 1.4.2 or later is available from the Fedora 25 repository as well as the Debian 9 repository, which you can install by [upgrading a Debian 8 template to version 9.](/doc/debian-template-upgrade-8/)
Check that Network Manager version is now at least 1.4.2:
~~~
$ sudo NetworkManager -V
1.4.2
~~~
## Randomize a single connection
Right click on the Network Manager icon of your NetVM in the tray and click 'Edit Connections..'.
Select the connection to randomize and click Edit.
Select the Cloned MAC Address drop down and set to Random or Stable.
Stable will generate a random address that persists until reboot, while Random will generate an address each time a link goes up.
![Edit Connection](/attachment/wiki/RandomizeMAC/networkmanager-mac-random.png)
Save the change and reconnect the connection (click on Network Manager tray icon and click disconnect under the connection, it should automatically reconnect).
## Randomize all Ethernet and Wifi connections
These steps should be done inside a template to be used to create a NetVM as it relies on creating a config file that would otherwise be deleted after a reboot due to the nature of AppVMs.
Write the settings to a new file in the `/etc/NetworkManager/conf.d/` directory, such as `00-macrandomize.conf`.
The following example enables Wifi and Ethernet MAC address randomization while scanning (not connected), and uses a randomly generated but persistent MAC address for each individual Wifi and Ethernet connection profile.
~~~
[device]
wifi.scan-rand-mac-address=yes
[connection]
wifi.cloned-mac-address=stable
ethernet.cloned-mac-address=stable
connection.stable-id=${CONNECTION}/${BOOT}
~~~
* `stable` in combination with `${CONNECTION}/${BOOT}` generates a random address that persists until reboot.
* `random` generates a random address each time a link goes up.
To see all the available configuration options, refer to the man page: `man nm-settings`
Next, create a new NetVM using the edited template and assign network devices to it.
Finally, shutdown all VMs and change the settings of sys-firewall, etc. to use the new NetVM.
You can check the MAC address currently in use by looking at the status pages of your router device(s), or inside the NetVM with the command `sudo ip link show`.

49
privacy-guides/martus.md Normal file
View File

@ -0,0 +1,49 @@
---
layout: doc
title: Martus
permalink: /doc/martus/
---
Martus
======
[Martus] is a free, open source, secure information collection and management tool
that empowers rights activists to be stronger in their fight against injustice and abuse.
To install Martus in a qube:
1. Create a Debian 8 backports template using the Qubes VM Manager or running
`qvm-clone debian-8 debian-8-backports` in dom0.
2. Add backports to the sources for the new template by opening a terminal in
the new template, run `sudo vi /etc/apt/sources.list` and add
`deb http://http.debian.net/debian jessie-backports main`.
(If you are new to `vi` text editing, type `i` to be able to edit, and when
done editing press `ESC` then type `:x` and press `ENTER`.)
3. Update source list: `sudo apt-get update`.
4. Install `openjdk` and `openjfx` from backports:
`sudo apt-get -t jessie-backports install openjdk-8-jre openjfx`.
5. You may need to install `unzip` to be able to unzip Martus after you
download it: `sudo apt-get install unzip`.
6. Create a new qube/appvm based on your `debian-8-martus` template with
whatever color and networking you want (`sys-whonix` probably preferred)
using the Qubes VM Manager or running
`qvm-create -t debian-8-backports -l blue martus` and
`qvm-prefs -s martus netvm sys-whonix` in dom0.
7. Download the latest Martus version from https://martus.org.
8. Unzip the Martus package `unzip Martus-5.1.1.zip`.
9. `cd` into new folder: `cd Martus-5.1.1`.
10. Run Martus: `java -jar martus.jar`.
[Martus]: https://martus.org/

65
privacy-guides/signal.md Normal file
View File

@ -0,0 +1,65 @@
---
layout: doc
title: Signal
permalink: /doc/signal/
---
Signal
======
What is [Signal]?
[According to Wikipedia:][signal-wikipedia]
> Signal is an encrypted instant messaging and voice calling application
> for Android and iOS. It uses end-to-end encryption to secure all
> communications to other Signal users. Signal can be used to send and receive
> encrypted instant messages, group messages, attachments and media messages.
> Users can independently verify the identity of their messaging correspondents
> by comparing key fingerprints out-of-band. During calls, users can check the
> integrity of the data channel by checking if two words match on both ends of
> the call.
>
> Signal is developed by Open Whisper Systems. The clients are published as free
> and open-source software under the GPLv3 license.
How to install Signal in Qubes
------------------------------
**CAUTION:** Before proceeding, please carefully read [On Digital Signatures and Key Verification][qubes-verifying-signatures].
This website cannot guarantee that any PGP key you download from the Internet is authentic.
Always obtain a trusted key fingerprint via other channels, and always check any key you download against your trusted copy of the fingerprint.
1. (Optional)Create a TemplateVM (Debian 9)
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-debian-9
2. Open a terminal in Debian 9
[user@dom0 ~]$ qvm-run -a debian-9 gnome-terminal
3. Use these commands in your terminal
(Optional)[user@debian-8 ~]$ sudo apt-get install curl
[user@debian-8 ~]$ curl -s https://updates.signal.org/desktop/apt/keys.asc | sudo apt-key add -
[user@debian-8 ~]$ echo "deb [arch=amd64] https://updates.signal.org/desktop/apt xenial main" | sudo tee -a /etc/apt/sources.list.d/signal-xenial.list
[user@debian-8 ~]$ sudo apt update && sudo apt install signal-desktop
5. Shutdown the TemplateVM :
[user@dom0 ~]$ qvm-shutdown debian-9
6. Create an AppVM based on this TemplateVM
7. With your mouse select the `Q` menu -> `Domain: "AppVM Name"` -> `"AppVM Name": Add more shortcuts`
(or `"AppVM Name": VM Settings` -> `Applications`).
Select `Signal` from the left `Available` column, move it to the right `Selected` column by clicking the `>` button and then `OK` to apply the changes and close the window.
-----
[qubes-verifying-signatures]: /security/verifying-signatures/
[Signal]: https://whispersystems.org/
[signal-wikipedia]: https://en.wikipedia.org/wiki/Signal_(software)
[shortcut]: https://support.whispersystems.org/hc/en-us/articles/216839277-Where-is-Signal-Desktop-on-my-computer-
[shortcut-desktop]: /doc/managing-appvm-shortcuts/#tocAnchor-1-1-1
[message]: https://groups.google.com/d/msg/qubes-users/rMMgeR-KLbU/XXOFri26BAAJ
[mailing list]: /support/

86
privacy-guides/tails.md Normal file
View File

@ -0,0 +1,86 @@
---
layout: doc
title: Running Tails in Qubes
permalink: /doc/tails/
redirect_from:
- /doc/running-tails
---
Running Tails in Qubes
============================
[Tails](https://tails.boum.org) stands for The Amnesic Incognito Live System.
It is a live operating system that aims to preserve your privacy and anonymity.
Tails is intended to be booted off of a live CD and leave no trace on the computer it is run on, but using Tails this way requires the user to restart their computer every time they want to switch from their installed OS to Tails.
Despite this, in case that method becomes cumbersome, Tails can be used inside virtualization software and Qubes.
To run Tails under Qubes:
1. Read about [creating and using HVM qubes](/doc/hvm/)
2. Download and verify Tails from [https://tails.boum.org](https://tails.boum.org) in a qube, (saved as `/home/user/Downloads/tails.iso` on qube "isoVM" for purposes of this guide).
3. Create a HVM
- In Manager, click "VM menu" and select "Create VM"
- Name the new qube - "Tails"
- Select "HVM"
- Set "initial memory" and "max memory" as the same ([official documentation](https://tails.boum.org/doc/about/requirements/index.en.html) recommends at least 2048 MB)
- Configure networking
- Click "OK" to create new HVM.
4. Open dom0 Konsole and start Tails:
qvm-start Tails --cdrom=isoVM:/home/user/Downloads/tails.iso
5. Configure Tails at start up.
6. Once the Tails qube has started, configure networking in the qube.
- Check the IP address allocated to the qube - either from GUI Manager, or ```qvm-ls -n Tails``` in Konsole. (E.g. `10.137.1.101` with gateway `10.137.1.1`)
- In the Tails qube, open systems menu in top-right corner. Select "Wired Settings", and change IPv4 configuration from "Automatic (DHCP)" to "Manual".
- Enter the Address: `10.137.1.101` in our example.
- Enter the Netmask: `255.255.255.0`
- Enter the Gateway: `10.137.1.1` in our example.
- Enter DNS: `10.137.1.1` in our example.
- Click "Apply". You should now see "Connected".
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
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.
If you intend to do this, you should read [the warnings](https://tails.boum.org/doc/advanced_topics/virtualization/) from the Tails team about it.
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.

281
privacy-guides/torvm.md Normal file
View File

@ -0,0 +1,281 @@
---
layout: doc
title: TorVM
permalink: /doc/torvm/
redirect_from:
- /doc/privacy/torvm/
- /en/doc/torvm/
- /doc/TorVM/
- /doc/UserDoc/TorVM/
- /wiki/UserDoc/TorVM/
---
Known issues:
-------------
- [Service doesn't start without (even empty) user torrc](https://groups.google.com/d/msg/qubes-users/fyBVmxIpbSs/R5mxUcIEZAQJ)
Qubes TorVM (qubes-tor)
==========================
Qubes TorVM is a deprecated ProxyVM service that provides torified networking to
all its clients. **If you are interested in TorVM, you will find the
[Whonix implementation in Qubes](/doc/privacy/whonix/) a
more usable and robust solution for creating a torifying traffic proxy.**
By default, any AppVM using the TorVM as its NetVM will be fully torified, so
even applications that are not Tor aware will be unable to access the outside
network directly.
Moreover, AppVMs running behind a TorVM are not able to access globally
identifying information (IP address and MAC address).
Due to the nature of the Tor network, only IPv4 TCP and DNS traffic is allowed.
All non-DNS UDP and IPv6 traffic is silently dropped.
See [this article](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html) for a description of the concept, architecture, and the original implementation.
## Warning + Disclaimer
1. Qubes TorVM is produced independently from the Tor(R) anonymity software and
carries no guarantee from The Tor Project about quality, suitability or
anything else.
2. Qubes TorVM is not a magic anonymizing solution. Protecting your identity
requires a change in behavior. Read the "Protecting Anonymity" section
below.
3. Traffic originating from the TorVM itself **IS NOT** routed through Tor.
This includes system updates to the TorVM. Only traffic from VMs using TorVM
as their NetVM is torified.
Installation
============
0. *(Optional)* If you want to use a separate vm template for your TorVM
qvm-clone fedora-23 fedora-23-tor
1. In dom0, create a proxy vm and disable unnecessary services and enable qubes-tor
qvm-create -p torvm
qvm-service torvm -d qubes-netwatcher
qvm-service torvm -d qubes-firewall
qvm-service torvm -e qubes-tor
# if you created a new template in the previous step
qvm-prefs torvm -s template fedora-23-tor
2. From your TemplateVM, install the torproject Fedora repo
sudo yum install qubes-tor-repo
3. Then, in the template, install the TorVM init scripts
sudo yum install qubes-tor
5. Configure an AppVM to use TorVM as its NetVM (for example a vm named anon-web)
qvm-prefs -s anon-web netvm torvm
... repeat for any other AppVMs you want torified...
6. Shutdown the TemplateVM.
7. Set the prefs of your TorVM to use the default sys-net or sys-firewall as its NetVM
qvm-prefs -s torvm netvm sys-net
8. Start the TorVM and any AppVM you have configured to be route through the TorVM
9. From the AppVMs, verify torified connectivity, e.g. by visiting
`https://check.torproject.org`.
### Troubleshooting ###
1. Check if the qubes-tor service is running (on the torvm)
[user@torvm] $ sudo service qubes-tor status
2. Tor logs to syslog, so to view messages use
[user@torvm] $ sudo grep Tor /var/log/messages
3. Restart the qubes-tor service (and repeat 1-2)
[user@torvm] $ sudo service qubes-tor restart
4. You may need to manually create the private data directory and set its permissions:
[user@torvm] $ sudo mkdir /rw/usrlocal/lib/qubes-tor
[user@torvm] $ sudo chown user:user /rw/usrlocal/lib/qubes-tor
Usage
=====
Applications should "just work" behind a TorVM, however there are some steps
you can take to protect anonymity and increase performance.
## Protecting Anonymity
The TorVM only purports to prevent the leaking of two identifiers:
1. WAN IP Address
2. NIC MAC Address
This is accomplished through transparent TCP and transparent DNS proxying by
the TorVM.
The TorVM cannot anonymize information stored or transmitted from your AppVMs
behind the TorVM.
*Non-comprehensive* list of identifiers TorVM does not protect:
* Time zone
* User names and real name
* Name+version of any client (e.g. IRC leaks name+version through CTCP)
* Metadata in files (e.g., exif data in images, author name in PDFs)
* License keys of non-free software
### Further Reading
* [Information on protocol leaks](https://trac.torproject.org/projects/tor/wiki/doc/TorifyHOWTO#Protocolleaks)
* [Official Tor Usage Warning](https://www.torproject.org/download/download-easy.html.en#warning)
* [Tor Browser Design](https://www.torproject.org/projects/torbrowser/design/)
## How to use Tor Browser behind TorVM
1. In a clean VM, [download Tor Browser from the Tor Project][tor-browser].
2. [Verify the PGP signature][tor-verify-sig].
3. Copy/move the Tor Browser archive into your AnonVM (i.e., the AppVM which has your TorVM as its netvm).
4. Unpack the Tor Browser archive into your home directory.
5. In dom0, right click the KDE Application Launcher Menu (AKA "Start Menu") and left click "Edit Applications..."
6. In the KDE Menu Editor, find your AnonVM's group and create a new item (or make a copy of an existing item).
7. Edit the following fields on the "General" tab:
* Name: `my-new-anonvm: Tor Browser`
* Command: `qvm-run -q --tray -a my-new-anonvm 'TOR_SKIP_LAUNCH=1 TOR_SKIP_CONTROLPORTTEST=1 TOR_SOCKS_PORT=9050 TOR_SOCKS_HOST=1.2.3.4 ./tor-browser_en-US/Browser/start-tor-browser'`
* Replace `my-new-anonvm` with the name of your AnonVM.
* Replace `1.2.3.4` with your TorVM's internal Qubes IP address, which can be viewed in Qubes VM Manager by clicking "View" --> "IP" or by running `qvm-ls -n` in dom0.
* Replace `en-US` with your locale ID, if different.
8. Click "Save" in the KDE Menu Editor.
Tor Browser should now work correctly in your AnonVM when launched via the shortcut you just created.
**Note:** If you want to use Tor Browser in a [DispVM][dispvm], the steps are the same as above, except you should copy the Tor Browser directory into your DVM template, [regenerate the DVM template][dispvm-customization], then use the following command in your KDE menu entry:
`sh -c 'echo TOR_SKIP_LAUNCH=1 TOR_SKIP_CONTROLPORTTEST=1 TOR_SOCKS_PORT=9050 TOR_SOCKS_HOST=1.2.3.4 ./tor-browser_en-US/Browser/start-tor-browser | /usr/lib/qubes/qfile-daemon-dvm qubes.VMShell dom0 DEFAULT red'`
(Replace `1.2.3.4` and `en-US` as indicated above.)
## Performance
In order to mitigate identity correlation TorVM makes use of Tor's new [stream
isolation feature][stream-isolation]. Read "Threat Model" below for more
information.
However, this isn't desirable in all situations, particularly web browsing.
These days loading a single web page requires fetching resources (images,
javascript, css) from a dozen or more remote sources. Moreover, the use of
IsolateDestAddr in a modern web browser may create very uncommon HTTP behavior
patterns, that could ease fingerprinting.
Additionally, you might have some apps that you want to ensure always share a
Tor circuit or always get their own.
For these reasons TorVM ships with two open SOCKS5 ports that provide Tor
access with different stream isolation settings:
* Port 9050 - Isolates by SOCKS Auth and client address only
Each AppVM gets its own circuit, and each app using a unique SOCKS
user/pass gets its own circuit
* Port 9049 - Isolates client + destination port, address, and by SOCKS Auth
Same as default settings listed above, but additionally traffic
is isolated based on destination port and destination address.
## Custom Tor Configuration
Default tor settings are found in the following file and are the same across
all TorVMs.
/usr/lib/qubes-tor/torrc
You can override these settings in your TorVM, or provide your own custom
settings by appending them to:
/rw/config/qubes-tor/torrc
For information on tor configuration settings `man tor`
Threat Model
============
TorVM assumes the same Adversary Model as [TorBrowser][tor-threats], but does
not, by itself, have the same security and privacy requirements.
## Proxy Obedience
The primary security requirement of TorVM is *Proxy Obedience*.
Client AppVMs MUST NOT bypass the Tor network and access the local physical
network, internal Qubes network, or the external physical network.
Proxy Obedience is assured through the following:
1. All TCP traffic from client VMs is routed through Tor
2. All DNS traffic from client VMs is routed through Tor
3. All non-DNS UDP traffic from client VMs is dropped
4. Reliance on the [Qubes OS network model][qubes-net] to enforce isolation
## Mitigate Identity Correlation
TorVM SHOULD prevent identity correlation among network services.
Without stream isolation, all traffic from different activities or "identities"
in different applications (e.g., web browser, IRC, email) end up being routed
through the same tor circuit. An adversary could correlate this activity to a
single pseudonym.
TorVM uses the default stream isolation settings for transparently torified
traffic. While more paranoid options are available, they are not enabled by
default because they decrease performance and in most cases don't help
anonymity (see [this tor-talk thread][stream-isolation-explained])
By default TorVM does not use the most paranoid stream isolation settings for
transparently torified traffic due to performance concerns. By default TorVM
ensures that each AppVM will use a separate tor circuit (`IsolateClientAddr`).
For more paranoid use cases the SOCKS proxy port 9049 is provided that has all
stream isolation options enabled. User applications will require manual
configuration to use this socks port.
Future Work
===========
* Integrate Vidalia
* Create Tor Browser packages w/out bundled tor
* Use local DNS cache to speedup queries (pdnsd)
* Support arbitrary [DNS queries][dns]
* Fix Tor's openssl complaint
* Support custom firewall rules (to support running a relay)
Acknowledgements
================
Qubes TorVM is inspired by much of the previous work done in this area of
transparent torified solutions. Notably the following:
* [Patrick Schleizer](mailto:adrelanos@riseup.net) for his work on [Whonix](https://www.whonix.org)
* The [Tor Project wiki](https://trac.torproject.org/projects/tor/wiki/doc/TorifyHOWTO)
* And the many people who contributed to discussions on [tor-talk](https://lists.torproject.org/pipermail/tor-talk/)
[stream-isolation]: https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/171-separate-streams.txt
[stream-isolation-explained]: https://lists.torproject.org/pipermail/tor-talk/2012-May/024403.html
[tor-threats]: https://www.torproject.org/projects/torbrowser/design/#adversary
[qubes-net]: /doc/QubesNet/
[dns]: https://tails.boum.org/todo/support_arbitrary_dns_queries/
[tor-browser]: https://www.torproject.org/download/download-easy.html
[tor-verify-sig]: https://www.torproject.org/docs/verifying-signatures.html
[dispvm]: /doc/DisposableVms/
[dispvm-customization]: /doc/UserDoc/DispVMCustomization/

58
privacy-guides/whonix.md Normal file
View File

@ -0,0 +1,58 @@
---
layout: doc
title: Whonix for Privacy & Anonymity
permalink: /doc/whonix/
redirect_from:
- /doc/privacy/whonix/
- /doc/templates/whonix/
- /en/doc/templates/whonix/
- /doc/Templates/Whonix/
- /wiki/Templates/Whonix/
- /doc/whonix/customize/
- /doc/privacy/customizing-whonix/
- /doc/whonix/install/
- /doc/privacy/install-whonix/
- /doc/whonix/uninstall/
- /doc/privacy/uninstall-whonix/
- /doc/whonix/update/
- /doc/privacy/updating-whonix/
---
Whonix for Privacy & Anonymity
==============================
To improve your privacy and anonymity on the internet, you can install the
Whonix Template on your Qubes machine.
[Whonix](https://www.whonix.org) is based on [Debian](https://www.debian.org)
and [Tor](https://www.torproject.org) and utilizes two VMs, a **"gateway"** and
a **"workstation"**. Qubes security architecture makes use of Whonix's isolation
by using the gateway as a ProxyVM to route all network traffic through Tor,
while the workstation is used for making AppVMs.
Whonix in Qubes replaces the deprecated [TorVM](/doc/torvm) service used in earlier
versions of Qubes.
*The following pages are written by the Whonix developers and are located on their website.*
## Getting Started with Whonix
Note: To install Whonix in Qubes, you must [install Qubes](/doc/installation-guide/) first.
* [Installing Whonix in Qubes](https://www.whonix.org/wiki/Qubes/Install)
* [Updating Whonix in Qubes](https://www.whonix.org/wiki/Qubes/Update)
* [Uninstalling Whonix from Qubes](https://www.whonix.org/wiki/Qubes/Uninstall)
## Configuring Whonix
* [Using Whonix with DisposableVMs](https://www.whonix.org/wiki/Qubes/Disposable_VM)
* [Post-Installation Security Advice](https://www.whonix.org/wiki/Post_Install_Advice)
* [How to set up Tor Bridges in Whonix on Qubes](https://www.whonix.org/wiki/Bridges)
* [Using Multiple Whonix-Workstations with Whonix on Qubes](https://www.whonix.org/wiki/Multiple_Whonix-Workstations#Qubes-Whonix)
* [How to use Corridor (a Tor traffic whitelisting gateway) with Whonix](https://www.whonix.org/wiki/Corridor)
## Support for Whonix
* [Whonix Support](https://www.whonix.org/wiki/Support) - General Whonix, Debian, Tor, etc... related issues
* [Whonix Qubes Forum](https://forums.whonix.org/c/qubes) - Whonix specific issues

72
security-guides/device-handling-security.md Normal file
View File

@ -0,0 +1,72 @@
---
layout: doc
title: Device Handling Security
permalink: /doc/device-handling-security/
---
# Device Handling Security #
Any additional ability a VM gains is additional attack surface. It's a good idea to always attach the minimum entity required in a VM.
For example, attaching a full USB-device offers [more attack surface than attaching a single block device][USB security], while
attaching a full block device (e.g. `sda`) again offers more attack surface than attaching a single partition (e.g. `sda1`), since the targetVM doesn't have to parse the partition-table.
(Attaching a full block device offers the advantage that most file-managers will mount and display them correctly, whereas they don't expect single partitions to be added and therefore don't handle them correctly.)
## PCI Security ##
Attaching a PCI device to a qube has serious security implications. It exposes the device driver running in the qube to an external device (and sourceVM, which contains the device - e.g. `sys-usb`). In many cases a malicious device can choose what driver will be loaded (for example by manipulating device metadata like vendor and product identifiers) - even if the intended driver is sufficiently secure, the device may try to attack a different, less secure driver.
Furthermore that VM has full control of the device and may be able to exploit bugs or malicious implementation of the hardware, as well as plain security problems the hardware may pose. (For example, if you attach a USB controller, all the security implications of USB passthrough apply as well.)
By default, Qubes requires any PCI device to be resettable from the outside (i.e. via the hypervisor), which completely reinitialises the device. This ensures that any device that was attached to a compromised VM, even if that VM was able to use bugs in the PCI device to inject malicious code, can be trusted again. (Or at least as trusted as it was when Qubes booted.)
Some devices do not implement a reset option. In these cases, Qubes by default does not allow attaching the device to any VM. If you decide to override this precaution, beware that the device may only be trusted when attached to the first VM. Afterwards, it should be **considered tainted** until the whole system is shut down. Even without malicious intent, usage data may be leaked.
In case device reset is disabled for any reason, detaching the device should be considered a risk. Ideally, devices for which the `no-strict-reset` option is set are attached once to a VM which isn't shut down until the system is shut down.
Additionally, Qubes restricts the config-space a VM may use to communicate with a PCI device. Only whitelisted registers are accessible. However, some devices or applications require full PCI access. In these cases, the whole config-space may be allowed. you're potentially weakening the device isolation, especially if your system is not equipped with a VT-d Interrupt Remapping unit. This increases the VM's ability to run a [side channel attack] and vulnerability to the same.
See [Xen PCI Passthrough: PV guests and PCI quirks] and [Software Attacks on Intel VT-d] \(page 7) for more details.
## USB Security ##
The connection of an untrusted USB device to dom0 is a security risk since the device can attack an arbitrary USB driver (which are included in the linux kernel), exploit bugs during partition-table-parsing or simply pretend to be a keyboard. There are many ready-to-use implementations of such attacks, e.g. a [USB Rubber Ducky][rubber duck].
The whole USB stack is put to work to parse the data presented by the USB device in order to determine if it is a USB mass storage device, to read its configuration, etc.
This happens even if the drive is then assigned and mounted in another qube.
To avoid this risk, use a [USB qube].
Attaching a USB device to a VM (USB passthrough) will **expose your target qube** to most of the [security issues][USB security] associated with the USB-stack.
If possible, use a method specific for particular device type (for example, block devices described above), instead of this generic one.
## Security Warning On USB Input Devices
If you connect USB input devices (keyboard and mouse) to a VM, that VM will effectively have control over your system.
Because of this, the benefits of using a [USB qube] entrusted with a keyboard or other interface device are much smaller than using a fully untrusted USB qube.
In addition to having control over your system, such a VM can also sniff all the input you enter there (for example, passwords in the case of a USB keyboard).
There is no simple way to protect against sniffing, but you can make it harder to exploit control over input devices.
If you have only a USB mouse connected to a USB qube, but the keyboard is connected directly to dom0 (using a PS/2 connector, for example), you simply need to lock the screen when you are away from your computer.
You must do this every time you leave your computer unattended, even if there no risk of anyone else having direct physical access to your computer.
This is because you are guarding the system not only against anyone with local access, but also against possible actions from a potentially compromised USB qube.
If your keyboard is also connected to a USB qube, things are much harder.
Locking the screen (with a traditional password) does not solve the problem, because the USB qube can simply sniff this password and later easily unlock the screen.
One possibility is to set up the screen locker to require an additional step to unlock (i.e., two-factor authentication).
One way to achieve this is to use a [YubiKey], or some other hardware token, or even to manually enter a one-time password.
Support for [two factor authentication][qubes u2f proxy] was recently added, though there are [issues][4661].
[USB security]:https://blog.invisiblethings.org/2011/05/31/usb-security-challenges.html "ITL blog post on USB security"
[rubber duck]: https://shop.hak5.org/products/usb-rubber-ducky-deluxe
[USB qube]: /doc/usb-qubes/
[YubiKey]: /doc/YubiKey/
[qubes u2f proxy]: https://www.qubes-os.org/news/2018/09/11/qubes-u2f-proxy/
[4661]: https://github.com/QubesOS/qubes-issues/issues/4661
[side channel attack]: https://en.wikipedia.org/wiki/Side-channel_attack
[Xen PCI Passthrough: PV guests and PCI quirks]: https://wiki.xenproject.org/wiki/Xen_PCI_Passthrough#PV_guests_and_PCI_quirks
[Software Attacks on Intel VT-d]: https://invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf

186
security-guides/multifactor-authentication.md Normal file
View File

@ -0,0 +1,186 @@
---
layout: doc
title: Multifactor Authentication
permalink: /doc/multifactor-authentication/
redirect_from:
- /en/doc/multifactor-authentication/
- /doc/Multi-factorAuthentication/
---
Using Multi-factor Authentication with Qubes
============================================
(Note: This page concerns multi-factor authentication for logging into external
services, not for logging into Qubes itself. For the latter, see
[here][YubiKey].)
[Multi-factor authentication (MFA)][MFA] today most commonly takes the form of a
numerical code generated by a smartphone app or sent via SMS (text message)
which the user must enter in addition to a password in order to log in to a
website or other service.
One of the primary features of Qubes is that it allows us to create securely
isolated VMs which can run arbitrary programs. (These VMs are securely isolated
not only from each other but also, optionally, from the network.) This means
that we can create a dedicated, network-isolated VM to function as a secure
authenticator.
This guide will show you how to set up a VM which uses [oathtool][], an
open-source one-time password tool, to generate authentication codes. This
method presents several benefits over relying on a consumer smartphone app or
SMS:
* `oathtool` includes the [time-based one-time password (TOTP)][TOTP]
algorithm, which is the same algorithm used by [Google Authenticator][], one
of the most commonly used authenticator apps. This means that we can use
`oathtool` as a complete open-source replacement for Google Authenticator
(which became propriety (closed-source) in May 2013 after version 2.21).
* By keeping all of our authenticator data as plain text files in a dedicated
VM, we have complete control over the secret keys used to generate our
authentication tokens, and we can back up, copy, and transfer our
authenticator data at will.
* By creating a minimal environment in which to run `oathtool` from the command
line, we can minimize our attack surface relative to most smartphone apps and
SMS. Consumer smartphones are typically internet-facing devices which are
increasingly targeted by malware. Most smartphones are bundled with
proprietary software which allows service providers almost complete control
over the device. Likewise, consumer SMS messages are often cleartext
communications which can feasibly be intercepted and read by third parties.
(In cases in which SMS messages are encrypted on the network by the service
provider, the service provider itself still has full access, which means that
the contents of such messages could be read by unscrupulous admins or turned
over to government agencies.)
* Using `oathtool` in a dedicated, network-isolated Qubes VM allows us to
achieve a unique combination of security and convenience. The strong isolation
Qubes provides allows us to reap the full security benefits of MFA, while
virtualization frees us from having to worry about finding and handling a
second physical device.
Optional Preparation Steps
--------------------------
1. Start with a minimal template. In this example, we'll use the
[minimal Fedora template][FedoraMinimal]. Get it if you haven't already done
so:
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-fedora-26-minimal
2. Since we'll be making some modifications, you may want to clone the minimal
template:
[user@dom0 ~]$ qvm-clone fedora-26-minimal fedora-26-min-mfa
3. Since this is going to be a minimal environment in which we run `oathtool`
from the command line, we'll install only a couple of packages:
[user@fedora-26-min-mfa ~]$ su -
[user@fedora-26-min-mfa ~]# dnf install oathtool vim-minimal
[user@fedora-26-min-mfa ~]$ poweroff
4. Create an AppVM and set it to use the TemplateVM we just created:
[user@dom0 ~]$ qvm-create -l black mfa
[user@dom0 ~]$ qvm-prefs -s mfa template fedora-26-min-mfa
5. Isolate the new AppVM from the network:
[user@dom0 ~]$ qvm-prefs -s mfa netvm none
Using the MFA AppVM
-------------------
Now that we have an AppVM set up to use `oathtool` securely, let's use it with
an external service. This process will vary slightly from service to service but
is largely the same.
1. Proceed with setting up multi-factor authentication as you normally would.
If you are prompted to scan a QR code, instead select the option (if
available) to view the secret key as text:
![Secret Key Example 0](/attachment/wiki/Multi-factorAuthentication/secret-key-example-0.png)
You should then see the secret key as text:
![Secret Key Example 1](/attachment/wiki/Multi-factorAuthentication/secret-key-example-1.png)
Note that the length and format of the secret key may vary by service:
![Secret Key Example 2](/attachment/wiki/Multi-factorAuthentication/secret-key-example-2.png)
2. In your MFA AppVM, you can now use `oathtool` to generate base32 TOTP
authentication tokens just like Google Authenticator would. In this example,
we'll use the secret key `xd2n mx5t ekg6 h6bi u74d 745k n4m7 zy3x` from the
second image above (substitute your own):
[user@mfa ~]$ oathtool --base32 --totp "xd2n mx5t ekg6 h6bi u74d 745k n4m7 zy3x"
279365
The output is `279365`. This is what you would enter when prompted for an
authenticator code. (Note that this is a *time*-based one-time password,
which means that your VM's clock must be sufficiently accurate in order to
generate a valid token. Qubes handles VM time syncing automatically, so you
normally shouldn't have to worry about this. As usual, the token will change
after a short period of time.)
3. To make this easier on ourselves in the future, we can create a simple shell
script for each service we use. (The example service here is a Google
account, using the example key from above. You'll get a unique secret key
from each service.) Create the script like so:
[user@mfa ~]$ > google
[user@mfa ~]$ vi google
#!/bin/bash
##My Google Account
##me@gmail.com
oathtool --base32 --totp "xd2n mx5t ekg6 h6bi u74d 745k n4m7 zy3x"
[user@mfa ~]$ chmod +x google
Since the secret key stored in the script never changes, we should never
have to update this script, but we can easily do so if we ever want to.
4. Now, whenever Google prompts us for an authenticator code, all we have to do
is this:
[user@mfa ~]$ ./google
640916
Done!
5. Now you can create scripts for any other TOTP-supporting services you use,
and enjoy the security and ease of quickly generating authentication tokens
right from your Qubes VM command-line:
[user@mfa ~]$ ./github
495272
[user@mfa ~]$ ./aws
396732
[user@mfa ~]$ ./facebook
851956
[user@mfa ~]$ ./dropbox
294106
[user@mfa ~]$ ./microsoft
295592
[user@mfa ~]$ ./slack
501731
[user@mfa ~]$ ./wordpress
914625
[user@mfa ~]$ ./tumblr
701463
For a more complete list of compatible services, see [here][usage].
[YubiKey]: /doc/YubiKey/
[MFA]: https://en.wikipedia.org/wiki/Multi-factor_authentication
[oathtool]: http://www.nongnu.org/oath-toolkit/man-oathtool.html
[TOTP]: https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm
[Google Authenticator]: https://en.wikipedia.org/wiki/Google_Authenticator
[FedoraMinimal]: /doc/Templates/FedoraMinimal/
[usage]: https://en.wikipedia.org/wiki/Google_Authenticator#Usage

166
security-guides/security-guidelines.md Normal file
View File

@ -0,0 +1,166 @@
---
layout: doc
title: Security Guidelines
permalink: /doc/security-guidelines/
redirect_from:
- /en/doc/security-guidelines/
- /doc/SecurityGuidelines/
- /wiki/SecurityGuidelines/
---
Security Guidelines
===================
Without some active and responsible participation of the user, no real security is possible. Running Firefox inside of an AppVM does not automagically make it (or any other app) more secure.
Programs themselves remain just as secure [(or insecure)](https://en.wikipedia.org/wiki/Computer_insecurity) on Qubes as on a normal Linux or Windows OS.
What drastically changes is the context in which your applications are used.
[This context](/doc/qubes-architecture/) is a [responsibility of the user](/security/goals/).
But managing security in this context well requires knowledge of some new concepts and procedures. So it is worth stressing some basic items:
Download Verification
---------------------
**Verify the authenticity and integrity of your downloads, [particularly the Qubes iso](/security/verifying-signatures/).**
The internet is always a dangerous place.
While your connection to the Qubes website and download mirrors is encrypted, meaning that your downloads from here can't be modified by a third party en route, there is always the chance that these websites themselves have been compromised.
Signature verification allows us to validate for ourselves that these files were the ones authored and signed by their creators (in this case the Qubes development team).
Because it's so easy for a hacker who manages to tamper with the downloaded iso files this way to patch in malware, it is of the utmost importance that you **verify the signature of the Qubes iso** you use to install Qubes.
See the page on [Verifying Signatures](/security/verifying-signatures/) for more information and a tutorial on how to accomplish this.
Once you have Qubes installed, the standard program installation command for Fedora and Qubes repositories
~~~
sudo dnf install <program>
~~~
automatically accomplishes this verification.
Custom user-added repositories might come with gpgcheck disabled. [Check the config files](https://docs.fedoraproject.org/en-US/Fedora/12/html/Deployment_Guide/sec-Configuring_Yum_and_Yum_Repositories.html) and verify that
~~~
gpgcheck=1
~~~
Plus, make sure you also **safely import their signing keys**. This may require you to check from multiple sources that the signing key is always the same.
Even then, you might want to consider new repositories to be **less** secure and not use them in templates that feed your more trusted VMs.
If you **need** to download programs that cannot be verified, then it is much less dangerous to install them in a **cloned template or a standalone VM**.
Remember: Qubes cannot automatically verify the signature of files that come from other sources like your browser, torrenting client, or home-made tofu recipe downloader. If the providers of these downloads provide keys for you to verify the signatures of their downloads, do it!
Observing Security Contexts
---------------------------
Each VM is assigned a specific colour for its window borders. These borders are how Qubes displays the **security context** of applications and data so that users can be easily aware of this at all times. Be sure to check the colour of window borders before taking any action, particularly if it affects the security of your system. [See this blog post for more information](https://blog.invisiblethings.org/2011/05/21/app-oriented-ui-model-and-its-security.html).
Always remember that any "red" window can draw "green" password prompts.
Don't let yourself be tricked into entering credentials designated to one qube into a forged input box rendered by another.
For XFCE users (which is the default desktop environment on QubesOS) it would be wise to manually move the more trusted window so that it is not displayed on top of a less trusted one, but rather over the trusted Dom0 wallpaper.
If you use KDE, it has a helpful feature called **Expose-like effect** that is activated in System Tools -\> System Settings -\> Desktop Effects -\> All Effects -\> Desktop Grid Present Windows.
Performing these steps makes it easier to tell the difference between when you're being phished and when you're genuinely being asked for credentials.
Installing Versus Running Programs
----------------------------------
With the exception of a text editor used to modify configuration files, one should not run applications in either template VMs or in Dom0. From a security standpoint there is a great difference between installing a program and running it.
Enabling and Verifying VT-d/IOMMU
---------------------------------
In **Dom0** terminal, run:
~~~
qubes-hcl-report <userVM>
~~~
where \<userVM\> is the name of the VM within which the report will be written (but the report will also be displayed in the Dom0 terminal). If it displays that VT-d is active, you should be able to assign **PCIe devices to an HVM** and **enjoy DMA protection** for your driver domains, so you successfully passed this step.
If VT-d is not active, attempt to activate it by selecting the **VT-d flag** within the BIOS settings. If your processor/BIOS does not allow VT-d activation you still enjoy much better security than alternative systems, but you may be vulnerable to **DMA attacks**. Next time you buy a computer consult our **[HCL (Hardware Compatibility List)](/hcl/)** and possibly contribute to it.
Updating Software
-----------------
To keep your system regularly updated against security related bugs and get new features, run in Dom0:
~~~
sudo qubes-dom0-update
~~~
and run in templates and standalone VM
~~~
sudo dnf update
~~~
or use the equivalent items in Qubes Manager, which displays an icon when an update is available.
Handling Untrusted Files
------------------------
When you receive or download any file from an **untrusted source**, do not browse to it with a file manager which has preview enabled. Enabling previews in your file manager gives malware another attack vector. **To disable preview in Nautilus**: Gear (up-right-icon) -\> Preferences -\> Preview (tab) -\> Show thumbnails: Never. Note that this change can be made in a TemplateVM (including the [DispVM template](/doc/dispvm-customization/)) so that future AppVMs created from this TemplateVM will inherit this feature.
Also, **do not open it in trusted VMs**. Rather, open it in a **disposable VM** right-clicking on it. You may even modify it within the disposable VM and then [copy it to other VM](/doc/copying-files/).
Alternatively PDFs may be converted to **trusted PDFs** by right clicking on them. This converts the PDF's text to graphic form, so the disk size these documents take up will increase.
Anti Evil Maid
--------------
If there is a risk that somebody may gain **physical access** to your computer when you leave it powered down, or if you use Qubes in **dual boot mode**, then you may want to [install AEM](/doc/anti-evil-maid/) (Anti Evil Maid). AEM will inform you of any unauthorized modifications to your BIOS or boot partition. If AEM alerts you of an attack, it is really bad news because **there is no true fix**. If you are really serious about security, you will have to buy a new laptop and install Qubes from a trusted ISO. Buying a used laptop runs a higher risk of tampering and is not an option for a security focused environment.
Reassigning USB Controllers
---------------------------
Before you [assign a USB controller to a VM](/doc/assigning-devices/), check if any **input devices** are included in that controller.
Assigning a USB keyboard will **deprive Dom0 VM of a keyboard**. Since a USB controller assignment survives reboot, you may find yourself **unable to access your system**. Most non-Apple laptops have a PS/2 input for keyboard and mouse, so this problem does not exist.
But **if you need to use a USB keyboard or mouse**, identify the USB controller in which you have your keyboard/mouse plugged in and do NOT assign it to a VM. Also, makes sure you know all the other USB ports for that controller, and use them carefully, knowing **you are exposing Dom0** (ie NO bluetooth device on it).
All USB devices should be assumed **side channel attack vectors** (mic via sound, others via power usage), so you might prefer to remove them. [See this about rootkits](https://web.archive.org/web/20070829112704/http://www.networkworld.com/news/2007/080207-black-hat-virtual-machine-rootkit-detection.html)
Using a **web-cam** also involves a risk, so better to physically cover it with adhesive tape or disconnect it if you do not use it. If you need it, you need **to assign it to a VM** and cover it with a cap or an elastic band when not in use. Attaching a **microphone** using Qubes VM Manager may also be risky, so attach it only when required.
It is preferable to avoid using **Bluetooth** if you travel or do not trust your neighbours. Kids with high-gain directional antennas might also gain long range access to your Bluetooth. In this case, buy a computer that does not have a Bluetooth hardware module, or, if you have it, assign it to an untrusted VM. Assigning it to its own Qube will also allow you to use Bluetooth without trusting it, if need be.
Many laptops allow one to disable various hardware (Camera, BT, Mic, etc) **in BIOS**. This might or might not be a dependable way of getting rid of those devices, depending on how much you trust your BIOS vendor.
If the VM will not start after you have assigned a USB controller, look at [this FAQ](/faq/#i-created-a-usbvm-and-assigned-usb-controllers-to-it-now-the-usbvm-wont-boot).
Creating and Using a USBVM
--------------------------
See [here](/doc/usb/).
Dom0 Precautions
----------------
As explained [here](/getting-started/#appvms-qubes-and-templatevms), dom0 should not be used for any user operations. There are several reasons for this:
1. Secure isolation among domUs (i.e., AppVMs, StandaloneVMs, HVMs, etc.) is the *raison d'être* of Qubes. This is the primary reason that we recommend the delegation of all user activities to some number of AppVMs. In the event that any given VM is compromised, only that particular VM is compromised. (TemplateVMs are the exception to this. If a TemplateVM were compromised, then every AppVM based on it might also be compromised. Even in this case, however, the entire system would not necessarily have been compromised, since StandaloneVM(s), HVM(s), and/or multiple TemplateVMs might be in use.) By contrast, if dom0 were ever compromised, the entire system would thereby be compromised.
2. Due to the absence of convenience mechanisms in dom0 such as the inter-VM clipboard and inter-VM file copying, it is significantly less convenient to attempt to use dom0 for user operations (e.g., password management) in conjunction with AppVMs than it is to use another dedicated AppVM (e.g., a "vault" VM).
3. Dom0 has access to every VM's data in the form of its private image file, including untrusted (e.g., red-bordered) VMs. If the user were to make a mistake (or be tricked into making one) and thereby inadvertently access untrusted files from dom0, those files could exploit the application which accessed them (e.g., a file manager) and gain control over dom0 and, therefore, the entire system. Even simply displaying the data in a [terminal emulator](http://securityvulns.com/docs4128.html) can be dangerous. For example, some file managers (such as the Thunar File Manager, which is pre-installed by default in the Xfce4 version of dom0) list loop devices used by running VMs. When one of these devices is selected in the file manager, the loop device is mounted to dom0, effectively [transferring the contents](https://groups.google.com/d/msg/qubes-users/_tkjmBa9m9w/9BbKh94PVtcJ) of the home directory of a (by definition less trusted) AppVM to dom0.
4. There is a (hopefully small, but always non-zero) chance that any given program is malicious. Even packages by third-party developers you trust might have been modified and then signed by an attacker who managed to get that developer's private key(s). For this reason, it is very important that as few programs as possible be run in dom0 in as restricted a manner as possible. For example, although GnuPG is used in dom0 for verifying updates received from the firewallvm, it does not follow that GnuPG should be used for regular user operations (e.g., key management) in dom0. This is because only a single GnuPG operation, the "verify signature" operation (which is believed to be the most bulletproof operation in GnuPG), is used by default in dom0. No other key management operations (e.g., importing unverified keys) or any other data parsing takes place in dom0 by default.
5. Any VM can be shut down in order to make it even more difficult for an adversary to access, and shutting down one VM does not restrict the user of other VMs. By contrast, one cannot shut down dom0 and use other VMs at the same time.
6. As far as we are aware, there are no special mechanisms in Xen which make dom0 more protected than any other VM, so there is no inherent security advantage to performing any user operations in dom0.
TemplateBasedVM Directories
---------------------------
* Once a TemplateBasedVM has been created, any changes in its `/home`,
`/usr/local`, or `/rw/config` directories will be persistent across reboots,
which means that any files stored there will still be available after
restarting the TemplateBasedVM. No changes in any other directories in
TemplateBasedVMs persist in this manner. If you would like to make changes
in other directories which *do* persist in this manner, you must make those
changes in the parent TemplateVM.
* See [here](/doc/templates) for more detail and version specific information.

52
security-guides/split-bitcoin.md Normal file
View File

@ -0,0 +1,52 @@
---
layout: doc
title: Split Bitcoin
permalink: /doc/split-bitcoin/
---
How to Set Up a Split Bitcoin Wallet in Qubes
=============================================
What is a "Split" Bitcoin Wallet?
---------------------------------
A "split" bitcoin wallet is a strategy of protecting your bitcoin by having your wallet split into an offline "[cold storage](https://en.bitcoin.it/wiki/Cold_storage)" wallet and an online "watching only" wallet.
A "Watching" Wallet and a "Cold" Wallet
---------------------------------------
1. Create a fedora-25-electrum template using the Qubes VM Manager or running
`qvm-clone fedora-25 fedora-25-electrum` in dom0.
2. Start the new template:
`qvm-start fedora-25-electrum`
`qvm-run fedora-25-electrum xterm`
3. Install `electrum` to fedora-25-electrum template VM. From fedora-25-electrum terminal enter:
`sudo dnf update`.
`sudo dnf install electrum`.
4. Shut down your `fedora-25-electrum` template
5. Create an `offline-bitcoin` qube based on `fedora-25-electrum` using the Qubes VM Manager or running `qvm-create -t fedora-25-electrum -l black offline-bitcoin` and `qvm-prefs -s offline-bitcoin netvm none` in dom0.
6. Follow the [electrum documentation in creating an offline wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-an-offline-wallet)
7. Create a `watching-bitcoin` qubes based on `fedora-25-electrum` connecting to the internet how ever you prefer using the Qubes VM Manager or running for example `qvm-create -t fedora-25-electrum -l green watching-bitcoin` and `qvm-prefs -s watching-bitcoin netvm sys-whonix` in dom0.
8. Follow the [electrum documentation in creating an online watching-only wallet](http://docs.electrum.org/en/latest/coldstorage.html#create-a-watching-only-version-of-your-wallet)
Important Notes
---------------
* The private keys (xpriv) should never be moved outside of `offline-bitcoin`.
* For copying out the public keys (xpub), Qubes provides two secure, convenient
methods: the [inter-VM clipboard] and [inter-VM file copy] tools. Compared to
traditional physically air-gapped machines, these tools make it very easy to
copy out public keys.
[inter-VM clipboard]: /doc/copy-paste/
[inter-VM file copy]: /doc/copying-files/

160
security-guides/vm-sudo.md Normal file
View File

@ -0,0 +1,160 @@
---
layout: doc
title: VM Sudo
permalink: /doc/vm-sudo/
redirect_from:
- /en/doc/vm-sudo/
- /doc/VMSudo/
- /wiki/VMSudo/
---
Password-less root access in VM
===============================
Background ([/etc/sudoers.d/qubes](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/misc/qubes.sudoers) in VM):
user ALL=(ALL) NOPASSWD: ALL
# WTF?! Have you lost your mind?!
#
# In Qubes VMs there is no point in isolating the root account from
# the user account. This is because all the user data is already
# accessible from the user account, so there is no direct benefit for
# the attacker if she could escalate to root (there is even no benefit
# in trying to install some persistent rootkits, as the VM's root
# filesystem modifications are lost upon each start of a VM).
#
# One might argue that some hypothetical attacks against the
# hypervisor or the few daemons/backends in Dom0 (so VM escape
# attacks) most likely would require root access in the VM to trigger
# the attack.
#
# That's true, but mere existence of such a bug in the hypervisor or
# Dom0 that could be exploited by a malicious VM, no matter whether
# requiring user, root, or even kernel access in the VM, would be
# FATAL. In such situation (if there was such a bug in Xen) there
# really is no comforting that: "oh, but the mitigating factor was
# that the attacker needed root in VM!" We're not M$, and we're not
# gonna BS our users that there are mitigating factors in that case,
# and for sure, root/user isolation is not a mitigating factor.
#
# Because, really, if somebody could find and exploit a bug in the Xen
# hypervisor -- as of 2016, there have been only three publicly disclosed
# exploitable bugs in the Xen hypervisor from a VM -- then it would be
# incidentally by one of the Qubes developers (RW) -- then it would be
# highly unlikely if that person couldn't also found a user-to-root
# escalation in VM (which as we know from history of UNIX/Linux
# happens all the time).
#
# At the same time allowing for easy user-to-root escalation in a VM
# is simply convenient for users, especially for update installation.
#
# Currently this still doesn't work as expected, because some idotic
# piece of software called PolKit uses own set of policies. We're
# planning to address this in Beta 2. (Why PolKit is an idiocy? Do a
# simple experiment: start 'xinput test' in one xterm, running as
# user, then open some app that uses PolKit and asks for root
# password, e.g. gpk-update-viewer -- observe how all the keystrokes
# with root password you enter into the "secure" PolKit dialog box can
# be seen by the xinput program...)
#
# joanna.
Below is a complete list of configuration made according to the above statement, with (not necessary complete) list of mechanisms depending on each of them:
1. sudo (/etc/sudoers.d/qubes):
user ALL=(ALL) NOPASSWD: ALL
(...)
- easy user->root access (main option for the user)
- qvm-usb (not really working, as of R2)
2. PolicyKit (/etc/polkit-1/rules.d/00-qubes-allow-all.rules):
//allow any action, detailed reasoning in sudoers.d/qubes
polkit.addRule(function(action,subject) { return polkit.Result.YES; });
and /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla:
[Qubes allow all]
Identity=*
Action=*
ResultAny=yes
ResultInactive=yes
ResultActive=yes
- NetworkManager configuration from normal user (nm-applet)
- updates installation (gpk-update-viewer)
- user can use pkexec just like sudo Note: above is needed mostly because Qubes user GUI session isn't treated by PolicyKit/logind as "local" session because of the way in which X server and session is started. Perhaps we will address this issue in the future, but this is really low priority. Patches welcomed anyway.
3. Empty root password
- used for access to 'root' account from text console (xl console) - the only way to access the VM when GUI isn't working
- can be used for easy 'su -' from user to root
Replacing password-less root access with Dom0 user prompt
---------------------------------------------------------
While ITL supports the statement above, some Qubes users may wish to enable
user/root isolation in VMs anyway. We do not support it in any of our packages,
but of course nothing is preventing the user from modifying his or her own
system. A list of steps to do so is provided here **without any guarantee of
safety, accuracy, or completeness. Proceed at your own risk. Do not rely on
this for extra security.**
1. Adding Dom0 "VMAuth" service:
[root@dom0 /]# echo "/usr/bin/echo 1" >/etc/qubes-rpc/qubes.VMAuth
[root@dom0 /]# echo "\$anyvm dom0 ask,default_target=dom0" \
>/etc/qubes-rpc/policy/qubes.VMAuth
(Note: any VMs you would like still to have password-less root access (e.g. TemplateVMs) can be specified in the second file with "\<vmname\> dom0 allow")
2. Configuring Fedora TemplateVM to prompt Dom0 for any authorization request:
- In /etc/pam.d/system-auth, replace all lines beginning with "auth" with these lines:
auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
auth requisite pam_deny.so
auth required pam_permit.so
- Require authentication for sudo. Replace the first line of /etc/sudoers.d/qubes with:
user ALL=(ALL) ALL
- Disable PolKit's default-allow behavior:
[root@fedora-20-x64]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules
[root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
3. Configuring Debian/Whonix TemplateVM to prompt Dom0 for any authorization request:
- In /etc/pam.d/common-auth, replace all lines beginning with "auth" with these lines:
auth [success=1 default=ignore] pam_exec.so seteuid /usr/lib/qubes/qrexec-client-vm dom0 qubes.VMAuth /bin/grep -q ^1$
auth requisite pam_deny.so
auth required pam_permit.so
- Require authentication for sudo. Replace the first line of /etc/sudoers.d/qubes with:
user ALL=(ALL) ALL
- Disable PolKit's default-allow behavior:
[root@debian-8]# rm /etc/polkit-1/rules.d/00-qubes-allow-all.rules
[root@debian-8]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
- In /etc/pam.d/su.qubes, comment out this line near the bottom of the file:
auth sufficient pam_permit.so
- For Whonix, if prompts appear during boot, create /etc/sudoers.d/zz99 and add these lines:
ALL ALL=NOPASSWD: /usr/sbin/virt-what
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck restart
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck start
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck stop
ALL ALL=NOPASSWD: /usr/sbin/service whonixcheck status
Dom0 password-less root access
------------------------------
There is also password-less user->root access in dom0. As stated in comment in sudo configuration there (different one than VMs one), there is really no point in user/root isolation, because all the user data (and VM management interface) is already accessible from dom0 user level, so there is nothing more to get from dom0 root account.

177
security-guides/yubi-key.md Normal file
View File

@ -0,0 +1,177 @@
---
layout: doc
title: YubiKey in Qubes
permalink: /doc/yubi-key/
redirect_from:
- /en/doc/yubi-key/
- /doc/YubiKey/
---
Using YubiKey to Qubes authentication
=====================================
You can use YubiKey to enhance Qubes user authentication, for example to mitigate
risk of snooping the password. This can also slightly improve security when you have [USB keyboard](/doc/device-handling-security/#security-warning-on-usb-input-devices).
There (at least) two possible configurations: using OTP mode and using challenge-response mode.
OTP mode
--------
This can be configured using
[app-linux-yubikey](https://github.com/adubois/qubes-app-linux-yubikey)
package. This package does not support sharing the same key slot with other
applications (it will deny further authentications if you try).
Contrary to instruction there, currently there is no binary package in the Qubes
repository and you need to compile it yourself. This might change in the future.
Challenge-response mode
----------------------
In this mode, your YubiKey will generate a response based on the secret key, and
random challenge (instead of counter). This means that it isn't possible to
generate a response in advance even if someone gets access to your YubiKey. This
makes it reasonably safe to use the same YubiKey for other services (also in
challenge-response mode).
Same as in the OTP case, you will need to set up your YubiKey, choose a separate
password (other than your login password!) and apply the configuration.
To use this mode you need to:
1. Install yubikey personalization the packages in your TemplateVM on which your USB VM is based.
For Fedora.
sudo dnf install ykpers yubikey-personalization-gui
For Debian.
sudo apt-get install yubikey-personalization yubikey-personalization-gui
Shut down your TemplateVM. Then reboot your USB VM (so changes inside the TemplateVM take effect
in your TemplateBased USB VM or install the packages inside your USB VM if you would like to avoid
rebooting your USB VM.
2. Configure your YubiKey for challenge-response `HMAC-SHA1` mode, for example
[following this
tutorial](https://www.yubico.com/products/services-software/personalization-tools/challenge-response/).
On Debian, you can run the graphical user interface `yubikey-personalization-gui` from the command line.
- Choose `configuration slot 2`.
- It is recommended to enable `Require user input (button press)` but this is optional.
- Note: Different from the above video, use the following settings select
`HMAC-SHA1 mode`: `fixed 64 bit input`.
- We will refer the `Secret Key (20 bytes hex)` as `AESKEY`.
- It is recommended to keep a backup of your `AESKEY` in an offline VM used as vault.
- Consider to keep a backup of your `AESKEY` on paper and store it in a safe place.
- In case you have multiple YubiKeys for backup purposes (in case a yubikey gets lost, stolen or breaks) you can write the same settings into other YubiKeys.
3. Install [qubes-app-yubikey](https://github.com/QubesOS/qubes-app-yubikey) in dom0.
sudo qubes-dom0-update qubes-yubikey-dom0
4. Adjust USB VM name in case you are using something other than the default
`sys-usb` by editing `/etc/qubes/yk-keys/yk-vm` in dom0.
5. Paste your `AESKEY` from step 2 into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
6. Paste your hashed password (other than your standard Qubes password) into
`/etc/qubes/yk-keys/yk-login-pass-hashed.hex` in dom0.
You can calculate your hashed password using the following two commands.
First run the following command to store your password in a temporary variable `password`.
(This way your password will not leak to the terminal command history file.)
read password
Now run the following command to calculate your hashed password.
echo -n "$password" | openssl dgst -sha1
7. Edit `/etc/pam.d/login` in dom0. Add this line at the beginning:
auth include yubikey
8. Edit `/etc/pam.d/xscreensaver` (or appropriate file if you are using other
screen locker program) in dom0. Add this line at the beginning:
auth include yubikey
9. Edit `/etc/pam.d/lightdm` (or appropriate file if you are using other
display manager) in dom0. Add this line at the beginning:
auth include yubikey
### Usage
When you want to unlock your screen...
1) Plug YubiKey into USB slot.
2) Enter password associated with YubiKey.
3) Press Enter.
4) If you configured so, YubiKey will request confirmation by pressing button on it (it will blink).
When everything is ok, your screen will be unlocked.
In any case you can still use your login password, but do it in a secure location
where no one can snoop your password.
### Mandatory YubiKey Login
Edit `/etc/pam.d/yubikey` (or appropriate file if you are using other screen locker program)
and remove `default=ignore` so the line looks like this.
auth [success=done] pam_exec.so expose_authtok quiet /usr/bin/yk-auth
Locking the screen when YubiKey is removed
------------------------------------------
You can setup your system to automatically lock the screen when you unplug your
YubiKey. This will require creating a simple qrexec service which will expose
the ability to lock the screen to your USB VM, and then adding a udev hook to
actually call that service.
In dom0:
1. First configure the qrexec service. Create `/etc/qubes-rpc/custom.LockScreen`
with a simple command to lock the screen. In the case of xscreensaver (used in Xfce)
it would be:
DISPLAY=:0 xscreensaver-command -lock
2. Allow your USB VM to call that service. Assuming that it's named `sys-usb` it
would require creating `/etc/qubes-rpc/policy/custom.LockScreen` with:
sys-usb dom0 allow
In your USB VM:
3. Create udev hook. Store it in `/rw/config` to have it
persist across VM restarts. For example name the file
`/rw/config/yubikey.rules`. Add the following line:
ACTION=="remove", SUBSYSTEM=="usb", ENV{ID_SECURITY_TOKEN}=="1", RUN+="/usr/bin/qrexec-client-vm dom0 custom.LockScreen"
4. Ensure that the udev hook is placed in the right place after VM restart. Append to `/rw/config/rc.local`:
ln -s /rw/config/yubikey.rules /etc/udev/rules.d/
udevadm control --reload
5. Then make `/rw/config/rc.local` executable.
sudo chmod +x /rw/config/rc.local
6. For changes to take effect, you need to call this script manually for the first time.
sudo /rw/config/rc.local
If you use KDE, the command(s) in first step would be different:
# In the case of USB VM being autostarted, it will not have direct access to D-Bus
# session bus, so find its address manually:
kde_pid=`pidof kdeinit4`
export `cat /proc/$kde_pid/environ|grep -ao 'DBUS_SESSION_BUS_ADDRESS=[[:graph:]]*'`
qdbus org.freedesktop.ScreenSaver /ScreenSaver Lock

172
troubleshooting/install-nvidia-driver.md Normal file
View File

@ -0,0 +1,172 @@
---
layout: doc
title: How to Install an Nvidia Driver
permalink: /doc/install-nvidia-driver/
redirect_from:
- /en/doc/install-nvidia-driver/
- /doc/InstallNvidiaDriver/
- /wiki/InstallNvidiaDriver/
---
# Nvidia proprietary driver installation
You can use rpm packages from rpmfusion, or you can build the driver yourself.
## Word of Caution
Proprietary (NVIDIA/AMD) drivers are known to be sometimes highly problematic, or completely unsupported.
Radeon driver support is prebaked in the Qubes kernel (v4.4.14-11) but only versions 4000-9000 give or take.
Support for newer cards is limited until AMDGPU support in the 4.5+ kernel, which isn't released yet for Qubes.
Built in Intel graphics, Radeon graphics (between that 4000-9000 range), and perhaps some prebaked NVIDIA card support that I don't know about. Those are your best bet for great Qubes support.
If you do happen to get proprietary drivers working on your Qubes system (via installing them), please take the time to go to the
[Hardware Compatibility List (HCL)](/doc/hcl/#generating-and-submitting-new-reports )
Add your computer, graphics card, and installation steps you did to get everything working.
## RpmFusion packages
There are rpm packages with all necessary software on rpmfusion. The only package you have to compile is the kernel module (but there is a ready built src.rpm package).
### Download packages
You will need any Fedora 18 system to download and build packages. You can use Qubes AppVM for it, but it isn't necessary. To download packages from rpmfusion - add this repository to your yum configuration (instructions are on their website). Then download packages using yumdownloader:
~~~
yumdownloader --resolve xorg-x11-drv-nvidia
yumdownloader --source nvidia-kmod
~~~
### Build kernel package
You will need at least kernel-devel (matching your Qubes dom0 kernel), rpmbuild tool and kmodtool, and then you can use it to build the package:
~~~
yum install kernel-devel rpm-build kmodtool
rpmbuild --nodeps -D "kernels `uname -r`" --rebuild nvidia-kmod-260.19.36-1.fc13.3.src.rpm
~~~
In the above command, replace `uname -r` with kernel version from your Qubes dom0. If everything went right, you have now complete packages with nvidia drivers for the Qubes system. Transfer them to dom0 (e.g. using a USB stick) and install (using standard "yum install /path/to/file").
Then you need to disable nouveau (normally it is done by install scripts from nvidia package, but unfortunately it isn't compatible with Qubes...):
Edit /etc/default/grub:
~~~
GRUB_CMDLINE_LINUX="quiet rhgb nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off"
~~~
Regenerate grub configuration:
~~~
grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
Reboot.
## Manual installation
This process is quite complicated: First - download the source from nvidia.com site. Here "NVIDIA-Linux-x86\_64-260.19.44.run" is used. Copy it to dom0. Every next step is done in dom0.
See [this page](/doc/copy-to-dom0/) for instructions on how to transfer files to Dom0 (where there is normally no networking).
**WARNING**: Nvidia doesn't sign their files. To make it worse, you are forced to download them over a plaintext connection. This means there are virtually dozens of possibilities for somebody to modify this file and provide you with a malicious/backdoored file. You should realize that installing untrusted files into your Dom0 is a bad idea. Perhaps it might be a better idea to just get a new laptop with integrated Intel GPU? You have been warned.
### Userspace components
Install libraries, Xorg driver, configuration utilities. This can by done by nvidia-installer:
~~~
./NVIDIA-Linux-x86_64-260.19.44.run --ui=none --no-x-check --keep --no-nouveau-check --no-kernel-module
~~~
### Kernel module
You will need:
- nvidia kernel module sources (left from previous step)
- kernel-devel package installed
- gcc, make, etc
This installation must be done manually, because nvidia-installer refused to install it on Xen kernel. Firstly ensure that kernel-devel package installed all needed files. This should consist of:
- */usr/src/kernels/2.6.34.1-12.xenlinux.qubes.x86\_64*
- */lib/modules/2.6.34.1-12.xenlinux.qubes.x86\_64/build* symlinked to the above directory
- */usr/src/kernels/2.6.34.1-12.xenlinux.qubes.x86\_64/arch/x64/include/mach-xen* should be present (if not - take it from kernel sources)
If all the files are not there correct the errors manually. To build the kernel module, enter *NVIDIA-Linux-x86\_64-260.19.44/kernel* directory and execute:
~~~
make
IGNORE_XEN_PRESENCE=1 CC="gcc -DNV_VMAP_4_PRESENT -DNV_SIGNAL_STRUCT_RLIM" make -f Makefile.kbuild
mv /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/kernel/drivers/video/nvidia.ko /lib/modules/2.6.34.1-12.xenlinux.qubes.x86_64/extra/
~~~
Ignore any errors while inserting nvidia.ko (at the end of make phase).
### Disable nouveau:
~~~
cat /etc/modprobe.d/nouveau-disable.conf
# blacklist isn't enough...
install nouveau /bin/true
~~~
Add *rdblacklist=nouveau* option to /boot/grub/menu.lst (at the end of line containing *vmlinuz*).
### Configure Xorg
Finally, you should configure Xorg to use nvidia driver. You can use *nvidia-xconfig* or do it manually:
~~~
X -configure
mv /root/xorg.conf.new /etc/X11/xorg.conf
# replace Driver in Device section by "nvidia"
~~~
Reboot to verify all this works.
# 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.
## 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.

65
troubleshooting/intel-igfx-troubleshooting.md Normal file
View File

@ -0,0 +1,65 @@
---
layout: doc
title: Intel Integrated Graphics Troubleshooting
permalink: /doc/intel-igfx-troubleshooting/
---
# Intel Integrated Graphics Troubleshooting #
## Software Rendering or Video Lags
If you are experiencing this issue, you will see extremely slow graphics updates.
You will be able to watch the screen and elements paint slowly from top to bottom.
You can confirm this is the issue by looking for a line similar to the following in your `/var/log/Xorg.0.log` file:
[ 131.769] (EE) AIGLX: reverting to software rendering
Newer versions of the Linux kernel have renamed the `i915.preliminary_hw_support=1` option to `i915.alpha_support=1`, so if you needed this kernel option in the past you will have to rename it or add it to your configuration files (follow either GRUB2 or EFI, not both):
* GRUB2: `/etc/default/grub`, `GRUB_CMDLINE_LINUX` line and
Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`)
* EFI: `/boot/efi/EFI/qubes/xen.cfg`, `kernel=` line(s)
## IOMMU ##
Dom0 Kernels currently included in Qubes have issues related to VT-d (IOMMU) and some versions of the integrated Intel Graphics Chip.
Depending on the specific hardware / software combination the issues are quite wide ranging, from apparently harmless log errors, to VM window refresh issues, to complete screen corruption and crashes rendering the machine unusable with Qubes.
Such issues have been reported on at least the following machines:
* HP Elitebook 2540p
* Lenovo x201
* Lenovo x220
* Thinkpad T410
* Thinkpad T450s
Log errors only on :
* Librem 13v1
* Librem 15v2
The installer for Qubes 4.0 final has been updated to disable IOMMU for the integrated intel graphics by default.
However, users of 3.2 may experience issues on install or on kernel upgrades to versions higher than 3.18.x.
Disabling IOMMU for the integrated graphics chip is not a security issue, as the device currently lives in dom0 and is not passed to a VM.
This behaviour is planned to be changed as of Qubes 4.1, when passthrough capabilities will be required for the GUI domain <sup id="a1-1">[1](#f1)</sup>.
## Workaround for existing systems with VT-d enabled (grub / legacy mode) ##
Edit the startup parameters for Xen:
1. Open a terminal in dom0
2. Edit `/etc/default/grub` (e.g. `sudo nano /etc/default/grub`)
3. Add to the line `GRUB_CMDLINE_XEN_DEFAULT` the setting `iommu=no-igfx`, save and quit
4. Commit the change with`sudo grub2-mkconfig --output /boot/grub2/grub.cfg`
## Workaround for existing systems with VT-d enabled (UEFI) ##
Edit the startup parameters for Xen:
1. Open a terminal in dom0
2. Edit `/boot/efi/EFI/qubes/xen.cfg` (e.g. `sudo nano /boot/efi/EFI/qubes/xen.cfg`)
3. Add to the line `options` the setting `iommu=no-igfx`, save and quit
<b name="f1">1</b> <https://github.com/QubesOS/qubes-issues/issues/2841> [↩](#a1-1)

328
troubleshooting/macbook-troubleshooting.md Normal file
View File

@ -0,0 +1,328 @@
---
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

25
troubleshooting/newer-hardware-troubleshooting.md Normal file
View File

@ -0,0 +1,25 @@
---
layout: doc
title: Troubleshooting newer hardware
permalink: /doc/newer-hardware-troubleshooting/
---
Troubleshooting newer hardware
==============================
By default, the kernel that is installed in dom0 comes from the `kernel` package, which is an older Linux LTS kernel.
For most cases this works fine since the Linux kernel developers backport fixes to this kernel, but for some newer hardware, you may run into issues.
For example, the audio might not work if the sound card is too new for the LTS kernel.
To fix this, you can try the `kernel-latest` package - though be aware that it's less tested!
In dom0:
~~~
sudo qubes-dom0-update kernel-latest
~~~
Reboot when it's done installing.
You can double-check that the boot used the newer kernel with `uname -r`, which prints the version of the currently-running kernel.
Compare this with the output of `rpm -q kernel`.
If the start of `uname -r` matches one of the versions printed by `rpm`, then you're still using the Linux LTS kernel, and you'll probably need to manually fix your boot settings.
If `uname -r` reports a higher version number, then you've successfully booted with the kernel shipped by `kernel-latest`.

159
troubleshooting/nvidia-troubleshooting.md Normal file
View File

@ -0,0 +1,159 @@
---
layout: doc
title: Nvidia Troubleshooting
permalink: /doc/nvidia-troubleshooting/
redirect_from:
- /en/doc/nvidia-troubleshooting/
- /doc/NvidiaTroubleshooting/
- /wiki/NvidiaTroubleshooting/
---
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".
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
---------------------
Assuming your X Window System works fine now when you booted from the "failsafe" configuration, do the next steps...
1. Do not log into X, but instead switch to a text console (press Ctrl-Alt-F2)
2. Log in as root
3. Switch to runlevel 3 (this should kill your X server):
~~~
init 3
~~~
4. Run X-autoconfiguration:
~~~
Xorg -configure
~~~
This should generate a file `xorg.conf.new` in the `/root` directory.
In most cases you can ignore any warning or error messages displayed by the X server, assuming it generated the xorg.conf.new file.
5. Edit this newly generated `xorg.conf.new` file and introduce the following two modifications:
First, uncomment the ShadowFB option, so that you should now have something like this:
~~~
Option "ShadowFB" # [<bool>]
~~~
Second, change the driver name to `nouveau` (you will probably have `nv` written there):
~~~
Driver "nouveau"
~~~
Save the modification, exit the editor.
6. Move the file to `/etc/X11` and rename it as `xorg.conf`:
~~~
mv /root/xorg.conf.new /etc/X11/xorg.conf
~~~
7. Verify that X will work with those new settings:
~~~
xinit
~~~
If you see a terminal window in the top left corner, it means you most likely succeeded, even if your keyboard or mouse do not work now (don't worry about them).
8. Reboot and let the system boot from the normal boot configuration. You should be able to use X under Xen now.
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
~~~
nouveau E[ PGRAPH][0000:01:00.0] grctx template channel unload timeout
nouveau E[ PGRAPH][0000:01:00.0] failed to construct context
nouveau E[ PGRAPH][0000:01:00.0] init failed, -16
~~~
Tip: In case you only have an external monitor it is advised to attach it directly to a connector of the motherboard if it is present, this should ensure that you're using the integrated graphics card instead of the nvidia graphics card.
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.
1. Verify that that GRUB Boot Menu is displaying, you should be presented with two options and a progressbar/timer than goes rather fast.
~~~
Qubes
Qubes with advanced Xen options
~~~
2. Quickly press the "E" key before the time is up.
3. An editor will open up that allows you to temporarily change the grub options for the next boot.
4. Press the down arrow key and move the cursor to the line after the line with the kernel options. The line with the kernel options will look like this:
~~~
module /vmlinux-4.1.13-9.pvops.qubes.x86_64 placeholder root=/dev/mapper/qubes_dom0-root ro ... rhgb quiet
~~~
It is not an exact copy as it may differ from system to system.
Please note: choose the module that starts with `vmlinux`!
5. Press the left/right arrow keys to position the cursor at the end of kernel options line, after `rhgb quiet` in this case.
6. Add the following:
~~~
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
~~~
This will temporarily disable nouveau until next boot.
7. Press either the F10 key or Ctrl+X to start the boot process.
Qubes should now boot properly, if that's the case then we should make this change permanent such that the GRUB config knows to not run nouveau.
You'll have to do the following to make this change persistent, so that it will work properly on every boot :
1. Open a terminal (do this by clicking on Q > 'run command' > type 'terminal' and hit enter)
2. type following commands:
~~~
cd /etc/default/
sudo nano grub
~~~
3. Edit `GRUB_CMDLINE_LINUX`, add the following to it at the end:
~~~
nouveau.modeset=0 rd.driver.blacklist=nouveau video=vesa:off
~~~
4. ctrl + X and then y to save the file.
5. The final step is to compile the configuration file to something the bootloader can read.
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~

47
troubleshooting/out-of-memory.md Normal file
View File

@ -0,0 +1,47 @@
---
layout: doc
title: Out of Memory
permalink: /doc/out-of-memory/
redirect_from:
- /en/doc/out-of-memory/
- /doc/OutOfmemory/
- /wiki/OutOfmemory/
---
VMs (especially templates) use pre-allocated space. The default private storage max size is 2 GB, but it's very easy to increase as needed. If the disk is completely full, you will get an `Out of disk space` error that may crash your system because Dom0 does not have enough disk space to work. So it's good practice to regularly check disk space usage with the command `df -h` in dom0 terminal.
A system that's out of space should be able to boot, but may be unable to load a desktop manager. In this case it is possible to login to dom0 terminal with Alt + Ctrl + F2. To recover disk space it may be possible to delete files in a userVM by connecting to the userVM terminal:
~~~
qvm-start <VMname>
sudo xl console <VMname>
~~~
If this does not work, check the size of /var/lib/qubes/qubes.xml. If it is zero, you'll need to use one of the file backup (stored in /var/lib/qubes/backup), hopefully you have the current data there. Find the most recent one and place in /var/lib/qubes/qubes.xml instead of the empty file.
In any case you'll need some disk space to start the VM. Check `df -h` output if you have some. If not, some hints how to free some disk space:
1. Clean yum cache:
~~~
sudo yum clean all
~~~
1. Delete .img files of a less important VM, that can be found in
/var/lib/qubes/appvms/. Then, when the system is working again, cleanup the rest with:
~~~
qvm-remove <VMname>
~~~
With this method you lose the data of one VM, but it'll work more reliably.
1. Decrease filesystem safety margin (5% by default):
~~~
sudo tune2fs -m 4 /dev/mapper/vg_dom0-lv_root
~~~
1. Remove some unneeded files in dom0 home (if you have any, most likely not).

36
troubleshooting/remove-vm-manually.md Normal file
View File

@ -0,0 +1,36 @@
---
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/#how-to-install-uninstall-reinstall-and-switch

58
troubleshooting/sony-vaio-tinkering.md Normal file
View File

@ -0,0 +1,58 @@
---
layout: doc
title: Sony Vaio Tinkering
permalink: /doc/sony-vaio-tinkering/
redirect_from:
- /en/doc/sony-vaio-tinkering/
- /doc/SonyVaioTinkering/
- /wiki/SonyVaioTinkering/
---
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.
Getting the graphics card working under Linux/Qubes OS
------------------------------------------------------
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.
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)
**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!
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
------------------------------------------------
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\>
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:
~~~
$ sudo bash
# qvm-dom0-networking up
# yum install qubes-core-dom0-vaio-fixes
# reboot
~~~
This script takes care about the following:
- Setting i8042.nopnp for your installed system
- 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! ;)

94
troubleshooting/thinkpad-troubleshooting.md Normal file
View File

@ -0,0 +1,94 @@
---
layout: doc
title: Lenovo ThinkPad Troubleshooting
permalink: /doc/thinkpad-troubleshooting/
redirect_from:
- /doc/thinkpad_x201/
- /en/doc/thinkpad_x201/
- /doc/Thinkpad_X201/
- /wiki/Thinkpad_X201/
- /doc/lenovo450-tinkering/
- /en/doc/lenovo450-tinkering/
- /doc/Lenovo450Tinkering/
- /wiki/Lenovo450Tinkering/
---
# Lenovo ThinkPad Troubleshooting #
## Instructions to create USB installation medium for newer (UEFI-only) ThinkPads ##
Newer ThinkPads (e.g. T470, T470p, ThinkPad 25) are likely to fail installation attempts made from a USB stick that was created with dd or Rufus, and even from a DVD burned using official ISO images - if the ThinkPad is configured for UEFI boot. If you don't want to use Legacy Mode as a workaround, the following instructions should help you create a Qubes Installation USB stick that works in UEFI-only mode.
In a nutshell, you need to use the Fedora livecd-tools to make a Qubes Installation USB Stick from the Qubes ISO image, then update the label on the partition of that USB stick to "BOOT", and then update the BOOT/EFI/xen.cfg file on the USB stick so that all labels point to BOOT. In more detail:
1. On your ThinkPad, enter the UEFI setup (press F1 at startup) and make sure to set at least the following options:
- *USB UEFI BIOS Support: Enabled*
- *UEFI/Legacy Boot: UEFI Only*
- *Secure Boot: Disabled*
2. On a different computer, create a "Fedora Live USB Stick": Download a current Fedora Live CD image, and put it onto a USB stick (e.g. using dd or Rufus). Start your ThinkPad from the Fedora Live USB Stick on your ThinkPad (Press F12 at startup to select boot device). Of course, you can alternatively start a different machine from the Fedora Live USB Stick, or use an existing Fedora installation. The next steps all occur within Fedora:
3. Install livecd-tools: `# dnf install livecd-tools`
4. Download the desired Qubes ISO image (or attach a storage device containing it), and verify the signatures as described in the Qubes installation guide. For these instructions, I assume the ISO image is at */run/media/liveuser/qsrc/Qubes-R4.0-rc3-x86_64.iso* (so whenever you see that path going forward in these instructions, replace it with whatever your own path is)
5. Within Fedora, attach the USB stick that you would like to turn into your Qubes Installation USB Stick. Use `dmesg` to figure out what the device name of that stick is. For these instructions, I assume it's */dev/sdd* (so whenever you see */dev/sdd* going forward in these instructions, replace it with whatever your actual device name is)
6. Make sure your target USB stick (presumed to be /dev/sdd) has no mounted partitions: ``# umount /dev/sdd*`` (the asterisk at the end makes sure to unmount all partitions if more than one exists). If none are mounted you'll get an error that you can ignore.
7. Use livecd-tools to copy the image: ``# livecd-iso-to-disk --format --efi /run/media/liveuser/qsrc/Qubes-R4.0-rc3-x86_64.iso /dev/sdd``. **This will erase everything on the drive. Make sure you specify the correct destination.** Then press ENTER when prompted to proceed. This process will take quite a while, be patient.
8. When imaging is complete, change the partition label to BOOT: ``# dosfslabel /dev/sdd1 BOOT``
9. Now create a mount point and mount the partition:
``# mkdir /mnt/qinst``
``# mount /dev/sdd1 /mnt/qinst/``
10. Use your favorite editor to edit the file */mnt/qinst/EFI/BOOT/xen.cfg*: Replace all instances of ``LABEL=Qubes-R4.0-rc3-x86_64`` with ``LABEL=BOOT``. There is typically no space in front of ``LABEL``, but there is a space at the end of the portion you replace.
11. Unmount the Qubes Installation USB stick: ``# umount /dev/sdd*`` and disconnect it.
That's it! You can now reboot the machine with the Qubes USB Installation stick attached, and press F12 to select it as the boot device at startup. Proceed to install Qubes OS normally. Enjoy!
## ThinkPads with Intel HD 3000 graphics ##
Several ThinkPad models have Intel HD 3000 graphics, including the T420s and the
T520. Some users with these laptops have experienced random reboots, which were
solved by adding `i915.enable_rc6=0` as a kernel parameter to
`GRUB_CMDLINE_LINUX` in the file `/etc/default/grub` in dom0.
## Instructions for getting your Lenovo Thinkpad X201 & X200 laptop working with Qubes/Linux ##
For being able to boot the installer from USB, you have to disable VT-d in the BIOS.
Enter the BIOS by hitting F1, go to Config - CPU and then disable VT-d there.
After the installation, you have to set a startup-parameter for Xen, to be able to activate VT-d again:
1. Open a terminal in dom0
2. Edit `/etc/default/grub`
3. Add to the line `GRUB_CMDLINE_XEN_DEFAULT` the setting `iommu=no-igfx`, save and quit
4. sudo `grub2-mkconfig --output /boot/grub2/grub.cfg`
Then reboot, enter BIOS and re-enable VT-d.
### Getting scrolling with the Trackpoint and the Middle Button to work ###
1. Create a script with the following content:
~~~
#!/bin/sh
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation" 1
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Button" 2
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Timeout" 200
xinput set-prop "TPPS/2 IBM TrackPoint" "Evdev Wheel Emulation Axes" 6 7 4 5
~~~
2. Add the script to the startup-items of your desktop environment.
## Instructions for getting your Lenovo 450 laptop working with Qubes/Linux ##
Lenovo 450 uses UEFI, so some settings are needed to get Qubes (or Fedora) to boot, otherwise Qubes install USB stick will reboot right after boot selector screen and not continue install.
### Setting UEFI options to get Qubes install to boot ###
1. Enable Legacy USB mode
2. Disable all Secure Boot and UEFI options, but leave this enabled: Config / USB / USB UEFI BIOS SUPPORT
3. Save settings and reboot
5. Install Qubes
... and now enjoy :) These settings may be needed also in other UEFI computers.

237
troubleshooting/uefi-troubleshooting.md Normal file
View File

@ -0,0 +1,237 @@
---
layout: doc
title: UEFI Troubleshooting
permalink: /doc/uefi-troubleshooting/
---
Troubleshooting UEFI related problems
========================================
Change installer kernel parameters in UEFI
---------------------
If you've installed successfully in legacy mode but had to change some kernel parameters for it to work, you should try installing in UEFI mode with the same parameters.
**Change the xen configuration on a USB media**
01. Attach the usb disk, mount the EFI partition (second partition available on the disk)
02. Edit your xen config (`xen.cfg/BOOTX64.cfg`) changing the `kernel` key to add your kernel parameters on the boot entry of your choice
03. Install using your modified boot entry
**Change xen configuration directly in an iso image**
01. Get EFI partition boundaries `parted Qubes-R4.0-rc4-x86_64.iso unit B print`
02. Using the start address and the size of the EFI partition, setup a loop device for it `sudo losetup -o 524288 --sizelimit 30562304 /dev/loop0 Qubes-R4.0-rc4-x86_64.iso`
03. Mount the loop device `sudo mount /dev/loop0 /mnt`
04. Edit `EFI/BOOT/BOOTX64.cfg` to add your params to the `kernel` configuration key
05. Save your changes, unmount and dd to usb device
Cannot start installation, installation completes successfully but then BIOS loops at boot device selection, hangs at four penguins after choosing "Test media and install Qubes OS" in GRUB menu
---------------------
There is some [common bug in UEFI implementation](http://xen.markmail.org/message/f6lx2ab4o2fch35r), affecting mostly Lenovo systems, but probably some others too. You can try existing workaround:
01. In GRUB menu<sup id="a1-1">[1](#f1)</sup>, select "Troubleshoot", then "Boot from device", then press `e`.
02. At the end of `chainloader` line add `/mapbs /noexitboot`.
03. Perform installation normally, but don't reboot the system at the end yet.
04. Go to `tty2` (Ctrl-Alt-F2).
05. Enable `/mapbs /noexitboot` on just installed system. This step differs between Qubes releases:
**For Qubes 3.1:**
06. Execute `mount | grep boot/efi` and note device name (first column). It should be something like `/dev/sda1`.
07. Execute `efibootmgr -v`, search for `Qubes` entry and note its number (it should be something like `Boot0001` - `0001` is an entry number).
08. Replace existing `Qubes` entry with modified one. Replace `XXXX` with entry number from previous step, `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number):
efibootmgr -b XXXX -B
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot"
09. Compare new entry with the old one (printed in step 6) - it should only differ in additional options at the end, and look probably something like this:
Boot0001* Qubes HD(1,GPT,partition-guid-here,0x800,0x64000)/File(\EFI\qubes\xen.efi)p.l.a.c.e.h.o.l.d.e.r. ./.m.a.p.b.s. ./.n.o.e.x.i.t.b.o.o.t.
If instead it looks like:
Boot0001* Qubes HD(1,0,00000000...0,0x0,0x0)/File(\EFI\qubes\xen.efi)p.l.a.c.e.h.o.l.d.e.r. ./.m.a.p.b.s. ./.n.o.e.x.i.t.b.o.o.t.
then try passing `/dev/sda1` or `/dev/nvme0n1p1` or whatever your EFI partition is instead of `/dev/sda` and `-p 1`.
10. Now you can reboot the system by issuing `reboot` command.
**For Qubes 3.2 or later:**
11. Edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg` (you can use `vi` editor) and add to every kernel section:
mapbs=1
noexitboot=1
**Note:** You must add these parameters on two separate new lines (one
parameter on each line) at the end of each section that includes a kernel
line (i.e., all sections except the first one, since it doesn't have a
kernel line).
12. Now you can reboot the system by issuing `reboot` command.
System crash/restart when booting installer
-------------------------------------------
Some Dell systems and probably others have [another bug in UEFI firmware](http://markmail.org/message/amw5336otwhdxi76). And there is another workaround for it:
1. In GRUB menu<sup id="a1-2">[1](#f1)</sup> press `e`.
2. At the end of `chainloader` line add `-- efi=attr=uc`.
3. Perform installation normally, but don't reboot the system at the end yet.
4. Go to `tty2` (Ctrl-Alt-F2).
5. Execute:
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/qubes/xen.cfg
or if you're installing 3.2 execute:
sed -i -e 's/^options=.*/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/xen.cfg
6. Now you can reboot the system by issuing `reboot` command.
* * *
<b name="f1">1</b> If you use rEFInd, you can see 3 options regarding the USB installer. Choose "Fallback Boot Loader" to enter the GRUB menu. [↩](#a1-1) [↩](#a1-2)
Boot device not recognized after installing
------------------------------------------
Some firmware will not recognize the default Qubes EFI configuration. As such,
it will have to be manually edited to be bootable. This will need to be done after
every kernel and Xen update to ensure you use the most recently installed versions.
1. Copy the `/boot/efi/EFI/qubes/` directory to `/boot/efi/EFI/BOOT/`
(the contents of `/boot/efi/EFI/BOOT` should be identical to `/boot/efi/EFI/qubes`
besides what is described in steps 2 and 3):
cp -r /boot/efi/EFI/qubes/. /boot/efi/EFI/BOOT
2. Rename `/boot/efi/EFI/BOOT/xen.cfg` to `/boot/efi/EFI/BOOT/BOOTX64.cfg`:
mv /boot/efi/EFI/BOOT/xen.cfg /boot/efi/EFI/BOOT/BOOTX64.cfg
3. Copy `/boot/efi/EFI/qubes/xen-*.efi` to `/boot/efi/EFI/qubes/xen.efi`
and `/boot/efi/EFI/BOOT/BOOTX64.efi`. For example with Xen 4.8.3
(you may need to confirm file overwrite):
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/qubes/xen.efi
cp /boot/efi/EFI/qubes/xen-4.8.3.efi /boot/efi/EFI/BOOT/BOOTX64.efi
Installation finished but "Qubes" boot option is missing and xen.cfg is empty
--------------------------------------------------------------------------------------
In some cases installer fails to finish EFI setup and leave the system without
Qubes-specific EFI configuration. In such a case you need to finish those parts
manually. You can do that just after installation (switch to `tty2` with
Ctrl-Alt-F2), or booting from installation media in "Rescue a Qubes system" mode.
1. Examine `/boot/efi/EFI/qubes` (if using Qubes installation media, it's in `/mnt/sysimage/boot/efi/EFI/qubes`). You should see 4 files there:
- xen.cfg (empty, size 0)
- xen-(xen-version).efi
- vmlinuz-(kernel-version)
- initramfs-(kernel-version).img
2. Copy `xen-(xen-version).efi` to `xen.efi`:
cd /mnt/sysimage/boot/efi/EFI/qubes
cp xen-*.efi xen.efi
3. Create xen.cfg with this content (adjust kernel version, and filesystem
locations, below values are based on default installation of Qubes 3.2):
[global]
default=4.4.14-11.pvops.qubes.x86_64
[4.4.14-11.pvops.qubes.x86_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M
kernel=vmlinuz-4.4.14-11.pvops.qubes.x86_64 root=/dev/mapper/qubes_dom0-root rd.lvm.lv=qubes_dom0/root rd.lvm.lv=qubes_dom0/swap i915.preliminary_hw_support=1 rhgb quiet
ramdisk=initramfs-4.4.14-11.pvops.qubes.x86_64.img
4. Create boot entry in EFI firmware (replace `/dev/sda` with your disk name and `-p 1` with `/boot/efi` partition number):
efibootmgr -v -c -u -L Qubes -l /EFI/qubes/xen.efi -d /dev/sda -p 1 "placeholder /mapbs /noexitboot"
Installation freezes before getting to Anaconda (Qubes 4.0)
-----------------------------------------------------------
Some systems can freeze with the default UEFI install options.
You can try the following to remove `noexitboot` and `mapbs`.
If you have an Nvidia card, see also [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#disabling-nouveau).
1. Follow the [steps above](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `xen.cfg`.
You want to comment out the `mapbs` and `noexitboot` lines.
The end result should look like this:
~~~
[qubes-verbose]
options=console=vga efi=attr=uc
# noexitboot=1
# mapbs=1
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
ramdisk=initrd.img
~~~
2. Boot the installer and continue to install as normal, but don't reboot the system at the end when prompted.
3. Go to `tty2` (Ctrl-Alt-F2).
4. Use your preferred text editor (`nano` works) to edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`, verifying the `noexitboot` and `mapbs` lines are not present.
This is also a good time to make permanent any other changes needed to get the installer to work, such as `nouveau.modeset=0`.
For example:
~~~
[4.14.18-1.pvops.qubes.x86_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=attr=uc
~~~
5. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
6. Continue with setting up default templates and logging in to Qubes.
Installation freezes before getting to Anaconda / disable EFI runtime services
------------------------------------------------------------------------------
On some early, buggy UEFI implementations, you may need to disable EFI under Qubes completely.
This can sometimes be done by switching to legacy mode in your BIOS/UEFI configuration.
If that's not an option there, or legacy mode does not work either, you can try the following to add `efi=no-rs`.
1. Follow the [steps above](/doc/uefi-troubleshooting/#change-installer-kernel-parameters-in-uefi) to edit the `[qubes-verbose]` section of your installer's `xen.cfg`.
You want to modify the `efi=attr=uc` setting and comment out the `mapbs` and `noexitboot` lines.
The end result should look like this:
~~~
[qubes-verbose]
options=console=vga efi=no-rs
# noexitboot=1
# mapbs=1
kernel=vmlinuz inst.stage2=hd:LABEL=Qubes-R4.0-x86_64 i915.alpha_support=1
ramdisk=initrd.img
~~~
2. Boot the installer and continue to install as normal, until towards the end when you will receive a warning about being unable to create the EFI boot entry.
Click continue, but don't reboot the system at the end when prompted.
3. Go to `tty2` (Ctrl-Alt-F2).
4. Use your preferred text editor (`nano` works) to edit `/mnt/sysimage/boot/efi/EFI/qubes/xen.cfg`, adding the `efi=no-rs` option to the end of the `options=` line.
For example:
~~~
[4.14.18-1.pvops.qubes.x86_64]
options=loglvl=all dom0_mem=min:1024M dom0_mem=max:4096M iommu=no-igfx ucode=scan efi=no-rs
~~~
5. Execute the following commands:
~~~
cp -R /mnt/sysimage/boot/efi/EFI/qubes /mnt/sysimage/boot/efi/EFI/BOOT
mv /mnt/sysimage/boot/efi/EFI/BOOT/xen.efi /mnt/sysimage/boot/efi/EFI/BOOT/BOOTX64.efi
mv /mnt/sysimage/boot/efi/EFI/BOOT/xen.cfg /mnt/sysimage/boot/efi/EFI/BOOT/BOOTX64.cfg
~~~
6. Go back to `tty6` (Ctrl-Alt-F6) and click `Reboot`.
7. Continue with setting up default templates and logging in to Qubes.
Whenever there is a kernel or Xen update for Qubes, you will need to follow these [other steps above](/doc/uefi-troubleshooting/#boot-device-not-recognized-after-installing) because your system is using the fallback UEFI bootloader in `[...]/EFI/BOOT` instead of directly booting to the Qubes entry under `[...]/EFI/qubes`.
Accessing installer Rescue mode on UEFI
---------------------------------------
In UEFI mode installer do not have boot menu, but starts directly the installation wizard. To get into Rescue mode, you need to switch to tty2 (Ctrl+Alt+F2) and then execute:
~~~
pkill -9 anaconda
anaconda --rescue
~~~

138
troubleshooting/updating-debian-and-whonix.md Normal file
View File

@ -0,0 +1,138 @@
---
layout: doc
title: Updating Debian and Whonix
permalink: /doc/troubleshooting/updating-debian-and-whonix/
---
Updating Debian and Whonix
==========================
Despite Qubes shipping with [Debian Templates](/doc/templates/debian/), most of Qubes core components run on Fedora and thus our documentation has better coverage for Fedora. However, Qubes has been working closely with the [Whonix](https://whonix.org) project which is based on Debian.
This troubleshooting guide is collection of tips about updating Whonix that also pertain to updating the normal Debian package manager. If you plan to use Debian heavily, **we highly recommend you install the Whonix templates and use them to update your normal Debian TemplateVM.**
*Note: some of the links on this page go to documentation on Whonix's website*
### Updating Error Messages
After running the commands to update Debian or Whonix, hopefully everything will complete perfectly.
~~~
sudo apt-get update && sudo apt-get dist-upgrade
~~~
However, if you see something like the following, then something went wrong.
~~~
W: Failed to fetch http://ftp.us.debian.org/debian/dist/jessie/contrib/binary-i386/Packages 404 Not Found
W: Failed to fetch http://ftp.us.debian.org/debian/dist/jessie/non-free/binary-i386/Packages 404 Not Found
E: Some index files failed to download. They have been ignored, or old ones used instead.
Err http://ftp.us.debian.org jessie Release.gpg
Could not resolve 'ftp.us.debian.org'
Err http://deb.torproject.org jessie Release.gpg
Could not resolve 'deb.torproject.org'
Err http://security.debian.org jessie/updates Release.gpg
Could not resolve 'security.debian.org'
Reading package lists... Done
W: Failed to fetch http://security.debian.org/dists/jessie/updates/Release.gpg Could not resolve 'security.debian.org'
W: Failed to fetch http://ftp.us.debian.org/debian/dists/jessie/Release.gpg Could not resolve 'ftp.us.debian.org'
W: Failed to fetch http://deb.torproject.org/torproject.org/dists/jessie/Release.gpg Could not resolve 'deb.torproject.org'
W: Some index files failed to download. They have been ignored, or old ones used instead.
~~~
This could be a temporary Tor exit relay or server failure that should fix itself. Here are some simple things to try:
- Check if your network connection is functional
- Try to [change your Tor circuit](https://www.whonix.org/wiki/Arm), then try again
- Running [whonixcheck](https://www.whonix.org/wiki/Whonixcheck) might also help diagnose the problem
Sometimes if you see a message such as:
~~~
Could not resolve 'security.debian.org'
~~~
It helps to run the following command:
~~~
nslookup security.debian.org
~~~
And then trying running the `update` and `upgrade` commands again.
~~~
sudo apt-get update && sudo apt-get dist-upgrade
~~~
*Please note: if you [disabled the Whonix APT Repository](https://www.whonix.org/wiki/Whonix-APT-Repository#Disable_Whonix_APT_Repository) you'll have to manually check for new Whonix releases and [manually install them from source code](https://www.whonix.org/wiki/Dev/Build_Documentation).*
### Never Install Unsigned Packages
If you see something like this:
~~~
WARNING: The following packages cannot be authenticated!
icedove
Install these packages without verification [y/N]?
~~~
Don't proceed! Press `N` and `<enter>`. Running `apt-get update` again should fix it. If not, something is broken or it's a [Man in the middle attack](https://www.whonix.org/wiki/Warning#Man-in-the-middle_attacks), which isn't that unlikely, since we are updating over Tor exit relays and some of them are malicious. Try to [change your Tor circuit](https://www.whonix.org/wiki/Arm#Arm).
### Signature Verification Warnings
There should be none at the moment. If there was such a warning, it would look like this:
~~~
W: A error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://deb.torproject.org stable Release: The following signatures were invalid: KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681
~~~
Even though, `apt-get` will automatically ignore repositories with expired keys or signatures, you will not receive upgrades from that repository. Unless the issue is already known/documented, it should be reported so it can be further investigated.
There are two possible reasons why this could happen, either there is an issue with the repository that the maintainers have to fix, or you are victim of a [Man-in-the-middle_attacks](https://www.whonix.org/wiki/Warning#Man-in-the-middle_attacks). The latter would not be a big issue and might go away after a while automatically or try to [change your Tor circuit](https://www.whonix.org/wiki/Arm#Arm)
In past various apt repositories were signed with expired key. If you want to see how the documentation looked at that point, please click on expand on the right.
[The Tor Project's apt repository key was expired](https://trac.torproject.org/projects/tor/ticket/12994). You saw the following warning.
~~~
W: A error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://deb.torproject.org stable Release: The following signatures were invalid: KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681 KEYEXPIRED 1409325681
W: Failed to fetch http://deb.torproject.org/torproject.org/dists/stable/Release
W: Some index files failed to download. They have been ignored, or old ones used instead.
~~~
It had already been [reported](https://trac.torproject.org/projects/tor/ticket/12994). There was no immediate danger. You could have just ignored it. Just make sure, you never install unsigned packages as explained above.
If you were to see other signature verification errors, those should be reported, but it shouldn't happen at this time.
### Changed Configuration Files
If you see something like the following.
~~~
Setting up ifupdown ...
Configuration file /etc/network/interfaces
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ? Your options are:
Y or I : install the package maintainer's version
N or O : keep your currently-installed version
D : show the differences between the versions
Z : background this process to examine the situation
The default action is to keep your current version.
*** interfaces (Y/I/N/O/D/Z) [default=N] ? N
~~~
Be careful. If the updated file isn't coming from Whonix specific package (some are called `whonix-...`), then press `n`. Otherwise anonymity/privacy/security settings deployed with Whonix might get lost. If you are an advanced user and know better, you can of course manually check the difference and merge them.
How could you find out if the file is coming from a Whonix specific package or not?
* Whonix specific packages are sometimes called `whonix-...`. In the example above it's saying `Setting up ifupdown ...`, so the file isn't coming from a Whonix specific package. In this case, you should press `n` as advised in the paragraph above.
* If the package name does include `whonix-...`, it's a Whonix specific package. In that case, your safest bet should be pressing `y`, but then you would lose your customized settings. You can re-add them afterwards. Such conflicts will hopefully rarely happen, if you use [Whonix modular flexible .d style configuration folders](https://www.whonix.org/wiki/Whonix_Configuration_Files).

121
troubleshooting/wireless-troubleshooting.md Normal file
View File

@ -0,0 +1,121 @@
---
layout: doc
title: Wireless Troubleshooting
permalink: /doc/wireless-troubleshooting/
redirect_from:
- /en/doc/wireless-troubleshooting/
---
Wireless Troubleshooting Guide
==============================
These instructions may help with suspend/resume issues for more devices than just wireless cards, that is just the (unfortunately not uncommon) example used here.
Resetting wireless cards by reloading drivers
---------------------------------------------
If your wireless card works, but after suspending and resuming your computer, the Network-Manager applet just says "Device not ready", then try un-loading and re-loading the driver.
### Determining your wireless card driver ###
First, determine which kernel module corresponds to your wireless card. There are several ways to do this.
The easiest is via the output of `lspci -k` in your sys-net VM:
~~~
[user@sys-net ~]$ lspci -k
00:00.0 Network controller: Intel Corporation Wireless 8260 (rev 3a)
Subsystem: Intel Corporation Device 0130
Kernel driver in use: iwlwifi
Kernel modules: iwlwifi
~~~
Here we see that the machine in question has an Intel wireless card, being used by the `iwlwifi` kernel module.
### Checking logs for relevant messages ###
View the output of `dmesg` in sys-net, and check if you see a bunch of wireless related errors. Depending on your hardware, they may look like the following (or not):
~~~
iwlwifi 0000:00:00.0: loaded firmware version 16.242414.0 op_mode iwlmvm
iwlwifi 0000:00:00.0: Detected Intel(R) Dual Band Wireless AC 8260, REV=0x208
...
IPv6: ADDRCONF(NETDEV_UP): wlp0s0: link is not ready
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: L1 Enabled - LTR Enabled
iwlwifi 0000:00:00.0: Failed to load firmware chunk!
iwlwifi 0000:00:00.0: Could not load the [0] uCode section
iwlwifi 0000:00:00.0: Failed to start INIT ucode: -110
iwlwifi 0000:00:00.0: Failed to run INIT ucode: -110
...
iwlwifi 0000:00:00.0: Direct firmware load for iwlwifi-8000C-18.ucode failed with error -2
~~~
### Seeing what modules you have loaded ###
You can check which drivers are currently loaded with `lsmod`, and view details about a module with `modinfo <module_name>`.
For example, we list what modules we have loaded:
~~~
[user@sys-net ~]$ lsmod
Module Size Used by
iwlmvm 315392 0
iwlwifi 155648 1 iwlmvm
mac80211 708608 1 iwlmvm
cfg80211 557056 3 iwlwifi,mac80211,iwlmvm
...
~~~
and check one:
~~~
[user@sys-net ~]$ modinfo iwlmvm | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: The new Intel(R) wireless AGN driver for Linux
depends: iwlwifi,mac80211,cfg80211
~~~
Hey, it's our wireless driver!
Now, check if reloading the module makes wireless work again:
~~~
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo modprobe iwlmvm
~~~
and try reconnecting to a network that is known to work.
If that is successful, see below about having Qubes automatically reload the driver for you. If not, try also reloading some dependent modules, in our example we must also reload iwlwifi:
~~~
[user@sys-net ~]$ modinfo iwlwifi | grep -E '^(description|author|depends):'
author: Copyright(c) 2003- 2015 Intel Corporation <ilw@linux.intel.com>
description: Intel(R) Wireless WiFi driver for Linux
depends: cfg80211
~~~
~~~
[user@sys-net ~]$ sudo rmmod iwlmvm
[user@sys-net ~]$ sudo rmmod iwlwifi
[user@sys-net ~]$ sudo modprobe iwlwifi # note the reverse order of loading/unloading
[user@sys-net ~]$ sudo modprobe iwlmvm
~~~
Automatically reloading drivers on suspend/resume
-------------------------------------------------
If reloading the driver (which resets the hardware into a known-state) resolves your issue when done manually, you can have Qubes automatically un/reload them on suspend & resume by listing the relevant modules in `/rw/config/suspend-module-blacklist`.
In the above example, it would look like this:
~~~
[user@sys-net config]$ cat /rw/config/suspend-module-blacklist
# You can list here modules you want to be unloaded before going to sleep. This
# file is used only if the VM has any PCI device assigned. Modules will be
# automatically loaded after resume.
iwlmvm
iwlwifi
~~~