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

Replace contents with redirects to Qubes Forum

Browse source 
https://forum.qubes-os.org/t/21746
This commit is contained in:
Andrew David Wong 2023-10-29 17:05:36 -07:00
parent dd657a2cbd
commit 2fa8015505
No known key found for this signature in database
GPG key ID: DB4DD3BC39503030
94 changed files with 94 additions and 12417 deletions
Download patch file Download diff file Expand all files Collapse all files

34
docs/configuration/bluetooth.md
View file

@ -1,33 +1 @@
# Graphical Bluetooth configuration
Install the package `blueman` in the template of your `sys-usb` qube.
```
sudo dnf install -y blueman
```
Then restart the qube. From now on you should have a tray icon and be ready to connect to bluetooth devices graphically, like so:
![](https://forum.qubes-os.org/uploads/db3820/original/2X/e/e7eb9d14ec38c6a9e3784b319866ba2b105b1621.png)
In the picture above I had a sys-net combined to use USB devices too. The procedure stays the same.
Note: if you're using a separate sys-usb, and need to attach your bluetooth module to a AudioVM or MediaVM, 'blueman-manager' won't run without a recognized adapter from 'blueman-applet'. Once you attach, you can run 'blueman-manager' and with a script like the below in your AppVM's `rc.local` auto-connect to your preffered device:
```
address="XX:XX:XX:XX:XX:XX"
while (sleep 1)
do
connected=`sudo hidd --show` > /dev/null
if [[ ! $connected =~ .*${address}.* ]] ; then
sudo hidd --connect ${address} > /dev/null 2>&1
fi
done
```
The loop should be the last thing in rc.local or appended with `&`. This is a simple solution. (Something more robust would require extra work with `udev` perhaps.)
## AudioVM
For the most secure scenario, one should be running an AudioVM rather than rely on having PulseAudio in dom0. The creation of such a VM is beyond the scope of this guide.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

32
docs/configuration/change-time-zone.md
View file

@ -1,31 +1 @@
# 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
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

105
docs/configuration/disk-trim.md
View file

@ -1,104 +1 @@
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).
You should also add this service or cron job to **each VM** you want the trim function to work in.
* **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 (R4.0)
----------
If you have enabled LUKS in dom0, discards will not get passed down to the storage device in R4.0. Note that this procedure is no longer needed in R4.1, as discards are enabled by default.
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 in both R4.0 and R4.1.
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.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

47
docs/configuration/external-audio.md
View file

