Git-Mirrors/Qubes-Community-Content
1
0
Fork 0
mirror of https://github.com/Qubes-Community/Contents.git synced 2025-05-02 06:16:28 -04:00
Code Issues Projects Releases Packages Wiki Activity

Migrate external docs from qubes-doc

Browse source 
https://github.com/QubesOS/qubes-issues/issues/4693
This commit is contained in:
Andrew David Wong 2020-12-07 20:04:29 -08:00
commit e3f40cc91f
No known key found for this signature in database
GPG key ID: DB4DD3BC39503030
50 changed files with 6774 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/configuration/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
docs/configuration/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
docs/configuration/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
~~~

107
docs/configuration/fetchmail.md Normal file
View file

@ -0,0 +1,107 @@
---
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
~~~
Make sure the folder '/rw/config/qubes-bind-dirs.d' exists.
~~~
sudo mkdir -p /rw/config/qubes-bind-dirs.d
~~~
Create the file '/rw/config/qubes-bind-dirs.d/50_user.conf' with root rights.
Now edit it to append the '/var/spool/mail/' directory to the binds variable.
~~~
binds+=( '/var/spool/mail' )
~~~
Now reboot your AppVM and you are done.

141
docs/configuration/install-nvidia-driver.md Normal file
View file

@ -0,0 +1,141 @@
---
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.
Before continuing, you may wish to try the `kernel-latest` package from the `current` repository. This kernel may better support your card and if so, you would not have to rely on proprietary drivers. This can be installed from dom0 with:
~~~
sudo qubes-dom0-update kernel-latest
~~~
## 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
The GRUB menu may show up fine, the installation environment starts loading, and then the display(s) go into standby mode. This is, typically, related to some sort of an issue with the kernel's KMS/video card modules. See the [Nvidia Troubleshooting](/doc/nvidia-troubleshooting/#lack-of-video-output-during-nvidia-driver-installation) guide for troubleshooting steps.

214
docs/configuration/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 the 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 on 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
docs/configuration/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-10 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=0x4773BD5E130D1D45>
- 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/130D1D45 2019-07-15 Spotify Public Repository Signing Key <tux@spotify.com>
Key fingerprint = 2EBF 997C 15BD A244 B6EB F5D8 4773 BD5E 130D 1D45
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=0x4773BD5E130D1D45&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`

226
docs/configuration/mutt.md Normal file
View file

@ -0,0 +1,226 @@
---
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
# disable use of gpgme, which interferes with Split-GPG
# and defaults to 'yes' on Debian 9 and higher
set crypt_use_gpgme=no
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; w3m -T text/html '%s' | cat --squeeze-blank; nametemplate=%s.html; copiousoutput
text/html; qvm-open-in-dvm %s

146
docs/configuration/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
docs/configuration/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
docs/configuration/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.

152
docs/configuration/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.

55
docs/configuration/tips-and-tricks.md Normal file
View file

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

321
docs/configuration/vpn.md Normal file
View file

@ -0,0 +1,321 @@
---
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
==================================
<div class="alert alert-info" role="alert">
<i class="fa fa-info-circle"></i>
<b>Note:</b> If you seek to enhance your privacy, you may also wish to consider <a href="/doc/whonix/">Whonix</a>.
You should also be aware of <a href="https://www.whonix.org/wiki/Tunnels/Introduction">the potential risks of VPNs</a>.
</div>
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 30 and Debian 10 templates.
Before proceeding, you will need to download a copy of your VPN provider's configuration file(s) and have your VPN login information handy.
1. Create a new VM, name it, choose "provides network", 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. The 'openvpn' package comes installed in the Fedora template, and in Debian it can be installed with the following command:
sudo apt-get install openvpn
Disable any auto-starting service that comes with the software package.
For example for OpenVPN.
sudo systemctl disable openvpn.service
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 configuration 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. Files accompanying the main config such as `*.crt` and `*.pem` should also be placed in the `/rw/config/vpn` folder.
Check or modify configuration file contents using a text editor:
sudo gedit /rw/config/vpn/openvpn-client.ovpn
Files referenced in `openvpn-client.ovpn` should not use absolute paths such as `/etc/...`.
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`.
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, so we'll add a reference to a file containing the VPN username and password.
For example for OpenVPN, add or modify `auth-user-pass` like so:
auth-user-pass pass.txt
Save the `/rw/config/vpn/openvpn-client.ovpn` file.
Now make sure a `/rw/config/vpn/pass.txt` file actually exists.
sudo gedit /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 1.1.1.1
`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 gedit /rw/config/vpn/qubes-vpn-handler.sh
Add the following:
~~~
#!/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 gedit /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 gedit /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
# Accept traffic to VPN
iptables -P OUTPUT ACCEPT
iptables -F OUTPUT
# 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
# Block non-VPN traffic to clearnet
iptables -I OUTPUT -o eth0 -j DROP
# 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 gedit /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 update your TemplateVMs through the VPN, you can enable the `qubes-updates-proxy` service for your new VPN VM and configure the [qubes-rpc policy](/doc/software-update-domu/#updates-proxy).
Troubleshooting
---------------
See the [VPN Troubleshooting](/doc/vpn-troubleshooting/) guide for tips on how to fix common VPN issues.

40
docs/configuration/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
docs/configuration/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)