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

Move current pages to /en/ subdirectory

Browse source
This commit is contained in:
Axon 2015-10-11 07:29:00 +00:00
parent f3ee78f223
commit a91496e9d6
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
159 changed files with 2 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

130
configuration/AssigningDevices.md
View file

@ -1,130 +0,0 @@
---
layout: doc
title: AssigningDevices
permalink: /en/doc/assigning-devices/
redirect_from:
- /doc/AssigningDevices/
- /wiki/AssigningDevices/
---
Assigning Devices to VMs
========================
In order to assign a whole PCI(e) device to a VM, one should use `qvm-pci` tool. E.g.
~~~
lspci
~~~
Find the BDF address of the device you want to assign, and then:
~~~
qvm-pci -a <vmname> <bdf>
~~~
E.g. assuming 00:1a.0 is a BDF of the device I want to assign to the "personal" domain:
~~~
qvm-pci -a personal 00:1a.0
~~~
Note that one can only assign full PCI or PCI Express devices. This means one cannot assign single USB devices -- only the whole USB controller with whatever USB devices connected to it. This limit is imposed by PC and VT-d architecture.
Using Qubes Manager
-------------------
TODO
\<screenshot\>
Finding the right USB controller
--------------------------------
If you want assign certain USB device to a VM (by attaching a whole USB controller), you need to figure out which PCI device is the right controller. First check to which USB bus the device is connected:
~~~
lsusb
~~~
For example I want assign a broadband modem to the netvm. In lsusb output it can be listed as something like this (in this case device isn't fully identified):
~~~
Bus 003 Device 003: ID 413c:818d Dell Computer Corp.
~~~
The device is connected to the USB bus \#3. Then check which other devices are connected to the same bus - all of them will be assigned to the same VM. Now is the time to find right USB controller:
~~~
readlink /sys/bus/usb/devices/usb3
~~~
This should output something like:
~~~
../../../devices/pci-0/pci0000:00/0000:00:1a.0/usb3
~~~
Now you see BDF address in the path (right before final usb3). Strip leading "0000:" and pass the rest to qvm-pci tool:
~~~
qvm-pci -a netvm 00:1a.0
~~~
Possible issues
---------------
### DMA buffer size
VMs with assigned PCI devices in Qubes have allocated a small buffer for DMA operations (called swiotlb). By default it is 2MB, but some devices need a larger buffer. To change this allocation, edit VM's kernel parameters (this is expressed in 512B chunks):
~~~
# qvm-prefs netvm |grep kernelopts
kernelopts : iommu=soft swiotlb=2048 (default)
# qvm-prefs -s netvm kernelopts "iommu=soft swiotlb=4096"
~~~
This is [known to be needed](https://groups.google.com/group/qubes-devel/browse_thread/thread/631c4a3a9d1186e3) for Realtek RTL8111DL Gigabit Ethernet Controller.
### PCI passthrough issues
Sometimes PCI arbitrator is too strict. There is a way to enable permissive mode for it. Create `/etc/systemd/system/qubes-pre-netvm.service`:
~~~
[Unit]
Description=Netvm fixup
Before=qubes-netvm.service
[Service]
ExecStart=/bin/sh -c 'echo 0000:04:00.0 > /sys/bus/pci/drivers/pciback/permissive'
Type=oneshot
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
~~~
Then enable it with `systemctl enable qubes-pre-netvm.service`
See also: [https://groups.google.com/forum/\#!topic/qubes-users/Fs94QAc3vQI](https://groups.google.com/forum/#!topic/qubes-users/Fs94QAc3vQI), [http://wiki.xen.org/wiki/Xen\_PCI\_Passthrough](http://wiki.xen.org/wiki/Xen_PCI_Passthrough)
**NOTE:** By setting the permissive flag for the PCI device, you're potentially weakening the device isolation, especially if your system is not equipped with VT-d Interrupt Remapping unit -- see [this paper, page 7](http://www.invisiblethingslab.com/resources/2011/Software%20Attacks%20on%20Intel%20VT-d.pdf) for more details.
Bringing PCI device back to dom0
--------------------------------
By default device detached from some VM (or when VM with PCI device attached get shut down) isn't attached back to dom0. This is an intended feature. A device which was previously assigned to a less trusted AppVM could attack dom0 if it were automatically reassigned there. In order to re-enable the device in dom0, either:
1. Reboot the physical machine.
or
1. Go to the sysfs (`/sys/bus/pci`), find the right device, detach it from the pciback driver and attach back to the original driver. Replace `<BDF>` with your device, for example `00:1c.2`:
~~~
echo 0000:<BDF> > /sys/bus/pci/drivers/pciback/unbind
MODALIAS=`cat /sys/bus/pci/devices/0000:<BDF>/modalias`
MOD=`modprobe -R $MODALIAS | head -n 1`
echo <BDF> > /sys/bus/pci/drivers/$MOD/bind
~~~

68
configuration/ConfigFiles.md
View file

@ -1,68 +0,0 @@
---
layout: doc
title: ConfigFiles
permalink: /en/doc/config-files/
redirect_from:
- /doc/ConfigFiles/
- "/doc/UserDoc/ConfigFiles/"
- "/wiki/UserDoc/ConfigFiles/"
---
Qubes specific VM config files
==============================
Those files are placed in /rw, which survives VM restart, so can be used to customize single VM (not all VMs based on the same template).
- `/rw/config/rc.local` - script run at VM startup. Good place to change some service settings, replace config files with its copy stored in /rw/config etc. Example usage:
~~~
# Store bluetooth keys in /rw to keep them across VM restarts
rm -rf /var/lib/bluetooth
ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
~~~
- `/rw/config/qubes-ip-change-hook` - script run in NetVM after external IP change (or connection to the network)
- `/rw/config/qubes-firewall-user-script` - script run in ProxyVM after firewall update. Good place to write own custom firewall rules
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system going to sleep. The file is used only in VM with some PCI devices attached. Supposed to be used for problematic device drivers.
Note that scripts need to be executable (chmod +x) to be used.
GUI and audio configuration in dom0
===================================
GUI configuration file `/etc/qubes/guid.conf` in one of few not managed by qubes-prefs nor Qubes Manager tool. Sample config (included in default installation):
~~~
# Sample configuration file for Qubes GUI daemon
# For syntax go http://www.hyperrealm.com/libconfig/libconfig_manual.html
global: {
# default values
#allow_fullscreen = false;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
#audio_low_latency = false;
};
# most of setting can be set per-VM basis
VM: {
work: {
#allow_utf8_titles = true;
};
video-vm: {
#allow_fullscreen = true;
};
};
~~~
Currently supported settings:
- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame). Regardless of this setting, you can also set window fullscreen using trusted window manager settings (right click on title bar).
- `allow_utf8_titles` - allow to use UTF-8 in window titles, otherwise non-ASCII characters are replaced by underscore.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste
- `windows_count_limit` - limit on concurrent windows count.
- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default). Note that this will cause much higher CPU usage in dom0.

37
configuration/DiskTrim.md
View file

@ -1,37 +0,0 @@
---
layout: doc
title: DiskTRIM
permalink: /en/doc/disk-trim/
redirect_from:
- /doc/DiskTRIM/
- /wiki/DiskTRIM/
---
VMs have already TRIM enabled by default, but dom0 doesn't. There are some security implications (read for example [this article](http://asalor.blogspot.com/2011/08/trim-dm-crypt-problems.html)), but IMO not very serious.
To enable TRIM in dom0 you need:
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 allow-discards
~~~
3. Add `rd.luks.allow-discards=1` to kernel cmdline (`/etc/default/grub`, GRUB\_CMDLINE\_LINUX line)
4. Rebuild grub config (`grub2-mkconfig -o /boot/grub2/grub.cfg`)
5. Rebuild initrd **in hostonly mode**:
~~~
dracut -H -f
~~~
6. Add "discard" option to `/etc/fstab` for root device
7. Reboot the system, verify that allow-discards is really enabled (`dmsetup table`)
There is a [bug affecting allow-discards option](https://bugzilla.redhat.com/show_bug.cgi?id=890533), once it will be fixed, first two steps will be no longer needed.

48
configuration/ExternalAudio.md
View file

@ -1,48 +0,0 @@
---
layout: doc
title: ExternalAudio
permalink: /en/doc/external-audio/
redirect_from:
- /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 yum 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 you 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 you selection.
If you detach your external audio device, then want to insert it again, or change it with another one, you need to repeat the previous commands in terminal, adding an other line at the beginning:
~~~
pactl unload-module module-udev-detect
sudo chmod a+rw /dev/snd/*
pactl load-module module-udev-detect
~~~

16
configuration/ExternalDeviceMountPoint.md
View file

@ -1,16 +0,0 @@
---
layout: doc
title: ExternalDeviceMountPoint
permalink: /en/doc/external-device-mount-point/
redirect_from:
- /doc/ExternalDeviceMountPoint/
- /wiki/ExternalDeviceMountPoint/
---
All external storage devices connected to an AppVM using the Fedora template can be found under
~~~
/run/media/user/
~~~
...of that AppVM's filesystem.

78
configuration/Fetchmail.md
View file

@ -1,78 +0,0 @@
---
layout: doc
title: Fetchmail
permalink: /en/doc/fetchmail/
redirect_from:
- /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](/en/doc/mutt/).
Installation
------------
`yum 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](/en/doc/postfix/) 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
~~~
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##*/}
echo systemctl --no-block start fetchmail@${instance}
done
~~~
Now reboot your AppVM and you are done.

219
configuration/Mutt.md
View file

@ -1,219 +0,0 @@
---
layout: doc
title: Mutt
permalink: /en/doc/mutt/
redirect_from:
- /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](/en/doc/postfix/) or Exim and MRA such as
[Fetchmail](/en/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
------------
`yum install mutt`
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](/en/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 http://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

145
configuration/NetworkBridgeSupport.md
View file

@ -1,145 +0,0 @@
---
layout: doc
title: NetworkBridgeSupport
permalink: /en/doc/network-bridge-support/
redirect_from:
- /doc/NetworkBridgeSupport/
- /wiki/NetworkBridgeSupport/
---
Network Bridge Support (EXPERIMENTAL and UNSUPPORTED)
=====================================================
The Qubes developpement 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 developpers 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.
A new option is now available in the AppVM Settings to enable set the NetVM in bridge mode. For a bridged AppVM, you should the select a netvm instead of a firewall vm, enabled 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 accept traffic coming from network interfaces called vif\* (in our case, we will use an additional interface called bridge0. The second reason is that all trafic 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 somehow buggy as it does not remember all the parameter you setup. 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 manager 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...

39
configuration/NetworkPrinter.md
View file

@ -1,39 +0,0 @@
---
layout: doc
title: NetworkPrinter
permalink: /en/doc/network-printer/
redirect_from:
- /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 3rd 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 3rd 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 3rd party, unverified drivers there. Such template might then be made the default template for [Disposable VM creation](/en/doc/disposable-vms/), which should allow one to print any document by right-clicking on it, choosing "Open in Disposable VM" 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 3rd 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 got 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. Be sure to allow network access from the template VM to your printer, 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.

152
configuration/Postfix.md
View file

@ -1,152 +0,0 @@
---
layout: doc
title: Postfix
permalink: /en/doc/postfix/
redirect_from:
- /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](/en/doc/mutt/)+Postfix+[Fetchmail](/en/doc/fetchmail/) stack.
Installation
------------
`yum install postfix procmail make`
Procmail is not strictly neccessary, but is useful to sort your incoming mail, for example to put each mailing list in its own directory. Make is also not neccessary, 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 `yum 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` 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 important file. Put there all your SMTP servers. 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 abovementioned servers. It depends on 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 abovementioned 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
~~~
Reboot your AppVM and you are done.

127
configuration/ResizeDiskImage.md
View file

@ -1,127 +0,0 @@
---
layout: doc
title: ResizeDiskImage
permalink: /en/doc/resize-disk-image/
redirect_from:
- /doc/ResizeDiskImage/
- /wiki/ResizeDiskImage/
---
Resizing Disk Image
-------------------
There are several disk images which can be easily extended.
But pay attention to the overall consumed space of your sparse disk images.
### Private disk image
1048576 MB is the maximum size which can be assigned to a private storage through qubes-manager.
To grow the private disk image of a AppVM beyond this limit [qubes-grow-private](/en/doc/dom0-tools/qvm-grow-private/) can be used:
~~~
qvm-grow-private <vm-name> <size>
~~~
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
Note2: If once the VM is started, the disk is has not been increased, you can issue in the VM's terminal:
~~~
sudo resize2fs /dev/xvdb
~~~
### Shrinking private disk image (Linux VM)
**This operation is dangerous and this is why it isn't available in standard Qubes tools. If you have enough disk space, it is safer to create new VM with smaller disk and move the data.**
The basic idea is to:
1. Shrink filesystem on the private disk image.
2. Then shrink the image.
Ext4 does not support online shrinking, so can't be done as convenient as image grown. Note that we don't want to touch the VM filesystem directly in dom0 for security reasons. First you need to start VM without `/rw` mounted. One of the possibility is to interrupt its normal startup by adding `rd.break` kernel option:
~~~
qvm-prefs -s <vm-name> kernelopts rd.break
qvm-start --no-guid <vm-name>
~~~
And wait for qrexec connect timeout (or simply press Ctrl-C). Then you can connect to VM console and shrink the filesystem:
~~~
sudo xl console <vm-name>
# you should get dracut emergency shell here
mount --bind /dev /sysroot/dev
chroot /sysroot
mount /proc
e2fsck -f /dev/xvdb
resize2fs /dev/xvdb <new-desired-size>
umount /proc
exit
umount /sysroot/dev
poweroff
~~~
Now you can resize the image:
~~~
truncate -s <new-desired-size> /var/lib/qubes/appvms/<vm-name>/private.img
~~~
**It is critical to use the same (or bigger for some safety margin) size in truncate call compared to resize2fs call. Otherwise you will loose your data!** Then reset kernel options back to default:
~~~
qvm-prefs -s <vm-name> kernelopts default
~~~
Done.
### Template disk image
If you want install a lot of software in your TemplateVM, you may need to increase the amount of disk space your TemplateVM can use.
1. Make sure that all the VMs based on this template are shut off (including netvms etc).
2. Sanity check: verify that none of loop device are pointing at this template root.img: `sudo losetup -a`
3. Resize root.img file using `truncate -s <desired size>` (the root.img path can be obtained from qvm-prefs).
4. If any netvm/proxyvm used by this template is based on it, set template netvm to none.
5. Start the template.
6. Execute `sudo resize2fs /dev/mapper/dmroot` in the template.
7. Verify available space in the template using `df -h`
8. Shutdown the template.
9. Restore original netvm setting (if changed), check firewall settings (setting netvm to none causes firewall reset to "block all")
### HVM disk image
In this example we will grow the disk image of an HVM to 30GB.
First, stop/shutdown the HVM.
Then, from a Dom0 terminal (in KDE: System Tools -\> Terminal Emulator) do the following:
~~~
cd /var/lib/qubes/appvms/<yourHVM>/
ls -lh root.img (<--verify current size of disk image)
truncate -s 30GB root.img
ls -lh root.img (<--verify new size of disk image)
~~~
The partition table and file-system must be adjusted after this change:
#### 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
~~~

32
configuration/ResizeRootDiskImage.md
View file

@ -1,32 +0,0 @@
---
layout: doc
title: ResizeRootDiskImage
permalink: /en/doc/resize-root-disk-image/
redirect_from:
- /doc/ResizeRootDiskImage/
- /wiki/ResizeRootDiskImage/
---
Resizing \`root.img\` Size
--------------------------
The safest way to increase the size of \`root.img\` is to do it for a standalone
VM (qvm-create --standalone) - which has its own root filesystem
(copy of template, instead of smart sharing).
But it should also work for a normal template (as long as changes in the
template between reboots didn't exceed 10G).
Replace the size and the path (name) of the template as wished and run your
modified command:
~~~
truncate -s 20G /var/lib/qubes/vm-templates/fedora-21/root.img
~~~
Then start your template or standalone VM and run:
~~~
sudo resize2fs /dev/mapper/dmroot
~~~
after that shutdown the template.
Then you should have extended \`root.img\` in your VM/template

141
configuration/Rxvt.md
View file

@ -1,141 +0,0 @@
---
layout: doc
title: Rxvt
permalink: /en/doc/rxvt/
redirect_from:
- /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
------------
`yum install rxvt-unicode-256color-ml` will bring both base `rxvt-unicode` and extension. Let me also recommend excellent Terminus font: `yum 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 neccessary. 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
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.

43
configuration/SecondaryStorage.md
View file

@ -1,43 +0,0 @@
---
layout: doc
title: SecondaryStorage
permalink: /en/doc/secondary-storage/
redirect_from:
- /doc/SecondaryStorage/
- /wiki/SecondaryStorage/
---
Storing AppVMs on Secondary Drives
==================================
Suppose you have a fast but small primary SSD and a large but slow secondary
HDD. You want to store a subset of your AppVMs on the HDD. In dom0:
1. `# mv /var/lib/qubes/appvms/my-new-appvm
/path/to/secondary/drive/my-new-appvm`
2. `# ln -s /path/to/secondary/drive/my-new-appvm /var/lib/qubes/appvms/`
Now, `my-new-appvm` will behave as if it were still stored on the primary SSD
(except that it will probably be slower, since it's actually stored on the
secondary HDD).
Known Issues
------------
* The above procedure does **not** interfere with [Qubes Backup][]. However,
attempting to symlink a `private.img` file (rather than the whole AppVM
directory) is known to prevent the `private.img` file from being backed up.
The same problem may occur if the above procedure is attempted on a
[TemplateVM][]. [[1]]
* After implementing the above procedure, starting `my-new-appvm` will cause
dom0 notifications to occur stating that loop devices have been attached to
dom0. This is normal. (No untrusted devices are actually being mounted to
dom0.) Do not attempt to detach these disks. (They will automatically be
detached when you shut down the AppVM.) [[2]]
[Qubes Backup]: https://www.qubes-os.org/doc/BackupRestore/
[TemplateVM]: https://www.qubes-os.org/doc/Templates/
[1]: https://groups.google.com/d/topic/qubes-users/EITd1kBHD30/discussion
[2]: https://groups.google.com/d/topic/qubes-users/nDrOM7dzLNE/discussion

280
configuration/Torvm.md
View file

@ -1,280 +0,0 @@
---
layout: doc
title: TorVM
permalink: /en/doc/torvm/
redirect_from:
- /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 ProxyVM service that provides torified networking to all its
clients.
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](http://theinvisiblethings.blogspot.com/2011/09/playing-with-qubes-networking-for-fun.html) for a description of the concept, architecture, and the original implementation.
If you are interested TorVM, you may find the [Whonix](https://www.qubes-os.org/doc/Templates/Whonix/) templates in Qubes a more usable and robust solution for torifying traffic.
## 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-21 fedora-21-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-21-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 sys-net 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
curl 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 + estination 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/usrlocal/etc/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:
* [adrelanos](mailto:adrelanos@riseup.net) for his work on [aos/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]: https://www.qubes-os.org/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]: https://www.qubes-os.org/doc/DisposableVms/
[dispvm-customization]: https://www.qubes-os.org/doc/UserDoc/DispVMCustomization/

54
configuration/Vpn.md
View file

@ -1,54 +0,0 @@
---
layout: doc
title: VPN
permalink: /en/doc/vpn/
redirect_from:
- /doc/VPN/
- /wiki/VPN/
---
How To make a VPN Gateway in Qubes
----------------------------------
The simplest case if you set up a VPN connection using the Network Manager inside one of your VMs. Setting up such a connection is really not Qubes specific and it is documented in Your operating system documentation. If you using the Qubes default Guest OS (Fedora): [Establishing a VPN Connection](http://docs.fedoraproject.org/en-US/Fedora/18/html/System_Administrators_Guide/sec-Establishing_a_VPN_Connection.html)
The Qubes specific part is to choose the right VM for the VPN client:
### NetVM
The simplest case is to set up a VPN connection using the Network Manager inside your NetVM. Because the NetworkManager 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 Network Manager is not started here (for a good reason), you can configure any kind of VPN client in your AppVM as well, however it is only suggested if you have to use a special VPN client.
### ProxyVM
**WARNING:** *Currently the NetworkManager is not working in ProxyVMs as expected. Actually it will mess up the routing table and because of that your packets may not be routed to the VPN tunnel. - This surely occurs if your VPN wants to be the default gateway.*
One of the best thing in Qubes that you can use a special type of VMs called ProxyVM (or FirewallVM). The special thing is that your AppVMs see this as a NetVM, and the NetVMs see it as an AppVM. Because of that You can place a ProxyVM between your AppVMs and Your NetVM. This is how the default firewall VM is working.
Using a ProxyVM to set up a VPN client gives you the ability to:
- 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.
**To setup a ProxyVM as a VPN gateway you should:**
1. check (`rpm -q qubes-core-vm`) if you have the package **qubes-core-vm** version **2.1.36** (or later)
2. create a new VM and check the ProxyVM radio button
![Create\_New\_VM.png](/attachment/wiki/VPN/Create_New_VM.png)
1. add the network-manager service to this new VM
![Settings-services.png](/attachment/wiki/VPN/Settings-services.png)
1. set up Your VPN as described in the Network Manager documentation linked above.
1. connect your AppVMs to use the new VM as a NetVM.
[![Settings-NetVM.png](/attachment/wiki/VPN/Settings-NetVM.png)

196
configuration/Zfs.md
View file

@ -1,196 +0,0 @@
---
layout: doc
title: ZFS
permalink: /en/doc/zfs/
redirect_from:
- /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)