@ -1,46 +1 @@
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](https://www.qubes-os.org/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
~~~
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

99
docs/configuration/fetchmail.md
View file

@ -1,98 +1 @@
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](https://www.qubes-os.org/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](https://www.qubes-os.org/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.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

157
docs/configuration/http-proxy.md
View file

@ -1,156 +1 @@
How to run an HTTP filtering proxy
=================================================
Introduction
------------
By default, Qubes uses a special firewall VM that sits between the networking VM and each AppVM.
This VM controls the traffic for AppVMs and can be used to restrict what AppVMs can send or receive.
The traffic rules can be setup using the filtering rules GUI in Qubes VM manager.
The manager translates user-defined setup into iptables rules for the firewall VM's kernel.
The primary goal of the filtering rule setup in the firewall VM is to allow for the user to protect either from his own mistakes (like accessing an arbitrary website from a browser running in a banking VM) or from the mistakes of websites (like a banking website that loads JS code from a social network operator when the user logs into the bank).
As the rules in the firewall are IP-based, it has drawbacks.
First, the rules cannot be used if one has to use an HTTP proxy to connect to websites (a common setup on corporate networks).
Second, Qubes resolves DNS names from the firewall rules when the AppVM loads.
This prevents websites that use DNS-based load balancers from working unless the user reloads the firewall rules (which re-resolve the DNS names) whenever the balancer transfers her session to another IP.
Third, the initial setup of the rules is complicated as the firewall drops the connection silently.
As a workaround, one can use a browser's network console to see what is blocked, but this is time-consuming and one can easily miss some important cases like including sites for OCSP SSL certificate verification in the firewall white-list.
These drawbacks can be mitigated if one replaces iptable-based rules with a filtering HTTP proxy.
The following describes how to setup a tinyproxy-based proxy in either the firewall VM or a custom proxy VM to achieve such filtering.
**Note** This content only describes setup of an HTTP proxy.
This will handle web browsing using HTTP and HTTPS, but this type of proxy does not support other protocols such as IMAP used in Thunderbird.
For that, you need a fully featured SOCKS proxy such as Squid which is beyond the scope of this article.
Warning
-------
Running an HTTP proxy in your firewall VM increases the attack surface against that VM from a compromised AppVM.
Tinyproxy has relatively simple code and a reasonable track record to allow to certain level of trust, but one cannot exclude bugs especially in the case of hostile proxy clients as this is a less tested scenario.
It is not advisable to use the proxy in a shared firewall VM against untrusted AppVMs to black-list some unwanted connections such as advertisement sites.
A less problematic setup is to white-list possible connections for several trusted and semi-trusted AppVMs within one firewall VM.
Still, for maximum safety, one should consider running a separate ProxyVM for each important AppVM.
In Qubes R4.0, one no longer creates ProxyVMs as such. However, the same is accomplished by choosing the `provides network` checkbox when creating an AppVM that will be used as a proxy.
As a counterpoint to this warning, it is important to note that an HTTP proxy decreases the attack surface of AppVMs.
For example, with a proxy the AppVM does not need to make direct DNS connections, so a bug in the kernel or in the browser in that area would not affect the AppVM.
Also, browsers typically avoid many of the latest and greatest HTTP features when connecting through proxies, minimizing exposure of new and unproven networking code.
Setup
-----
1. After reading through the Warning section above, determine if you want to proceed with the following steps in either your default `sys-firewall` VM or in a newly created proxy VM.
If you decide to create a separate proxy VM,
* In R4.0, create a new AppVM with the `provides network` checkbox set.
* In R3.2, create a new ProxyVM.
Then, proceed with the following.
2. Copy this [archive] (**Note:** not reviewed, use at own risk!) with the proxy control script, default tinyproxy config, and a sample filtering file into the proxy VM and unpack it in the `/rw/config` folder there as root:
cd /rw/config
sudo tar xzf .../proxy.tar.xz
3. If necessary, adjust `/rw/config/tinyproxy/config` according to the man page for `tinyproxy.conf`.
The included config file refuses the connection unless the host is white-listed in the filtering file, so this can be altered if one prefers to black-list connections.
One may also specify upstream proxies here.
The file is a template file and the control script will replace `{name}` constructs in the file with actual parameters.
In general, lines with `{}` should be preserved as is.
4. For each AppVM that one wants to run through the proxy, create a corresponding filtering file in the `/rw/config/tinyproxy` directory.
With the default config, the filtering file should contain regular expressions to match white-listed hosts with one regular expression per line.
See the man page for tinyproxy.conf for details.
The file should be named:
name.ip-address-of-app-vm
The name before the dot is arbitrary.
For convenience, one can use an AppVM name here, but this is not required.
It is important to get the ip address part right, as this is what the control script uses to determine to which AppVM it will apply the proxy rules.
If you have created a separate proxy VM, change the `NetVM` of each AppVM that will be using it to the proxy VM.
That can be done in Qubes VM manager in the VM settings dialog under the Basic tab.
Next, see the Networking settings on the same tab to check the IP address of an AppVM.
The attached archive includes a `social.10.137.2.13` file with rules for an AppVM allowing connections to Google, Facebook, Linkedin, Livejournal, Youtube, and few other other sites.
One can use it as an example after changing the IP address accordingly.
When editing the rules, remember to include a `$` at the end of the host name, and to prefix each dot in the host name with a backslash (like `\.`).
This way, the pattern matches the whole host and not just a prefix, and the dot is not interpreted as an instruction to match an arbitrary character according to regular expression syntax.
5. Check that the `proxyctl.py` script can properly recognize the rule files.
For that, run:
sudo /rw/config/tinyproxy/proxyctl.py show
For each rule file it should print the name, ip address, and network interface of the running AppVMs.
It will also display the id of the tinyproxy process that proxies that AppVM.
Each pid will be `--` because we have no running proxies yet.
6. Now, start the AppVM for which you created a rule file, and then run:
sudo /rw/config/tinyproxy/proxyctl.py update
The update command starts proxy processes and adjusts the iptable rules to allow for proxy traffic for each running AppVM from the filtering files list.
For each stopped AppVM, the proxy is killed.
Check that proxy is started and the `pid` field of the show command is a number:
sudo /rw/config/tinyproxy/proxyctl.py show
7. Run the browser in the active AppVM and configure it to use the proxy on port 8100 of the proxy VM interface's IP address.
In Qubes VM manager, the IP address is displayed in the Gateway field in the Settings dialog for the AppVM.
In Firefox, go to the Preferences dialog, select Advanced->Network, and click Settings for the Connection section.
In the Connection Settings dialog, select Manual proxy configuration. For the HTTP Proxy field use the IP address of the AppVM's gateway.
Enter 8100 as the port, and select the checkbox "Use this proxy server for all protocols".
Go to a test web site.
The browser should either load it (if it was white-listed in the filtering file), or show a page generated by tinyproxy that the page was filtered out.
In the proxy VM, see the `/run/tinyproxy/<name>/log` file.
For each filtered out website it contains an entry, and one can adjust the filtering file to include the corresponding host.
After changing the file, run either:
sudo /rw/config/tinyproxy/proxyctl.py restart <name>
to restart the proxy with an updated rules file only for the given VM, or
sudo /rw/config/tinyproxy/proxyctl.py kill-all-and-restart
to restart all proxy processes.
8. To make sure that the proxy is started automatically when the AppVM starts, change `/rw/config/qubes-firewall-user-script` to include the following line:
/rw/config/tinyproxy/proxyctl.py update
If the file does not exist, create it so it looks like this:
#!/bin/sh
/rw/config/tinyproxy/proxyctl.py update
Make sure that the script is owned by root and executable:
sudo chown root:root /rw/config/qubes-firewall-user-script
sudo chmod 755 /rw/config/qubes-firewall-user-script
9. In Qubes VM manager, adjust the Firewall rules for each AppVM using a proxy.
In a typical case, when only the HTTP proxy should be permitted for outside connections:
* In R4.0, select "Limit outgoing Internet connections to..." and make sure the address list is empty.
* In R3.2, select "Deny network access except...", make sure the address list is empty, and then unselect the "Allow ICMP," "DNS", and "Update proxy" checkboxes.
There is no need to add any special entries for the proxy in the GUI as `proxyctl.py` adds rules for the proxy traffic itself.
--------------------------------------------------------------------------------
This guide was initially written by Igor Bukanov in a [message] to the `qubes-devel` [mailing list].
[archive]: https://groups.google.com/group/qubes-devel/attach/39c95d63fccca12b/proxy.tar.gz?part=0.1
[message]: https://groups.google.com/d/msg/qubes-devel/UlK8P27UtD4/K6HM_GNdyTkJ
[mailing list]: https://www.qubes-os.org/mailing-lists/
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

113
docs/configuration/install-nvidia-driver.md
View file

@ -1,112 +1 @@
# 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)](https://www.qubes-os.org/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-525.116.04" is used. Copy it to dom0. Every next step is done in dom0.
See [this page](https://www.qubes-os.org/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-525.116.04.run --ui=none --no-x-check --keep --extract
~~~
### 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 refuses to install it on Xen kernel.
To build the kernel module, enter *NVIDIA-Linux-x86\_64-525.116.04/kernel* directory and execute:
~~~
make IGNORE_XEN_PRESENCE=1 CC="gcc -DNV_VMAP_4_PRESENT -DNV_SIGNAL_STRUCT_RLIM"
mv nvidia.ko /lib/modules/$(uname -r)/kernel/drivers/video/
depmod -a
~~~
### Disable nouveau
Add `rd.driver.blacklist=nouveau` option in `/etc/default/grub` (at the end of line `GRUB_CMDLINE_LINUX`).
Install the new grub config with `grub2-mkconfig -o /boot/efi/EFI/qubes/grub.cfg`.
### Reboot
Reboot to verify all this works. You can ensure the module is loaded by running `lsmod | grep nvidia` which should display a single output line, and `lsmod | grep nouveau` should have no output.
## 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](https://www.qubes-os.org/doc/nvidia-troubleshooting/#lack-of-video-output-during-nvidia-driver-installation) guide for troubleshooting steps.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

210
docs/configuration/multiboot.md
View file

@ -1,209 +1 @@
Multibooting Qubes
========================================
Introduction
---------------------
You should think carefully before dual booting Qubes on your box.
Read the [guidelines](https://www.qubes-os.org/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](https://www.qubes-os.org/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
~~~
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

232
docs/configuration/multimedia.md
View file

@ -1,231 +1 @@
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=0x8fd3d9a8d3800305a9fff259d1742ad60d811d58>
- 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 --keyid-format long --with-fingerprint spotify.pubkey`
This should look like:
[user@t-multimedia ~]$ gpg --keyid-format long --with-fingerprint spotify.pubkey
gpg: WARNING: no command supplied. Trying to guess what you mean ...
pub rsa4096/D1742AD60D811D58 2020-09-08 [SC] [expires: 2021-12-02]
Key fingerprint = 8FD3 D9A8 D380 0305 A9FF F259 D174 2AD6 0D81 1D58
uid Spotify Public Repository Signing Key <tux@spotify.com>
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 --keyid-format long --with-fingerprint videolan.pubkey`
This should look like:
[user@t-multimedia ~]$ gpg --keyid-format long --with-fingerprint videolan.pubkey
gpg: WARNING: no command supplied. Trying to guess what you mean ...
pub rsa2048/6BCA5E4DB84288D9 2013-08-27 [SC]
Key fingerprint = 8F08 45FE 77B1 6294 429A 7934 6BCA 5E4D B842 88D9
uid VideoLAN APT Signing Key <videolan@videolan.org>
sub rsa2048/ED1466D0288D4A2C 2013-08-27 [E]
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 --keyid-format long --with-fingerprint google.pubkey`
This should look like:
[user@t-multimedia ~]$ gpg --keyid-format long --with-fingerprint videolan.pubkey
gpg: WARNING: no command supplied. Trying to guess what you mean ...
pub rsa4096/7721F63BD38B4796 2016-04-12 [SC]
Key fingerprint = EB4C 1BFD 4F04 2F6D DDCC EC91 7721 F63B D38B 4796
uid Google Inc. (Linux Packages Signing Authority) <linux-packages-keymaster@google.com>
sub rsa4096/1397BC53640DB551 2016-04-12 [S] [expired: 2019-04-12]
sub rsa4096/6494C6D6997C215E 2017-01-24 [S] [expired: 2020-01-24]
sub rsa4096/78BD65473CB3BD13 2019-07-22 [S] [expires: 2022-07-21]
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`
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

218
docs/configuration/mutt.md
View file

@ -1,217 +1 @@
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](https://www.qubes-os.org/doc/postfix/) or Exim and MRA such as
[Fetchmail](https://www.qubes-os.org/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](https://www.qubes-os.org/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
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

138
docs/configuration/network-bridge-support.md
View file

@ -1,137 +1 @@
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...
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

48
docs/configuration/network-printer.md
View file

@ -1,47 +1 @@
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](https://www.qubes-os.org/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).
You may need to install it first `sudo dnf install system-config-printer`.
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.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

147
docs/configuration/postfix.md
View file

@ -1,146 +1 @@
Postfix
=======
Postfix is full featured MTA (Message Transfer Agent). Here we will configure it in smarthost mode as part of common [Mutt](https://www.qubes-os.org/doc/mutt/)+Postfix+[Fetchmail](https://www.qubes-os.org/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.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

87
docs/configuration/qmenu.md
View file

@ -1,86 +1 @@
Manage Qubes via dmenu; qmenu
==============================
[qmenu](https://github.com/sine3o14nnae/qmenu/) is a collection of tools that utilize
[dmenu](https://tools.suckless.org/dmenu/), a dynamic menu for X, to provide you with a drop down menu for Qubes specific tasks.
When configured to execute these tools via hotkeys, you are able to list, start and stop your qubes, attach and detach your connected devices,
adjust your qube preferences, firewall rules, per-qube keyboard layouts, launch applications and more, very quickly with only the keyboard.
List of qmenu tools:
- qmenu-am - Launch domU and dom0 applications.
- qmenu-dm - List and manage your connected devices.
- qmenu-vm - List, manage and configure your qubes.
Warning
-------
qmenu is **not** included in the Qubes dom0 repositories. This page will show you how to install qmenu by cloning its repository
to a disposable qube and [copying its contents to dom0](https://www.qubes-os.org/doc/copy-from-dom0/#copying-to-dom0).
**However, this way of installing software in dom0 is not advised and can compromise the security of your system!**
**Furthermore, qmenu is unreviewed third party software and is in no way endorsed by the Qubes team. You have to trust its maintainers
to not act maliciously and to protect it from malicious and unsafe contributions. Keep in mind that you are
installing these tools in _dom0_, so judge accordingly.**
Installation
------------
- Install dmenu:
[user@dom0 ~]$ sudo qubes-dom0-update dmenu
- Start a disposable qube that is able to connect to the internet. **Do not use this qube for anything else!**
Then inside this qube; clone the qmenu repository with git:
[user@dispXXXX ~]$ git clone https://github.com/sine3o14nnae/qmenu/
- Import the authors public key:
[user@dispXXXX ~]$ gpg2 --keyserver pool.sks-keyservers.net --recv-keys 0xCBE6 0BC2 811F FE14 333F EE05 3435 0BCA 3DDE 9AD9
- Check the validity of the signed commit:
[user@dispXXXX ~/qmenu/]$ git show --show-signature
- Finally, decide what qmenu tools you want to use, replace 'XX' accordingly, then copy them to dom0, place them
inside your path and change their mode bits.
[user@dom0 ~]$ qvm-run --pass-io --filter-escape-chars --no-color-output dispXXXX 'cat /home/user/qmenu/qmenu-XX' > /tmp/qmenu-XX
[user@dom0 ~]$ sudo cp /tmp/qmenu-XX /usr/local/bin/
[user@dom0 ~]$ sudo chmod 755 /usr/local/bin/qmenu-XX
- For `qmenu-vm`, you have to additionally follow the steps below to copy all the files in /home/user/qmenu/lib/qmenu_vm/ to dom0 and place them in /lib/qmenu_vm/.
[user@dom0 ~]$ mkdir /tmp/qmenu_vm
[user@dom0 ~]$ for file in fq_keyboard fq_logs fq_pm fqubes_prefs fqvm_appmenus fqvm_clone fqvm_create fqvm_device fqvm_firewall fqvm_pci fqvm_prefs fqvm_remove fqvm_run fqvm_service fqvm_tags fqvm_volume; do qvm-run --pass-io --filter-escape-chars --no-color-output dispXXXX "cat /home/user/qmenu/lib/qmenu_vm/$file" > /tmp/qmenu_vm/$file; done
[user@dom0 ~]$ sudo cp -r /tmp/qmenu_vm/ /lib/
Customization
-------------
### qmenu ###
The colors that correspond to a qube label can be adjusted by appending `--{LABEL}=#{HEX VALUE}`
for any qube label, when executing a qmenu tool.
Try the following example for visually appealing colors:
~~~
--purple=#a020f0 --blue=#4363d8 --gray=#bebebe --green=#3cb44b --yellow=#ffe119 --orange=#f58231 --red=#e6194b --black=#414141
~~~
### dmenu ###
In order to customize and configure dmenu, instead of downloading it from the repositories,
you have to get it from [suckless](https://tools.suckless.org/dmenu/), compile it yourself
and [copy it to dom0](https://www.qubes-os.org/doc/copy-from-dom0/#copying-to-dom0).
**However, this way of installing software in dom0 is not advised and can compromise the security of your system!**
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

144
docs/configuration/rxvt.md
View file

@ -1,143 +1 @@
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.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

106
docs/configuration/screen-share.md
View file

@ -1,105 +1 @@
How to Share A Screen Across Qubes
==================================
> Warning:
> This guide involves opening up a TCP port between qubes. This is discouraged from the security standpoint and should only be used as a last resort, use sparingly.
## Terminology
PRESENTATION_QUBE is the Qube you want to view the screen from
CONTENT_QUBE is the Qube that has the window you want to share
## Setup The Shared Screen Server
Choose one of these sub-sections depending on whether you want to open a new screen (increased isolation), or use an existing monitor or screen.
### If You Want To Share a New Screen
In the Content Qube:
1. Install packages `sudo apt install xfwm4 tigervnc-standalone-server tigervnc-viewer` or `sudo dnf install xfwm4 tigervnc-server tigervnc`
2. Enter the password by executing `vncpasswd`
1. You can generate secure enough passwords for this purpose using `openssl rand -base64 16 | tr -d '+/=' | head -c 8;echo`
2. Enter one password for read/write (first password and verify prompt)
3. Enter a different password for the view only password (second password and verify prompt)
3. Start the server `vncserver :1 -xstartup /usr/bin/xfwm4 -geometry 1920x1080 -localhost no`
4. View the shared screen `vncviewer -passwd ~/.vnc/passwd :1`
5. Open applications `DISPLAY=:1 xterm` where xterm can be any binary on your system
## If You Want To Share an Existing Monitor or Window
In the Content Qube:
1. Install packages `sudo apt install xfwm4 x11vnc x11-utils` or `sudo dnf install xfwm4 x11vnc xwininfo`
2. Enter the password by executing `x11vnc -storepasswd`
1. You can generate secure enough passwords for this purpose using `openssl rand -base64 16 | tr -d '+/=' | head -c 8;echo`
3. Start the server
1. If you want to share a window `x11vnc -viewonly -rfbauth ~/.vnc/passwd -rfbport 5901 -clip 1920x1080+0+0`
- Replace `1920x1080+0+0` with the resolution (e.g. `1920x1080`) and offset (e.g. `+0+0`) of the screen area you want to share. The coordinates 0,0 are in the top left, increasing down and to the right.
- Use `xrandr --listactivemonitors` in Dom0 to get a list of all monitors and their offsets. That command returns in the form `W/_xH/_+X+Y`. For example to share DP-1, with xrandr output of ` 0: +DP-1 1920/510x1080/287+1280+0 DP-1`, 1920x1080+1280+0 would share just that screen.
- `arandr` is a useful graphical tool to show where all the monitors are in relation to each other.
2. If you want to share a monitor `x11vnc -viewonly -rfbauth ~/.vnc/passwd -rfbport 5901 -id pick`
- This retrieves the numerical id of the next window you click on.
3. If you want to share all the monitors use `x11vnc -viewonly -rfbauth ~/.vnc/passwd -rfbport 5901`
4. View the shared screen as specified in "View The Shared Screen"
5. Open applications like normal
## Qubes Connect TCP Service
These steps are a simpler version of [The Qubes Firewall](https://www.qubes-os.org/doc/firewall/#opening-a-single-tcp-port-to-other-network-isolated-qube). In dom0 execute these steps:
1. Edit /etc/qubes-rpc/policy/qubes.ConnectTCP
2. Add the line: `<PRESENTATION_QUBE> @default ask,target=<CONTENT_QUBE>`
- (recommended) By specifying `ask`, dom0 will ask each time a connection is attempted on that port
- (not recommended) Rather than specifying `ask` you can use `allow` to allow all connections without a prompt, this leaves you unaware of new attempted connections.
3. After you are done sharing you screen, remove this line to prevent further unwanted connections
## View The Shared Screen
In the Presentation Qube:
1. Install package `sudo apt install -y tigervnc-viewer`
2. Bind TCP port using Qubes Connect TCP service `qvm-connect-tcp ::5901`
3. Start the VNC Viewer `vncviewer -Shared -ViewOnly -RemoteResize=0 -SendPrimary=0 -SendClipboard=0 -SetPrimary=0 127.0.0.1:5901`
4. Confirm that you want to connect to the Presentation Qube in the dom0 prompt
5. Enter password for the VNC server you created above
6. In your presentation software share the VNC viewer
## Present
In the Content Qube interact with the shared screen, the changes will be mirrored back to your Presentation Qube.
## Notes
- To reset the VNC password delete `~/.vnc/passwd` in the Content Qube
- The Content Qube does not need to have access to the internet
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

99
docs/configuration/shrink-volumes.md
View file

@ -1,98 +1 @@
Shrinking volumes
=================
The procedure for shrinking a volume on Ext4 and most other filesystems is bit convoluted because online shrinking isn't supported and we don't want to process any untrusted data in dom0 for security reasons.
**Shrinking volumes is dangerous** and this is why it isn't available in standard Qubes tools. If you have enough disk space, the recommended approach is to create a new VM with a smaller disk and move the data. However, this approach has two caveats:
- it requires copying data, which can take a while
- it is limited to the private volume of VMs based on TemplateVMs
**ALWAYS BACKUP your data before attempting to shrink a volume.**.
Qubes 4.0 (root and private volumes)
------------------------------------
Qubes 4.0 uses *thin* LVM storage: only the data present on a volume uses disk space, free space isn't allocated physically. If your only concern is disk space, you may simply be careful with how much data you store in a given volume and avoid having to shrink a volume (use `sudo lvs` in dom0 and compare the `LSize` vs `Data%` fields to find out about real disk usage).
The instructions below show how to resize a Linux VM's private volume. For root volumes, swap the `-private` volume suffix with `-root`. For other OSes (eg. MS Windows) you'll have to use the OS' specific tools to resize the volume at step 4 instead of `resize2fs`, and to be careful to specify the right shrinked size at step 6.
1. backup your data with `qvm-clone` , `qvm-backup`, or your own backup mechanism. Do not rely only on snapshots (yet)
2. stop the VM (eg. 'largeVM') whose volume has to be resized
3. start another VM (eg. 'tempVM') with largeVM's private volume attached:
~~~
qvm-start --hddisk dom0:/dev/qubes_dom0/vm-largeVM-private tempVM
~~~
Alternatively, you could setup a loop device in dom0 associated to largeVM's private volume and attach it to a running VM but this is outside the scope of this document (see `losetup` and `qvm-block`).
4. in tempVM, resize the attached volume:
~~~
sudo e2fsck -f /dev/xvdi
sudo resize2fs /dev/xvdi <newsize>
~~~
(eg. `<newsize>` = `2G` ; see `man resize2fs` for allowed formats).
5. shutdown tempVM
6. in dom0, resize the lvm volume to the **SAME** size you used at step 4. (specifying a lower size than the underlying filesystem's size **will corrupt** the filesystem and either destroy some of your data or trigger filesystem exceptions when the filesystem tries to write at a location that doesn't exist):
~~~
sudo lvresize -L<newsize> /dev/qubes_dom0/vm-largeVM-private
~~~
Qubes 3.2 (Linux VMs, private image only)
-----------------------------------------
First you need to start VM without `/rw` mounted. One possibility is to interrupt its normal startup by adding the `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 the `resize2fs` call. Otherwise **you will lose your data!**.
Then reset kernel options back to default:
~~~
qvm-prefs -s <vm-name> kernelopts default
~~~
Done.
In order to avoid errors, you might want to first reduce the filesystem to a smaller size than desired (say 3G), then truncate the image to the target size (for example 4G), and lastly grow the filesystem to the target size. In order to do this, after the `truncate` step, start the vm again in maintenance mode and use the following command to extend the filesystem to the correct size:
~~~
resize2fs /dev/xvdb
~~~
With no argument, `resize2fs` grows the filesystem to match the underlying block device (the .img file you just shrunk).
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

410
docs/configuration/split-ssh.md
View file

@ -1,409 +1 @@
# Qubes Split SSH
Split SSH implements a concept similar to having a smart card with your private SSH keys, except that the role of the “smart card” is played by another Qubes AppVM.
This Qubes setup allows you to keep your SSH private keys in a vault VM (`vault`) while using an SSH Client VM (`ssh-client`) to access your remote server.
This is done by using Qubes's [qrexec][qrexec] framework to connect a local SSH Agent socket from your SSH Client VM to the SSH Agent socket within the vault VM.
This way the compromise of the domain you use to connect to your remote server does not allow the attacker to automatically also steal all your keys.
(We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
![diagram](/attachment/wiki/split-ssh/diagram.svg)
## Security Benefits
In the setup described in this guide, even an attacker who manages to gain access to the `ssh-client` VM will not be able to obtain the user’s private key since it is simply not there.
Rather, the private key remains in the `vault` VM, which is extremely unlikely to be compromised if nothing is ever copied or transferred into it.
In order to gain access to the vault VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a signed, compromised package which is already installed in the TemplateVM upon which the vault VM is based.
## Overview
1. Make sure the TemplateVM you plan to use is up to date.
2. Create `vault` and `ssh-client` AppVMs.
3. Create an ssh key in your `vault` AppVM and set up automatic key adding prompt.
4. Set up VM interconnection
5. (Strongly Encouraged) Create a KeePassXC Database and set up SSH Agent Integration in KeePassXC.
## Preparing your system
Make sure the templates you plan to base your AppVMs on are [up-to-date][update].
## [Creating AppVMs][appvm create]
If you’ve installed Qubes OS using the default options, a few qubes including a vault AppVM has been created for you.
Skip the first step if you don't wish to create another vault.
1. Create a new vault AppVM (`vault`) based on your chosen template. Set networking to `(none)`.
![vault creation](/attachment/wiki/split-ssh/vault-creation.png)
2. Create a SSH Client AppVM (`ssh-client`). This VM will be used to make SSH connections to your remote machine.
![ssh-client creation](/attachment/wiki/split-ssh/client-creation.png)
## Setting up SSH
Install `ssh-askpass` in the template of your `vault` VM. It will be
used by `ssh-agent` to ask for confirmation, for keys added using
`ssh-add -c`.
For Fedora templates:<br/>
```
sudo dnf install openssh-askpass
```
For Debian templates:<br/>
```
sudo apt-get install ssh-askpass-gnome
```
Perform the next steps in the AppVM `vault`.
1. Generate an SSH key pair.
Skip this step if you already have your keys.
Note that it is *okay* to not enter a password for your private keys since the `vault` AppVM has no networking.
If you still want to encrypt your keys you must refer to the [Securing Your Private Key](#securing-your-private-key) section.
```shell_prompt
[user@vault ~]$ ssh-keygen -t ed25519 -a 500
Generating public/private ed25519 key pair.
Enter file in which to save the key (/home/user/.ssh/id_ed25519):
Created directory '/home/user/.ssh'.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/user/.ssh/id_ed25519
Your public key has been saved in /home/user/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:DBxSxZcp16d1NSVSid3m8HRipUDM2INghQ4Sx3jPEDo user@vault
The key's randomart image is:
+--[ED25519 256]--+
| o==+++.@++o=*|
| o==o+ B BoOoB|
| Eoo* + *.O.|
| . o+ . o|
| S |
| |
| |
| |
| |
+----[SHA256]-----+
```
**-t**: type<br/>
**-a**: num_trials<br/>
Please note that the key fingerprint and the randomart image will differ.
For more information about `ssh-keygen`, run `man ssh-keygen`.
**Notice:** Skip the following steps if you plan on using KeePassXC.
2. Make a new directory `~/.config/autostart`
```
mkdir -p ~/.config/autostart
```
3. Create the file `~/.config/autostart/ssh-add.desktop`
- Open the file with e.g. `gedit`
```
gedit ~/.config/autostart/ssh-add.desktop
```
- Paste the following contents:
```shell_prompt
[Desktop Entry]
Name=ssh-add
Exec=ssh-add -c
Type=Application
```
**Note:** If you've specified a custom name for your key using *-f*, you should adjust `Exec=ssh-add -c` to `Exec=ssh-add -c <path-to-your-key-file>` (the path must be absolute, e.g. `/home/user/.ssh/my_key`).
## Setting Up VM Interconnection
### In `dom0`:
To control which VM is allowed as a client, which may act as the server and how we want this interaction to happen, we have to write a policy file for qrexec in `dom0`.
1. Create and edit `/etc/qubes-rpc/policy/qubes.SshAgent`.
- Open the file with e.g. `nano`.
```
sudo nano /etc/qubes-rpc/policy/qubes.SshAgent
```
- If you want to explicitly allow only this connection, add the following line:
```shell_prompt
ssh-client vault ask
```
- If you want all of your VMs to potentially be an `ssh-client` or a `vault`, add the following line:
```shell_prompt
@anyvm @anyvm ask
```
- If you want the input field to be "prefilled" by your `vault` VM, append `default_target=vault` so it looks like for example:
```shell_prompt
@anyvm @anyvm ask,default_target=vault
```
**Note:** There are many ways to fine-tune this policy. For more details see the [Qubes qrexec documentation][PolicyFilesQubesOS].
### In the Template of Your AppVM `vault`:
We now need to write a small script that handles connection requests from `ssh-client` and forwards them to the SSH agent in your `vault`. As we are using qrexec as communication method we have to place it in a special location and have to name it just as the policy file we just created in `dom0`.
1. Create and edit `/etc/qubes-rpc/qubes.SshAgent`.
- Open the file with e.g. `gedit`
```shell_prompt
sudo gedit /etc/qubes-rpc/qubes.SshAgent
```
- Paste the following contents:
```shell_prompt
#!/bin/sh
# Qubes App Split SSH Script
# safeguard - Qubes notification bubble for each ssh request
notify-send "[$(qubesdb-read /name)] SSH agent access from: $QREXEC_REMOTE_DOMAIN"
# SSH connection
socat - "UNIX-CONNECT:$SSH_AUTH_SOCK"
```
2. Make it executable
```shell_prompt
sudo chmod +x /etc/qubes-rpc/qubes.SshAgent
```
### In the AppVM `ssh-client`
Theoretically, you can use SSH in any AppVM.
However, if you are considering split-SSH as an additional security layer it is probably reasonable to also think about which VMs you will be using SSH in.
For instance, you might want a dedicated `admin` domain for these purposes.
Depending on how many systems you plan to access and where they are located, it could also be preferable to have different VMs with different firewall rules for Intranet and Internet administration.
We want to make sure that our `ssh-client` is prepared to use split-ssh right after the VM has started.
Therefore, we add a script in `rc.local` (Which will run at VM startup) to listen for responses from `vault` and make SSH use this connection by modifying the user’s `.bashrc`.
1. Edit `/rw/config/rc.local`.
- Open the file with e.g. `gedit`.
```shell_prompt
sudo gedit /rw/config/rc.local
```
- Add the following to the bottom of the file:
```shell_prompt
# SPLIT SSH CONFIGURATION >>>
# replace "vault" with your AppVM name which stores the ssh private key(s)
SSH_VAULT_VM="vault"
if [ "$SSH_VAULT_VM" != "" ]; then
export SSH_SOCK="/home/user/.SSH_AGENT_$SSH_VAULT_VM"
rm -f "$SSH_SOCK"
sudo -u user /bin/sh -c "umask 177 && exec socat 'UNIX-LISTEN:$SSH_SOCK,fork' 'EXEC:qrexec-client-vm $SSH_VAULT_VM qubes.SshAgent'" &
fi
# <<< SPLIT SSH CONFIGURATION
```
2. Edit `~/.bashrc` and add the following to the bottom of the file:
- Open the file with e.g. `gedit`
```shell_prompt
gedit ~/.bashrc
```
- Add the following to the bottom of the file:
```shell_prompt
# SPLIT SSH CONFIGURATION >>>
# replace "vault" with your AppVM name which stores the ssh private key(s)
SSH_VAULT_VM="vault"
if [ "$SSH_VAULT_VM" != "" ]; then
export SSH_AUTH_SOCK="/home/user/.SSH_AGENT_$SSH_VAULT_VM"
fi
# <<< SPLIT SSH CONFIGURATION
```
## Securing Your Private Key
Although passwords wouldn't protect you against a full system compromise (attacker could place a keylogger), it's possible for an adversary to gain read-only access to some of your files (e.g., file shares or offline backups of data).
This becomes even more likely if you plan to also use your data outside of Qubes and not be able to modify anything.
Passwords are advisable for mitigating these threats .
You can either [use the built-in password utility](#using-the-built-in-password-utility) of your private key combined with a graphical prompt or prefer to [use KeePassXC](#using-keepassxc).
Please note that since `ssh-askpass` prompt is displayed on `vault` VM boot, it is not possible to use both configurations simultaneously.
### Using the Built-in Password Utility and `ssh-askpass`
You should have added `ssh-askpass` to your vault template earlier when [setting up SSH](#setting-up-ssh).
1. Either add a password to an existing private key with `ssh-keygen -p` or directly create a key pair with a password (enter password when prompted during the creation process, see [above](#setting-up-ssh)).
Note that the location and name of your private key may differ.
```
[user@vault ~]$ ssh-keygen -p
Enter file in which the key is (/home/user/.ssh/id_rsa): /home/user/.ssh/id_ed25519
Key has comment 'user@vault'
Enter new passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved with the new passphrase.
```
2. Shutdown the template and restart your `vault` VM.
With this configuration you'll be prompted for entering your password every time you start your vault VM to be able to make use of your SSH key.
### Using [KeePassXC][KeePassXC]
**Note:** This part is for setting up *KeePassXC*, not KeePassX or KeePass. See the [KeePassXC FAQ][KeePassXC FAQ].
KeePassXC should be installed by default in both Fedora and Debian TemplateVMs. If it’s not or you're using another template, you can [install it manually](https://www.qubes-os.org/doc/software-update-domu/#installing-software-in-templatevms).
**A note on managing your Qubes domains:** You might already be using KeePassXC to store your passwords. This guide explains how to set up a new KeePass database and use it exclusively for SSH keys. However, it is also possible to mix your passwords and SSH keys in one big database. Others might have dedicated databases for different kinds of passwords, potentially even in different `vault` VMs. There is no right or wrong here. Feel free to skip the first five steps if you want to use an existing database.
1. Add KeepasXC to the Applications menu of the newly created AppVM for ease of access and launch it.
![vault adding keepass](/attachment/wiki/split-ssh/vault-adding-keepass.png)
**Note:** Since the vault VM has no internet connection, you can safely deny automatic updates if prompted.
2. Create a new database.
![create database](/attachment/wiki/split-ssh/create-database.png)
3. Enter a name for your database and continue.
![naming screen](/attachment/wiki/split-ssh/naming-screen.png)
4. Adjust the encryption settings.
Check the [KeePassXC User Guide][KeePassXC User Guide] for more information about these settings.
![encryption settings](/attachment/wiki/split-ssh/encryption-settings.png)
5. Enter a password for your database. Take your time make a secure but also rememberable password. ([hint][Hint])
![password screen](/attachment/wiki/split-ssh/password-screen.png)
6. Add a new entry.
![adding new entry](/attachment/wiki/split-ssh/adding-new-entry.png)
7. Set password to your SSH key passphrase.
![enter passphrase](/attachment/wiki/split-ssh/enter-passphrase.png)
8. Go into the Advanced section and add your keys.
![adding keys](/attachment/wiki/split-ssh/adding-keys.png)
**Note:** Technically, you only need to add the private key (`id_25519`) for the following steps to work. If you add the public key here, too, you can later on backup your kdbx file and have everything in one place. You can even delete your keys (`id_25519` and `id_25519.pub`) from your file system if you like.
9. Enable "SSH Agent Integration" within the Application Settings.
![enable ssh agent integration](/attachment/wiki/split-ssh/enable-ssh-agent-integration.png)
10. Restart KeePassXC
11. Check the SSH Agent Integration status.
![check integration status](/attachment/wiki/split-ssh/check-integration-status.png)
12. Open the entry you created and select your private key in the "SSH Agent" section.
Don't forget to also check the first two options.
![select private key](/attachment/wiki/split-ssh/select-private-key.png)
#### Testing the KeePassXC Setup
1. Close your KeePassXC database and run `ssh-add -L` in a `vault` VM terminal. It should return `The agent has no identities.`
```shell_prompt
[user@vault ~]$ ssh-add -L
The agent has no identities.
```
2. Unlock your KeePassXC database and run `ssh-add -L` again. This time it should return your public key.
```shell_prompt
[user@vault ~]$ ssh-add -L
ssh-ed25519 <public key string> user@vault-keepassxc
```
## Test Your Configuration
1. If you're using KeePassXC, shutdown KeePassXC on your vault VM.
If not, make sure your private key is not added to the ssh-agent in your vault VM (Check with `ssh-add -L`).
If it is, restart your vault VM and do not enter your password when it asks you to.
2. Try fetching your identities on the SSH Client VM.
```shell_prompt
ssh-add -L
```
3. Allow operation execution. (If you don't see the below prompt, check your VM interconnection setup.)
![operation execution](/attachment/wiki/split-ssh/operation-execution.png)
It should return `The agent has no identities.`.
If you're getting an error (e.g. `error fetching identities: communication with agent failed`), make sure your vault VM is running and check your VM interconnection setup.
4. Launch KeePassXC and unlock your database.
5. Repeat steps 1 and 2.
Check if it returns `ssh-ed25519 <public key string>`
If you're getting an error (e.g. `error fetching identities: communication with agent failed`), make sure your vault VM is running and check your VM interconnection setup.
## Current limitations
* It is possible for a malicious VM to hold onto an ssh-agent connection for more than one use.
Therefore, if you authorize usage once, assume that a malicious VM could then use it many more times.
In this case, though, the SSH Agent will continue to protect your private keys; only usage of it would be available to the malicious VM until it is shut down.
* The two actions below should allow the user to know what is requested before the operation gets approved, but has not been fully verified:
* configuring the vault to use `ssh-add -c` as described above
* configuring KeepassXC to "Require user confirmation when this key is used"
Want more Qubes split magic?
Check out [Split-GPG][Split-GPG].
-------------------------------
This guide has been inspired by:<br/>
Qubes Split SSH (Github: Jason Hennessey - henn) https://github.com/henn/qubes-app-split-ssh <br/>
Using split ssh in QubesOS 4.0 (Kushal Das) https://kushaldas.in/posts/using-split-ssh-in-qubesos-4-0.html <br/>
Using Split-SSH in Qubes 4 (Denis Zanin) https://deniszanin.com/using-split-ssh-gpg-in-qubes-os/ <br/>
R.I.S.K.S. https://19hundreds.github.io/risks-workflow/ssh-split-setup <br/>
Contributor(s): @shaaati, @invalid-error, @deeplow, @ephemer4l
[CreateBackup]:https://www.qubes-os.org/doc/backup-restore/#creating-a-backup
[qrexec]: https://www.qubes-os.org/doc/qrexec/
[update]: https://www.qubes-os.org/doc/software-update-domu/#updating-software-in-templatevms
[appvm create]: https://www.qubes-os.org/doc/getting-started/#adding-removing-and-listing-qubes
[PolicyFilesQubesOS]:https://www.qubes-os.org/doc/qrexec/#policy-files
[Split-GPG]:https://www.qubes-os.org/doc/split-gpg
[KeePassXC]: https://keepassxc.org/project
[KeePassXCFedoraPackageSource]:https://src.fedoraproject.org/rpms/keepassxc
[KeePassXC download page]: https://keepassxc.org/download/
[KeePassXC FAQ]: https://keepassxc.org/docs
[KeePassXC User Guide]: https://keepassxc.org/docs/KeePassXC_UserGuide.html#_database_settings
[Hint]:https://xkcd.com/936
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

51
docs/configuration/tips-and-tricks.md
View file

@ -1,50 +1 @@
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](https://www.qubes-os.org/doc/security-guidelines/) and [security goals](https://www.qubes-os.org/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](https://www.qubes-os.org/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)
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

317
docs/configuration/vpn.md
View file

@ -1,316 +1 @@
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-server@.service
sudo systemctl disable openvpn-client@.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
# Restart the VPN automatically
sleep 5s
sudo /rw/config/rc.local
;;
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'
groupadd -rf qvpn ; sleep 2s
sg qvpn -c "$VPN_CLIENT $VPN_OPTIONS"
su - -c 'notify-send "$(hostname): Starting $VPN_CLIENT..." --icon=network-idle' user
~~~
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](https://www.qubes-os.org/doc/software-update-domu/#updates-proxy).
Troubleshooting
---------------
See the [VPN Troubleshooting](https://www.qubes-os.org/doc/vpn-troubleshooting/) guide for tips on how to fix common VPN issues.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

32
docs/configuration/w3m.md
View file

@ -1,31 +1 @@
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?
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

189
docs/configuration/zfs.md
View file

@ -1,188 +1 @@
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)
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)

70
docs/configuration/zoom_dispvm.md
View file

@ -1,69 +1 @@
# Running Zoom in a DispVM
## Intro
Zoom is a fairly widely-used video conferencing application that runs on a variety of platforms. In this guide we will go through the process of setting up a Disposable VM for Zoom.
### Why we will use a DispVM
By running Zoom alone in a Disposable VM, we can improve the safety of using the application. DispVMs ensure that even if a Zoom exploit leads to the entire DispVM being compromised, it is *contained* to the DispVM which is destroyed once you shutdown the Qube or exit Zoom. No persistence, limited attack surface, and zero trust.
## Step 0: Clone a TemplateVM
1. Open `Qubes Manager`
2. Right-click on the `debian-10` TemplateVM
3. Click `Clone Qube`
4. Name the cloned qube `videoconferencing`
*Alternatively:*
1. Open Terminal Emulator in dom0
2. Clone the `debian-10` template to new template `videoconferencing`:
`qvm-clone --verbose debian-10 videoconferencing`
## Step 1: Download Zoom for Debian 8.0+ 64-bit
### Download and import Zoom's signing key:
1. Open `Xfce Terminal` from `whonix-ws-15-dvm` **Make a note of the Qube name in the title. This will be used in step 2.**
2. Download Zoom's GPG key using wget:
`wget "https://zoom.us/linux/download/pubkey"`
3. Import Zoom's Public Key:
`gpg --import pubkey`
### Download and verify Zoom, then copy to TemplateVM:
1. Download Zoom using `wget`:
`wget "https://zoom.us/client/latest/zoom_amd64.deb"`
2. Verify `zoom_amd64.deb`:
* `sudo apt install -y dpkg-sig`: `Install dpkg-sig` so we can verify `zoom_amd64.deb`
* `dpkg-sig zoom_amd64.deb`: Verify `zoom_amd64.deb`.
* Expected output should include indicate a good signature, for example here's what I got running the command:
`GOODSIG _gpgbuilder 396060CADD8A75220BFCB369B903BF1861A7C71D 1590375377`
3. Copy `zoom_amd64.deb` to TemplateVM `videoconferencing`:
`qvm-copy zoom_amd64.deb`
4. Select the `videoconferencing` TemplateVM as the destination to copy `zoom_amd64.deb` to.
5. Shutdown the TemplateVM:
`sudo shutdown now`
## Step 2: Install Zoom in TemplateVM
### Install Zoom in the `videoconferencing` TemplateVM:
1. Open `Terminal` from TemplateVM `videoconferencing`
2. Check QubesIncoming folder contents:
`ls QubesIncoming`
3. You should see a folder with the same name as the Qube name in the title from the end of step 2. **In the following example, the Qube name was disp6247.**
4. Change directory to the location of `zoom_amd64.deb`:
`cd ~/QubesIncoming/disp6247/`
5. Install Zoom using `apt-get`:
`sudo apt-get install -y ./zoom_amd64.deb`
6. Shutdown the TemplateVM
`sudo shutdown now`
## Step 3: Create an AppVM for Zoom
1. Open `Create Qubes VM`.
2. Name the Qube `videoconferencing-dvm` and label it `red` to indicate the lowest level of trust.
3. Select `AppVM` as the type of qube to be created. *This is the default.*
4. Select `videoconferencing` as the template for the AppVM Qube.
5. Choose `sys-firewall` for networking.
6. Click `OK`.
## Step 4: Add Zoom to the AppVM's list of applications & enable DispVM
1. Open `Qube Manager`
2. `Search` for the `videoconferencing` TemplateVM. Right-click it and select `Qube Settings`
3. Click the `Applications` tab.
4. Click `Zoom` to highlight it, then click the `>` button to add it to the AppVM's application list.
5. Click the `Advanced` tab.
6. Under the `Other` section, check the box labeled `Disposable VM Template`
7. Click `OK`.
This content has moved to [Qubes Forum: Community Guides](https://forum.qubes-os.org/c/guides/14). [Learn more.](https://forum.qubes-os.org/t/announcement-qubes-community-project-has-been-migrated-to-the-forum/20367/)