Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2025-07-24 15:25:47 -04:00
Code Issues Projects Releases Packages Wiki Activity

Update and reorganize documentation

Browse source 
- Convert "Common Tasks" to "How-to Guides"
  (QubesOS/qubes-issues#6694)
- Make title capitalization consistent across docs
- Fix leftover h1 headings
- Reorganize various pages and topics
- Update permalinks to better match titles
- Create redirects for changed permalinks
- Miscellaneous cleanup

QubesOS/qubes-issues#6701
This commit is contained in:
Andrew David Wong 2021-06-17 04:23:57 -07:00
parent 12408884dd
commit 6d81f95cc2
No known key found for this signature in database
GPG key ID: 8CE137352A019A17
73 changed files with 101 additions and 107 deletions
Download patch file Download diff file Expand all files Collapse all files

191
user/advanced-topics/awesome.md Normal file
View file

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

106
user/advanced-topics/bind-dirs.md Normal file
View file

@ -0,0 +1,106 @@
---
lang: en
layout: doc
permalink: /doc/bind-dirs/
redirect_from:
- /en/doc/bind-dirs/
ref: 186
title: How to Make Any File Persistent (bind-dirs)
---
## What are bind-dirs? ##
With [bind-dirs](https://github.com/QubesOS/qubes-core-agent-linux/blob/master/vm-systemd/bind-dirs.sh)
any arbitrary files or folders can be made persistent in TemplateBasedVMs.
## What is it useful for? ##
In a TemplateBasedVM all of the file system comes from the template except `/home`, `/usr/local`, and `/rw`.
This means that changes in the rest of the filesystem are lost when the TemplateBasedVM is shutdown.
bind-dirs provides a mechanism whereby files usually taken from the template can be persisted across reboots.
For example, in Whonix, [Tor's data dir `/var/lib/tor` has been made persistent in the TemplateBased ProxyVM sys-whonix](https://github.com/Whonix/qubes-whonix/blob/8438d13d75822e9ea800b9eb6024063f476636ff/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf#L5)
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a StandaloneVM.
## How to use bind-dirs.sh? ##
In this example, we want to make `/var/lib/tor` persistent.
Inside the TemplateBasedVM.
1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists.
```
sudo mkdir -p /rw/config/qubes-bind-dirs.d
```
2. Create a file `/rw/config/qubes-bind-dirs.d/50_user.conf` with root rights.
3. Edit the file 50_user.conf to append a folder or file name to the `binds` variable.
```
binds+=( '/var/lib/tor' )
```
4. Save.
5. Reboot the TemplateBasedVM.
6. Done.
From now on any files within the `/var/lib/tor` folder will persist across reboots.
You can make make many files or folders persist, simply by making multiple entries in the `50_user.conf` file, each on a separate line.
For example, if you added the file `/etc/tor/torrc` to the `binds` variable, any modifications to *that* file will persist across reboots.
```
binds+=( '/var/lib/tor' )
binds+=( '/etc/tor/torrc' )
```
## Other Configuration Folders ##
* `/usr/lib/qubes-bind-dirs.d` (lowest priority, for packages)
* `/etc/qubes-bind-dirs.d` (intermediate priority, for template wide configuration)
* `/rw/config/qubes-bind-dirs.d` (highest priority, for per VM configuration)
## How does it work? ##
bind-dirs.sh is called at startup of a TemplateBasedVM, and configuration files in the above configuration folders are parsed to build a bash array.
Files or folders identified in the array are copied to `/rw/bind-dirs` if they do not already exist there, and are then bind mounted over the original files/folders.
Creation of the files and folders in `/rw/bind-dirs` should be automatic the first time the TemplateBasedVM is restarted after configuration.
If you want to circumvent this process, you can create the relevant file structure under `/rw/bind-dirs` and make any changes at the same time that you perform the configuration, before reboot.
Note that you must create the full folder structure under `/rw/bind-dirs` - e.g you would have to create `/rw/bind-dirs/var/lib/tor`
## Limitations ##
* Files that exist in the TemplateVM root image cannot be deleted in the TemplateBasedVMs root image using bind-dirs.sh.
* Re-running `sudo /usr/lib/qubes/init/bind-dirs.sh` without a previous `sudo /usr/lib/qubes/init/bind-dirs.sh umount` does not work.
* Running `sudo /usr/lib/qubes/init/bind-dirs.sh umount` after boot (before shutdown) is probably not sane and nothing can be done about that.
* Many editors create a temporary file and copy it over the original file. If you have bind mounted an individual file this will break the mount.
Any changes you make will not survive a reboot. If you think it likely you will want to edit a file, then either include the parent directory in bind-dirs rather than the file, or perform the file operation on the file in `/rw/bind-dirs`.
* Some files are altered when a qube boots - e.g. `/etc/hosts`.
If you try to use bind-dirs on such files you may break your qube in unpredictable ways.
You can add persistent rules to `/etc/hosts` using [`/rw/config/rc.local`](/doc/config-files)
## How to remove binds from bind-dirs.sh? ##
`binds` is actually just a bash variable (an array) and the bind-dirs.sh configuration folders are sourced as bash snippets in lexical order.
Therefore if you wanted to remove an existing entry from the `binds` array, you could do that by using a lexically higher configuration file.
For example, if you wanted to make `/var/lib/tor` non-persistent in `sys-whonix` without manually editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf`, you could use the following in:
`/rw/config/qubes-bind-dirs.d/50_user.conf`
~~~
binds=( "${binds[@]/'/var/lib/tor'}" )
~~~
(Editing `/usr/lib/qubes-bind-dirs.d/40_qubes-whonix.conf` directly is strongly discouraged, since such changes get lost when that file is changed in the package on upgrades.)
## Discussion ##
[TemplateBasedVMs: make selected files and folders located in the root image persistent- review bind-dirs.sh](https://groups.google.com/forum/#!topic/qubes-devel/tcYQ4eV-XX4/discussion)

147
user/advanced-topics/config-files.md Normal file
View file

@ -0,0 +1,147 @@
---
lang: en
layout: doc
permalink: /doc/config-files/
redirect_from:
- /en/doc/config-files/
- /doc/ConfigFiles/
- /doc/UserDoc/ConfigFiles/
- /wiki/UserDoc/ConfigFiles/
ref: 180
title: Config Files
---
Qubes-specific VM config files
------------------------------
These files are placed in `/rw`, which survives a VM restart.
That way, they can be used to customize a single VM instead of all VMs based on the same template.
The scripts here all run as root.
- `/rw/config/rc.local` - script runs at VM startup.
Good place to change some service settings, replace config files with its copy stored in `/rw/config`, etc.
Example usage:
~~~
# Store bluetooth keys in /rw to keep them across VM restarts
rm -rf /var/lib/bluetooth
ln -s /rw/config/var-lib-bluetooth /var/lib/bluetooth
~~~
~~~
# Add entry to /etc/hosts
echo '127.0.0.1 example.com' >> /etc/hosts
~~~
- `/rw/config/qubes-ip-change-hook` - script runs in NetVM after every external IP change and on "hardware" link status change.
- In ProxyVMs (or AppVMs with `qubes-firewall` service enabled), scripts placed in the following directories will be executed in the listed order followed by `qubes-firewall-user-script` at start up.
Good place to write custom firewall rules.
~~~
/etc/qubes/qubes-firewall.d
/rw/config/qubes-firewall.d
/rw/config/qubes-firewall-user-script
~~~
- `/rw/config/suspend-module-blacklist` - list of modules (one per line) to be unloaded before system goes to sleep.
The file is used only in a VM with PCI devices attached.
Intended for use with problematic device drivers.
- In NetVMs/ProxyVMs, scripts placed in `/rw/config/network-hooks.d` will be ran when configuring Qubes interfaces. For each script, the `command`, `vif`, `vif_type` and `ip` is passed as arguments (see `/etc/xen/scripts/vif-route-qubes`). For example, consider a PV AppVM `work` with IP `10.137.0.100` and `sys-firewall` as NetVM. Assuming it's Xen domain id is arbitrary `12` then, the following script located at `/rw/config/network-hooks.d/hook-100.sh` in `sys-firewall`:
~~~
#!/bin/bash
command="$1"
vif="$2"
vif_type="$3"
ip="$4"
if [ "$ip" == '10.137.0.100' ]; then
case "$command" in
online)
ip route add 192.168.0.100 via 10.137.0.100
;;
offline)
ip route del 192.168.0.100
;;
esac
fi
~~~
will be executed with arguments `online vif12.0 vif 10.137.0.100` when starting `work`. Please note that in case of an HVM, the script will be called twice - once with vif_type `vif`, then with vif_type `vif_ioemu` (and different interface names). As long as the ioemu interface exists, it should be preferred (up to the hook script). When the VM decides to use a PV interface (vif_type `vif`), the ioemu one will be unplugged.
Note that scripts need to be executable (`chmod +x`) to be used.
Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an AppVM and have those changes persist.
GUI and audio configuration in dom0
-----------------------------------
The GUI configuration file `/etc/qubes/guid.conf` in one of a few not managed by `qubes-prefs` or the Qubes Manager tool.
Sample config (included in default installation):
~~~
# Sample configuration file for Qubes GUI daemon
# For syntax go https://www.hyperrealm.com/libconfig/libconfig_manual.html
global: {
# default values
#allow_fullscreen = false;
#override_redirect_protection = true;
#allow_utf8_titles = false;
#secure_copy_sequence = "Ctrl-Shift-c";
#secure_paste_sequence = "Ctrl-Shift-v";
#windows_count_limit = 500;
#audio_low_latency = true;
#log_level = 1;
#trayicon_mode = "border1";
#startup_timeout = 45;
};
# most of setting can be set per-VM basis
VM: {
work: {
allow_utf8_titles = true;
};
video-vm: {
allow_fullscreen = true;
};
};
~~~
Currently supported settings:
- `allow_fullscreen` - allow VM to request its windows to go fullscreen (without any colorful frame).
**Note:** Regardless of this setting, you can always put a window into fullscreen mode in Xfce4 using the trusted window manager by right-clicking on a window's title bar and selecting "Fullscreen".
This functionality should still be considered safe, since a VM window still can't voluntarily enter fullscreen mode.
The user must select this option from the trusted window manager in dom0.
To exit fullscreen mode from here, press `alt` + `space` to bring up the title bar menu again, then select "Leave Fullscreen".
- `allow_utf8_titles` - allow the use of UTF-8 in window titles; otherwise, non-ASCII characters are replaced by an underscore.
- `secure_copy_sequence` and `secure_paste_sequence` - key sequences used to trigger secure copy and paste.
- `audio_low_latency` - force low-latency audio mode (about 40ms compared to 200-500ms by default).
Note that this will cause much higher CPU usage in dom0. It's enabled by
default, disabling it may save CPU in dom0.
- `trayicon_mode` - defines the trayicon coloring mode. Options are
- `bg` - color full icon background to the VM color
- `border1` - add 1px border at the icon edges
- `border2` - add 1px border 1px from the icon edges
- `tint` - tinttint icon to the VM color, can be used with additional
modifiers (you can enable multiple of them)
- `tint+border1,tint+border2` - same as tint, but also add a border
- `tint+saturation50` - same as tint, but reduce icon saturation by 50%
- `tint+whitehack` - same as tint, but change white pixels (0xffffff) to
almost-white (0xfefefe)
- `log level` - defines the log options logs can take. It can
have a value of 0 (only errors), 1 (some basic messages), and 2 (debug).
- `startup_timeout` - The timeout for startup.

385
user/advanced-topics/disposablevm-customization.md Normal file
View file

@ -0,0 +1,385 @@
---
lang: en
layout: doc
permalink: /doc/disposablevm-customization/
redirect_from:
- /doc/dispvm-customization/
- /en/doc/dispvm-customization/
- /doc/DispVMCustomization/
- /doc/UserDoc/DispVMCustomization/
- /wiki/UserDoc/DispVMCustomization/
ref: 174
title: DisposableVM Customization
---
## Introduction
A [DisposableVM](/doc/disposablevm) can be based on any [TemplateBasedVM](/doc/glossary/#templatebasedvm).
You can also choose to use different [DisposableVM Templates](/doc/glossary/#disposablevm-template) for different DisposableVMs.
To prepare an AppVM to be a DisposableVM Template, you need to set `template_for_dispvms` property, for example:
```shell_session
[user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True
```
Additionally, if you want to have menu entries for starting applications in DisposableVM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature:
```shell_session
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
```
Note: application shortcuts that existed before setting this feature will not be updated automatically. Please go the the "Applications" tab in the qube's "Settings" dialog and unselect all existing shortcuts by clicking "<<", then click "OK" and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See [this page](/doc/managing-appvm-shortcuts) for background information.
## Security
If a DisposableVM Template becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important DisposableVM Templates.
In particular, the *default* DisposableVM Template is important because it is used by the "Open in DisposableVM" feature.
This means that it will have access to everything that you open with this feature.
For this reason, it is strongly recommended that you base the default DisposableVM Template on a trusted TemplateVM and refrain from making any risky customizations to it.
## Creating a new DisposableVM Template
In Qubes 4.0, you're no longer restricted to a single DisposableVM Template. Instead, you can create as many as you want. Whenever you start a new DisposableVM, you can choose to base it on whichever DisposableVM Template you like.
To create new DisposableVM Template, lets say `custom-disposablevm-template`, based on `debian-9` template, use following commands:
```shell_session
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposablevm-template
[user@dom0 ~]$ qvm-prefs custom-disposablevm-template template_for_dispvms True
[user@dom0 ~]$ qvm-features custom-disposablevm-template appmenus-dispvm 1
```
Additionally you may want to set it as default DisposableVM Template:
```shell_session
[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template
```
The above default is used whenever a qube request starting a new DisposableVM and do not specify which one (for example `qvm-open-in-dvm` tool). This can be also set in qube settings and will affect service calls from that qube. See [qrexec documentation](/doc/qrexec/#specifying-vms-tags-types-targets-etc) for details.
If you wish to use a [Minimal TemplateVM](/doc/templates/minimal/) as a DisposableVM Template, please see the [Minimal TemplateVM](/doc/templates/minimal/) page.
## Customization of DisposableVM
_**Note:** If you are trying to customize Tor Browser in a Whonix DisposableVM, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#DVM_Template_Customization)._
It is possible to change the settings for each new DisposableVM.
This can be done by customizing the DisposableVM Template on which it is based:
1. Start a terminal in the `fedora-26-dvm` qube (or another DisposableVM Template) by running the following command in a dom0 terminal. (If you enable `appmenus-dispvm` feature (as explained at the top), applications menu for this VM (`fedora-26-dvm`) will be "Disposable: fedora-26-dvm" (instead of "Domain: fedora-26-dvm") and entries there will start new DisposableVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself).
```shell_session
[user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal
```
2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include:
- Changing Firefox's default startup settings and homepage.
- Changing default editor, image viewer. In Debian-based templates this can be done with the `mimeopen` command.
- Changing the DisposableVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DisposableVM, you can choose your desired ProxyVM manually (by changing the newly-started DisposableVMs settings). This is useful if you sometimes wish to use a DisposableVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DisposableVM.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
## Using static DisposableVMs for sys-*
You can use a static DisposableVM for `sys-*` as long as it is stateless.
For example, a `sys-net` using DHCP or `sys-usb` will work.
In most cases `sys-firewall` will also work, even if you have configured AppVM firewall rules.
The only exception is if you require something like VM to VM communication and have manually edited `iptables` or other items directly inside the firewall AppVM.
To create one that has no PCI devices attached, such as for `sys-firewall`:
~~~
qvm-create -C DispVM -l green <sys-VMName>
qvm-prefs <sys-VMName> autostart true
qvm-prefs <sys-VMName> netvm <sys-net>
qvm-prefs <sys-VMName> provides_network true
qvm-features <sys-VMName> appmenus-dispvm ''
~~~
Next, set the old `sys-firewall` autostart to false, and update any references to the old one to instead point to the new.
For example, with `qvm-prefs work netvm sys-firewall2`.
To create one with a PCI device attached such as for `sys-net` or `sys-usb`, use the additional commands as follows.
**Note** You can use `qvm-pci` to [determine](/doc/pci-devices/#qvm-pci-usage) the `<BDF>`.
Also, you will often need to include the `-o no-strict-reset=True` [option](/doc/pci-devices/#no-strict-reset) with USB controllers.
~~~
qvm-create -C DispVM -l red <sys-VMName>
qvm-prefs <sys-VMName> virt_mode hvm
qvm-service <sys-VMName> meminfo-writer off
qvm-pci attach --persistent <sys-VMName> dom0:<BDF>
qvm-prefs <sys-VMName> autostart true
qvm-prefs <sys-VMName> netvm ''
qvm-features <sys-VMName> appmenus-dispvm ''
# optional, if this DisposableVM will be providing networking
qvm-prefs <sys-VMName> provides_network true
~~~
Next, set the old `sys-` VM's autostart to false, and update any references to the old one.
In particular, make sure to update `/etc/qubes-rpc/policy/qubes.UpdatesProxy` in dom0.
For example, `qvm-prefs sys-firewall netvm <sys-VMName>`.
See below for a complete example of a `sys-net` replacement:
~~~
qvm-create -C DispVM -l red sys-net2
qvm-prefs sys-net2 virt_mode hvm
qvm-service sys-net2 meminfo-writer off
qvm-pci attach --persistent sys-net2 dom0:00_1a.0
qvm-prefs sys-net2 autostart true
qvm-prefs sys-net2 netvm ''
qvm-features sys-net2 appmenus-dispvm ''
qvm-prefs sys-net2 provides_network true
qvm-prefs sys-net autostart false
qvm-prefs sys-firewall netvm sys-net2
qubes-prefs clockvm sys-net2
~~~
## Adding programs to DisposableVM Application Menu
For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM.
In order to do that, select "Qube settings" entry in selected base AppVM, go to "Applications" tab and select desired applications as for any other qube.
Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead.
## Create Custom sys-net sys-firewall and sys-usb DisposableVMs
Users have the option of creating customized DisposableVMs for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a DisposableVM is launched. Functionality is near-identical to the default VMs created following a new Qubes’ installation, except the user benefits from a non-persistent filesystem.
Functionality is not limited, users can:
- Set custom firewall rule sets and run Qubes VPN scripts.
- Set DisposableVMs to autostart at system boot.
- Attach PCI devices with the `--persistent` option.
Using DisposableVMs in this manner is ideal for untrusted qubes which require persistent PCI devices, such as USB VMs and NetVMs.
>_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate DisposableVM Template for use by each DisposableVM. If DisposableVM Template customization is not needed, then a single DisposableVM Template is used as a template for all DisposableVMs.
### Create and configure the DisposableVM Template on which the DisposableVM will be based
1. Create the DisposableVM Template:
```shell_session
[user@dom0 ~]$ qvm-create --class AppVM --label gray <DisposableVM-Template-Name>
```
2. _(optional)_ In the DisposableVM Template, add custom firewall rule sets, Qubes VPN scripts, etc.
Firewall rules sets and Qubes VPN scripts can be added just like any other VM.
3. Set the DisposableVM Template as template for DisposableVMs:
```shell_session
[user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
```
### Create the sys-net DisposableVM
1. Create `sys-net` DisposableVM based on the DisposableVM Template:
```shell_session
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label red disp-sys-net
```
2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/):
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net virt_mode hvm
```
3. Set `disp-sys-net` to provide network for other VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net provides_network true
```
4. Set `disp-sys-net` NetVM to none:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net netvm ""
```
5. List all available PCI devices to determine the correct _backend:BDF_ address(es) to assign to `disp-sys-net`:
```shell_session
[user@dom0 ~]$ qvm-pci
```
6. Attach the network PCI device(s) to `disp-sys-net` (finding and assigning PCI devices can be found [here](/doc/pci-devices/):
```shell_session
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-net <backend>:<bdf>
```
7. _(recommended)_ Set `disp-sys-net` to start automatically when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-net autostart true
```
8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
```
9. _(optional)_ Set `disp-sys-net` as the dom0 time source:
```shell_session
[user@dom0 ~]$ qubes-prefs clockvm disp-sys-net
```
10. _(recommended)_ Allow templates to be updated via `disp-sys-net`. In dom0, edit `/etc/qubes-rpc/policy/qubes.UpdatesProxy` to change the target from `sys-net` to `disp-sys-net`.
### Create the sys-firewall DisposableVM
1. Create `sys-firewall` DisposableVM:
```shell_session
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label green disp-sys-firewall
```
2. Set `disp-sys-firewall` to provide network for other VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall provides_network true
```
3. Set `disp-sys-net` as the NetVM for `disp-sys-firewall`:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
```
4. Set `disp-sys-firewall` as NetVM for other AppVMs:
```shell_session
[user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
```
5. _(recommended)_ Set `disp-sys-firewall` to auto-start when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-firewall autostart true
```
6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
```
7. _(optional)_ Set `disp-sys-firewall` as the default NetVM:
```shell_session
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
```
### Create the sys-usb DisposableVM
1. Create the `disp-sys-usb`:
```shell_session
[user@dom0 ~]$ qvm-create --template <disposablevm-template-name> --class DispVM --label red disp-sys-usb
```
2. Set the `disp-sys-usb` virtualization mode to hvm:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb virt_mode hvm
```
3. Set `disp-sys-usb` NetVM to none:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb netvm ""
```
4. List all available PCI devices:
```shell_session
[user@dom0 ~]$ qvm-pci
```
5. Attach the USB controller to the `disp-sys-usb`:
>_**Note:**_ Most of the commonly used USB controllers (all Intel integrated controllers) require the `-o no-strict-reset=True` option to be set. Instructions detailing how this option is set can be found [here](/doc/pci-devices/#no-strict-reset).
```shell_session
[user@dom0 ~]$ qvm-pci attach --persistent disp-sys-usb <backined>:<bdf>
```
6. _(optional)_ Set `disp-sys-usb` to auto-start when Qubes boots:
```shell_session
[user@dom0 ~]$ qvm-prefs disp-sys-usb autostart true
```
7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a DisposableVM template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the DisposableVM template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
```
8. Users should now follow instructions on [How to hide USB controllers from dom0](/doc/usb-qubes/#how-to-hide-all-usb-controllers-from-dom0).
9. At this point, your mouse may not work.
Edit the `qubes.InputMouse` policy file in dom0, which is located here:
```
/etc/qubes-rpc/policy/qubes.InputMouse
```
Add a line like this to the top of the file:
```
disp-sys-usb dom0 allow,user=root
```
### Starting the DisposableVMs
Prior to starting the new VMs, users should ensure that no other VMs such as the old `sys-net` and `sys-usb` VMs are running. This is because no two VMs can share the same PCI device while both running. It is recommended that users detach the PCI devices from the old VMs without deleting them. This will allow users to reattach the PCI devices if the newly created DisposableVMs fail to start.
Detach PCI device from VM:
```shell_session
[user@dom0~]$ qvm-pci detach <vm_name> <backend>:<bdf>
```
### Troubleshooting
If the `disp-sys-usb` does not start, it could be due to a PCI passthrough problem. For more details on this issue along with possible solutions, users can look [here](/doc/pci-troubleshooting/#pci-passthrough-issues).
## Deleting DisposableVMs
While working in a DisposableVM, you may want to open a document in another DisposableVM.
For this reason, the property `default_dispvm` may be set to the name of your DisposableVM in a number of VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
default_dispvm - custom-disposablevm-template
```
This will prevent the deletion of the DisposableVM Template. In order to fix this you need to unset the `default_dispvm` property:
```shell_session
[user@dom0 ~]$ qvm-prefs workvm default_dispvm ""
```
You can then delete the DisposableVM Template:
```shell_session
[user@dom0 ~]$ qvm-remove custom-disposablevm-template
This will completely remove the selected VM(s)
custom-disposablevm-template
```
If you still encounter the issue, you may have forgot to clean an entry. Looking at the system logs will help you:
```shell_session
[user@dom0 ~]$ journalctl | tail
```

58
user/advanced-topics/gui-configuration.md Normal file
View file

@ -0,0 +1,58 @@
---
lang: en
layout: doc
permalink: /doc/gui-configuration/
ref: 184
title: GUI Configuration
---
## Video RAM adjustment for high-resolution displays
When a qube starts, a fixed amount of RAM is allocated to the graphics buffer called video RAM.
This buffer needs to be at least as big as the whole desktop, accounting for all displays that are or will be connected to the machine.
By default, it is as much as needed for the current display and an additional full HD (FHD) display (1920×1080 8 bit/channel RGBA).
This logic fails when the machine has primary display in FHD resolution and, after starting some qubes, a 4K display is connected.
If the buffer is too small, and internal desktop resize fails.
To increase the minimum size of the video RAM buffer:
```sh
qvm-features dom0 gui-videoram-min $(($WIDTH * $HEIGHT * 4 / 1024))
qvm-features dom0 gui-videoram-overhead 0
```
Where `$WIDTH`×`$HEIGHT` is the maximum desktop size that you anticipate needing.
For example, if you expect to use a 1080p display and a 4k display side-by-side, that is `(1920 + 3840) × 2160 × 4 / 1024 = 48600`, or slightly more than 48 MiB per qube.
After making these adjustments, the qubes need to be restarted.
In the case of multiple display with different orientations or if you plug/unplug displays, the following code will set correct memory size using xrandr.
```sh
qvm-features dom0 gui-videoram-min $(xrandr --verbose | grep "Screen 0" | sed -e 's/.*current //' -e 's/\,.*//' | awk '{print $1*$3*4/1024}')
```
The amount of memory allocated per qube is the maximum of:
- `gui-videoram-min`
- current display + `gui-videoram-overhead`
Default overhead is about 8 MiB, which is enough for a 1080p display (see above).
So, the `gui-videoram-overhead` zeroing is not strictly necessary; it only avoids allocating memory that will not be used.
You might face issues when playing video, if the video is choppy instead of
smooth display this could be because the X server doesn't work. You can use the
Linux terminal (Ctrl-Alt-F2) after starting the virtual machine, login. You can
look at the Xorg logs file. As an option you can have the below config as
well present in `/etc/X11/xorg.conf.d/90-intel.conf`, depends on HD graphics
though -
```bash
Section "Device"
Identifier "Intel Graphics"
Driver "intel"
Option "TearFree" "true"
EndSection
```
## GUI Troubleshooting
See [GUI Troubleshooting](/doc/gui-troubleshooting) for issues relating to the Qubes graphical user interface and how to fix them.

227
user/advanced-topics/how-to-install-software-in-dom0.md Normal file
View file

@ -0,0 +1,227 @@
---
lang: en
layout: doc
permalink: /doc/how-to-install-software-in-dom0/
redirect_from:
- /doc/software-update-dom0/
- /en/doc/software-update-dom0/
- /doc/SoftwareUpdateDom0/
- /wiki/SoftwareUpdateDom0/
ref: 194
title: How to Install Software in Dom0
---
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> Installing software in dom0 is for advanced users only. Doing so has the potential to compromise your entire Qubes OS installation. Exercise extreme caution.
</div>
## Security
Since there is no networking in dom0, any bugs discovered in dom0 desktop components (e.g., the window manager) are unlikely to pose a problem for Qubes, since none of the third-party software running in dom0 is accessible from VMs or the network in any way.
Nonetheless, since software running in dom0 can potentially exercise full control over the system, it is important to install only trusted software in dom0.
The install/update process is split into two phases: *resolve and download* and *verify and install*.
The *resolve and download* phase is handled by the UpdateVM.
(The role of UpdateVM can be assigned to any VM in the Qube Manager, and there are no significant security implications in this choice.
By default, this role is assigned to the FirewallVM.)
After the UpdateVM has successfully downloaded new packages, they are sent to dom0, where they are verified and installed.
This separation of duties significantly reduces the attack surface, since all of the network and metadata processing code is removed from the TCB.
Although this update scheme is far more secure than directly downloading updates in dom0, it is not invulnerable.
For example, there is nothing that the Qubes OS Project can feasibly do to prevent a malicious RPM from exploiting a hypothetical bug in the cryptographic signature verification operation.
At best, we could switch to a different distro or package manager, but any of them could be vulnerable to the same (or a similar) attack.
While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular TemplateVM distro's updates, and this would be far too costly for us to maintain.
## How to update dom0
See [Updating Qubes OS](/doc/updating-qubes-os/).
## How to install a specific package
To install additional packages in dom0 (usually not recommended):
```
$ sudo qubes-dom0-update anti-evil-maid
```
You may also pass the `--enablerepo=` option in order to enable optional repositories (see yum configuration in dom0).
However, this is only for advanced users who really understand what they are doing.
You can also pass commands to `dnf` using `--action=...`.
## How to downgrade a specific package
**WARNING:** Downgrading a package can expose your system to security vulnerabilities.
1. Download an older version of the package:
~~~
sudo qubes-dom0-update package-version
~~~
Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
2. Downgrade the package:
~~~
sudo dnf downgrade package-version
~~~
## How to re-install a package
You can re-install in a similar fashion to downgrading.
1. Download the package:
~~~
sudo qubes-dom0-update package
~~~
Dnf will say that there is no update, but the package will nonetheless be downloaded to dom0.
2. Re-install the package:
~~~
sudo dnf reinstall package
~~~
Note that `dnf` will only re-install if the installed and downloaded versions match.
You can ensure they match by either updating the package to the latest version, or specifying the package version in the first step using the form `package-version`.
## How to uninstall a package
If you've installed a package such as anti-evil-maid, you can remove it with the following command:
```
sudo dnf remove anti-evil-maid
```
## Testing repositories
There are three Qubes dom0 [testing](/doc/testing/) repositories:
- `qubes-dom0-current-testing` -- testing packages that will eventually land in the stable
(`current`) repository
- `qubes-dom0-security-testing` -- a subset of `qubes-dom0-current-testing` that contains packages
that qualify as security fixes
- `qubes-dom0-unstable` -- packages that are not intended to land in the stable (`qubes-dom0-current`)
repository; mostly experimental debugging packages
To temporarily enable any of these repos, use the `--enablerepo=<repo-name>` option.
Example commands:
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing
sudo qubes-dom0-update --enablerepo=qubes-dom0-security-testing
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable
~~~
To enable or disable any of these repos permanently, change the corresponding `enabled` value to `1` in
`/etc/yum.repos.d/qubes-dom0.repo`.
## Contributed package repository
Please see [installing contributed packages](/doc/installing-contributed-packages/).
## Kernel upgrade
This section describes upgrading the kernel in dom0 and domUs.
### dom0
The packages `kernel` and `kernel-latest` are for dom0.
In the `current` repository:
- `kernel`: an older LTS kernel that has passed Qubes [testing](/doc/testing/) (the default dom0 kernel)
- `kernel-latest`: the latest release from kernel.org that has passed Qubes [testing](/doc/testing/) (useful for [troubleshooting newer hardware](/doc/newer-hardware-troubleshooting/))
In the `current-testing` repository:
- `kernel`: the latest LTS kernel from kernel.org at the time it was built.
- `kernel-latest`: the latest release from kernel.org at the time it was built.
### domU
The packages `kernel-qubes-vm` and `kernel-latest-qubes-vm` are for domUs.
See [Managing VM kernel](/doc/managing-vm-kernel/) for more information.
### Example
(Note that the following example enables the unstable repo.)
~~~
sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel kernel-qubes-vm
~~~
If the update process does not automatically do it (you should see it mentioned in the CLI output
from the update command), you may need to manually rebuild the EFI or grub config depending on which
your system uses.
*EFI*: Replace the example version numbers with the one you are upgrading to.
~~~
sudo dracut -f /boot/efi/EFI/qubes/initramfs-4.14.35-1.pvops.qubes.x86_64.img 4.14.35-1.pvops.qubes.x86_64
~~~
*Grub2*
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
Reboot required.
If you wish to upgrade to a kernel that is not available from the repos, then
there is no easy way to do so, but [it may still be possible if you're willing
to do a lot of work yourself](https://groups.google.com/d/msg/qubes-users/m8sWoyV58_E/HYdReRIYBAAJ).
## Changing default kernel
This section describes changing the default kernel in dom0.
It is sometimes needed if you have upgraded to a newer kernel and are having problems booting, for example.
The procedure varies depending on if you are booting with UEFI or grub.
On the next kernel update, the default will revert to the newest.
*EFI*
~~~
sudo nano /boot/efi/EFI/qubes/xen.cfg
~~~
In the `[global]` section at the top, change the `default=` line to match one of the three boot entries listed below.
For example,
~~~
default=4.19.67-1.pvops.qubes.x86_64
~~~
*Grub2*
~~~
sudo nano /etc/default/grub
[update the following two lines, add if needed]
GRUB_DISABLE_SUBMENU=false
GRUB_SAVEDEFAULT=true
[save and exit nano]
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
Then, reboot.
Once the grub menu appears, choose "Advanced Options for Qubes (with Xen hypervisor)".
Next, the top menu item (for example, "Xen hypervisor, version 4.8.5-9.fc25").
Select the kernel you want as default, and it will be remembered for next boot.
## Updating over Tor
Requires installed [Whonix](/doc/privacy/whonix/).
Go to Qubes VM Manager -> System -> Global Settings.
See the UpdateVM setting.
Choose your desired Whonix-Gateway ProxyVM from the list.
For example: sys-whonix.
`
Qubes VM Manager -> System -> Global Settings -> UpdateVM -> sys-whonix
`

109
user/advanced-topics/i3.md Normal file
View file

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

58
user/advanced-topics/installing-contributed-packages.md Normal file
View file

@ -0,0 +1,58 @@
---
lang: en
layout: doc
permalink: /doc/installing-contributed-packages/
ref: 225
title: Installing Contributed Packages
---
_This page is for users who wish to install contributed packages.
If you want to contribute a package, please see [package contributions](/doc/package-contributions/)._
Qubes OS contributed packages are available under the [QubesOS-contrib](https://github.com/QubesOS-contrib/) GitHub Project.
This is a place where our community can [contribute Qubes OS related packages, additions and various customizations](/doc/package-contributions/).
## Installing the repositories
If you want to install one of these packages, first you need to enable the repository in your system (dom0 and/or templates). This can be done by installing the `qubes-repo-contrib` package. This package includes the repository definition and keys necessary to download, verify, and install [QubesOS-contrib](https://github.com/QubesOS-contrib/) packages.
In dom0, use `qubes-dom0-update`:
```bash_session
sudo qubes-dom0-update qubes-repo-contrib
```
In a Fedora-based template, use `dnf`:
```bash_session
sudo dnf install qubes-repo-contrib
```
In a Debian-based template, use `apt`:
```bash_session
sudo apt update && sudo apt install qubes-repo-contrib
```
The new repository definition will be in the usual location for your distro, and it will follow the naming pattern `qubes-contrib-*`, depending on your Qubes release and whether it is in dom0 or a TemplateVM.
For example, in a Fedora TemplateVM on Qubes 4.0, the new repository definition would be:
```
/etc/yum.repos.d/qubes-contrib-vm-r4.0.repo
```
## Installing packages
After you've installed the repositories, you can install contributed packages.
**Note:** The first time you install a contrib package in dom0, you must use the `--clean` flag.
For example, to install `qvm-screenshot-tool` in dom0:
```bash_session
sudo qubes-dom0-update --clean qvm-screenshot-tool
```
Please see the package's README for specific installation and setup instructions.

91
user/advanced-topics/kde.md Normal file
View file

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

365
user/advanced-topics/managing-vm-kernels.md Normal file
View file

@ -0,0 +1,365 @@
---
lang: en
layout: doc
permalink: /doc/managing-vm-kernels/
redirect_from:
- /doc/managing-vm-kernel/
- /en/doc/managing-vm-kernel/
ref: 173
title: Managing VM Kernels
---
By default, VMs kernels are provided by dom0.
(See [here](/doc/software-update-dom0/#kernel-upgrade) for information about upgrading kernels in dom0.)
This means that:
1. You can select the kernel version (using GUI VM Settings tool or `qvm-prefs` commandline tool);
2. You can modify kernel options (using `qvm-prefs` commandline tool);
3. You can **not** modify any of the above from inside a VM;
4. Installing additional kernel modules is cumbersome.
*Note* In the examples below, although the specific version numbers might be old, the commands have been verified on R3.2 and R4.0 with debian-9 and fedora-26 templates.
To select which kernel a given VM will use, you can either use Qubes Manager (VM settings, advanced tab), or the `qvm-prefs` tool:
~~~
[user@dom0 ~]$ qvm-prefs -s my-appvm kernel
Missing kernel version argument!
Possible values:
1) default
2) none (kernels subdir in VM)
3) <kernel version>, one of:
- 3.18.16-3
- 3.18.17-4
- 3.19.fc20
- 3.18.10-2
[user@dom0 ~]$ qvm-prefs -s my-appvm kernel 3.18.17-4
[user@dom0 ~]$ qvm-prefs -s my-appvm kernel default
~~~
To check/change the default kernel you can either go to "Global settings" in Qubes Manager, or use the `qubes-prefs` tool:
~~~
[user@dom0 ~]$ qubes-prefs
clockvm : sys-net
default-fw-netvm : sys-net
default-kernel : 3.18.17-4
default-netvm : sys-firewall
default-template : fedora-21
updatevm : sys-firewall
[user@dom0 ~]$ qubes-prefs -s default-kernel 3.19.fc20
~~~
To view kernel options, you can use the GUI VM Settings tool; to view and change them, use `qvm-prefs` commandline tool:
~~~
[user@dom0 ~]$ qvm-prefs -g work kernelopts
nopat
[user@dom0 ~]$ qvm-prefs -s work kernelopts "nopat apparmor=1 security=apparmor"
~~~
## Installing different kernel using Qubes kernel package
VM kernels are packages by Qubes team in `kernel-qubes-vm` packages.
Generally, the system will keep the three newest available versions.
You can list them with the `rpm` command:
~~~
[user@dom0 ~]$ rpm -qa 'kernel-qubes-vm*'
kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64
kernel-qubes-vm-3.18.16-3.pvops.qubes.x86_64
kernel-qubes-vm-3.18.17-4.pvops.qubes.x86_64
~~~
If you want a more recent version, you can check the `qubes-dom0-unstable` repository.
There is also the `kernel-latest-qubes-vm` package which should provide a more recent (non-LTS) kernel, but has received much less testing.
As the names suggest, keep in mind that those packages may be less stable than the default ones.
To check available versions in the `qubes-dom0-unstable` repository:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable --action=list kernel-qubes-vm
Using sys-firewall as UpdateVM to download updates for Dom0; this may take some time...
Running command on VM: 'sys-firewall'...
Loaded plugins: langpacks, post-transaction-actions, yum-qubes-hooks
Installed Packages
kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes installed
kernel-qubes-vm.x86_64 1000:3.18.16-3.pvops.qubes installed
kernel-qubes-vm.x86_64 1000:3.18.17-4.pvops.qubes installed
Available Packages
kernel-qubes-vm.x86_64 1000:4.1.12-6.pvops.qubes qubes-dom0-unstable
No packages downloaded
Installed Packages
kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes @anaconda/R3.0
kernel-qubes-vm.x86_64 1000:3.18.16-3.pvops.qubes @/kernel-qubes-vm-3.18.16-3.pvops.qubes.x86_64
kernel-qubes-vm.x86_64 1000:3.18.17-4.pvops.qubes @qubes-dom0-cached
~~~
Installing a new version from `qubes-dom0-unstable` repository:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update --enablerepo=qubes-dom0-unstable kernel-qubes-vm
Using sys-firewall as UpdateVM to download updates for Dom0; this may take some time...
Running command on VM: 'sys-firewall'...
Loaded plugins: langpacks, post-transaction-actions, yum-qubes-hooks
Resolving Dependencies
(...)
===========================================================================================
Package Arch Version Repository Size
===========================================================================================
Installing:
kernel-qubes-vm x86_64 1000:4.1.12-6.pvops.qubes qubes-dom0-cached 40 M
Removing:
kernel-qubes-vm x86_64 1000:3.18.10-2.pvops.qubes @anaconda/R3.0 134 M
Transaction Summary
===========================================================================================
Install 1 Package
Remove 1 Package
Total download size: 40 M
Is this ok [y/d/N]: y
Downloading packages:
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction (shutdown inhibited)
Installing : 1000:kernel-qubes-vm-4.1.12-6.pvops.qubes.x86_64 1/2
mke2fs 1.42.12 (29-Aug-2014)
This kernel version is used by at least one VM, cannot remove
error: %preun(kernel-qubes-vm-1000:3.18.10-2.pvops.qubes.x86_64) scriptlet failed, exit status 1
Error in PREUN scriptlet in rpm package 1000:kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64
Verifying : 1000:kernel-qubes-vm-4.1.12-6.pvops.qubes.x86_64 1/2
Verifying : 1000:kernel-qubes-vm-3.18.10-2.pvops.qubes.x86_64 2/2
Installed:
kernel-qubes-vm.x86_64 1000:4.1.12-6.pvops.qubes
Failed:
kernel-qubes-vm.x86_64 1000:3.18.10-2.pvops.qubes
Complete!
[user@dom0 ~]$
~~~
In the above example, it tries to remove the 3.18.10-2.pvops.qubes kernel (to keep only three installed), but since some VM uses it, it fails.
Installation of the new package is unaffected by this event.
The newly installed package is set as the default VM kernel.
## Installing different VM kernel based on dom0 kernel
It is possible to package a kernel installed in dom0 as a VM kernel.
This makes it possible to use a VM kernel which is not packaged by Qubes team.
This includes:
* using a Fedora kernel package
* using a manually compiled kernel
To prepare such a VM kernel, you need to install the `qubes-kernel-vm-support` package in dom0 and also have matching kernel headers installed (`kernel-devel` package in the case of a Fedora kernel package).
You can install requirements using `qubes-dom0-update`:
~~~
[user@dom0 ~]$ sudo qubes-dom0-update qubes-kernel-vm-support kernel-devel
Using sys-firewall as UpdateVM to download updates for Dom0; this may take some time...
Running command on VM: 'sys-firewall'...
Loaded plugins: langpacks, post-transaction-actions, yum-qubes-hooks
Package 1000:kernel-devel-4.1.9-6.pvops.qubes.x86_64 already installed and latest version
Resolving Dependencies
(...)
================================================================================
Package Arch Version Repository Size
================================================================================
Installing:
qubes-kernel-vm-support x86_64 3.1.2-1.fc20 qubes-dom0-cached 9.2 k
Transaction Summary
================================================================================
Install 1 Package
Total download size: 9.2 k
Installed size: 13 k
Is this ok [y/d/N]: y
Downloading packages:
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction (shutdown inhibited)
Installing : qubes-kernel-vm-support-3.1.2-1.fc20.x86_64 1/1
Creating symlink /var/lib/dkms/u2mfn/3.1.2/source ->
/usr/src/u2mfn-3.1.2
DKMS: add completed.
Verifying : qubes-kernel-vm-support-3.1.2-1.fc20.x86_64 1/1
Installed:
qubes-kernel-vm-support.x86_64 0:3.1.2-1.fc20
Complete!
~~~
Then you can call the `qubes-prepare-vm-kernel` tool to actually package the kernel.
The first parameter is kernel version (exactly as seen by the kernel), the second one (optional) is short name.
This is visible in Qubes Manager and the `qvm-prefs` tool.
~~~
[user@dom0 ~]$ sudo qubes-prepare-vm-kernel 4.1.9-6.pvops.qubes.x86_64 4.1.qubes
--> Building files for 4.1.9-6.pvops.qubes.x86_64 in /var/lib/qubes/vm-kernels/4.1.qubes
---> Recompiling kernel module (u2mfn)
---> Generating modules.img
mke2fs 1.42.12 (29-Aug-2014)
---> Generating initramfs
--> Done.
~~~
## Kernel files structure
Kernel for a VM is stored in `/var/lib/qubes/vm-kernels/KERNEL_VERSION` directory (`KERNEL_VERSION` replaced with actual version). Qubes 4.x supports the following files there:
* `vmlinuz` - kernel binary (may not be a Linux kernel)
* `initramfs` - initramfs for the kernel to load
* `modules.img` - ext4 filesystem image containing Linux kernel modules (to be mounted at `/lib/modules`); additionally it should contain a copy of `vmlinuz` and `initramfs` in its root directory (for loading by qemu inside stubdomain)
* `default-kernelopts-common.txt` - default kernel options, in addition to those specified with `kernelopts` qube property (can be disabled with `no-default-kernelopts` feature)
All the files besides `vmlinuz` are optional in Qubes R4.1 or newer. In Qubes R4.0, `vmlinuz` and `initramfs` are both required to be present.
## Using kernel installed in the VM
Both debian-9 and fedora-26 templates already have grub and related tools preinstalled so if you want to use one of the distribution kernels, all you need to do is clone either template to a new one, then:
~~~
qvm-prefs <clonetemplatename> virt_mode hvm
qvm-prefs <clonetemplatename> kernel ''
~~~
If you'd like to use a different kernel than default, continue reading.
### Installing kernel in Fedora VM
Install whatever kernel you want.
You need to also ensure you have the `kernel-devel` package for the same kernel version installed.
If you are using a distribution kernel package (`kernel` package), the initramfs and kernel modules may be handled automatically.
If you are using a manually built kernel, you need to handle this on your own.
Take a look at the `dkms` documentation, especially the `dkms autoinstall` command may be useful.
If you did not see the `kernel` install rebuild your initramfs, or are using a manually built kernel, you will need to rebuild it yourself.
Replace the version numbers in the example below with the ones appropriate to the kernel you are installing:
~~~
sudo dracut -f /boot/initramfs-4.15.14-200.fc26.x86_64.img 4.15.14-200.fc26.x86_64
~~~
Once the kernel is installed, you need to create a GRUB configuration.
You may want to adjust some settings in `/etc/default/grub`; for example, lower `GRUB_TIMEOUT` to speed up VM startup.
Then, you need to generate the actual configuration:
In Fedora it can be done using the `grub2-mkconfig` tool:
~~~
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
~~~
You can safely ignore this error message:
~~~
grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map
~~~
Then shutdown the VM.
**Note:** You may also use `PV` mode instead of `HVM` but this is not recommended for security purposes.
If you require `PV` mode, install `grub2-xen` in dom0 and change the template's kernel to `pvgrub2`.
Booting to a kernel inside the template is not supported under `PVH`.
### Installing kernel in Debian VM
#### Distribution kernel
Apply the following instruction in a Debian TemplateVM or in a Debian StandaloneVM.
Using a distribution kernel package the initramfs and kernel modules should be handled automatically.
Install distribution kernel image, kernel headers and the grub.
~~~
sudo apt install linux-image-amd64 linux-headers-amd64 grub2 qubes-kernel-vm-support
~~~
If you are doing that on a qube based on "Debian Minimal" template, a grub gui will popup during the installation, asking you where you want to install the grub loader. You must select /dev/xvda (check the box using the space bar, and validate your choice with "Enter".)
You can safely ignore this error message:
`grub2-probe: error: cannot find a GRUB drive for /dev/mapper/dmroot. Check your device.map`
You may want to adjust some settings in `/etc/default/grub` (or better `/etc/default/grub.d`). For example, lower `GRUB_TIMEOUT` to speed up VM startup. You need to re-run `sudo update-grub` after making grub configuration changes.
Then shutdown the VM.
Go to dom0 -> Qubes VM Manger -> right click on the VM -> Qube settings -> Advanced
Depends on `Virtualization` mode setting:
* `Virtualization` mode `PV`: Possible, however use of `Virtualization` mode `PV` mode is discouraged for security purposes.
* If you require `Virtualization` mode `PV` mode, install `grub2-xen` in dom0. This can be done by running command `sudo qubes-dom0-update grub2-xen` in dom0.
* `Virtualization` mode `PVH`: Possible.
* `Virtualization` mode `HVM`: Possible.
The `Kernel` setting of the `Virtualization` mode setting:
* If `Virtualization` is set to `PVH` -> `Kernel` -> choose `pvgrub2-pvh` -> OK
* If `Virtualization` is set to `PV` -> `Kernel` -> choose `pvgrub2` -> OK
* If `Virtualization` is set to `HVM` -> `Kernel` -> choose `none` -> OK
Start the VM.
The process of using Qubes VM kernel with distribution kernel is complete.
#### Custom kernel
Any kernel can be installed. Just make sure to install kernel headers as well.
If you are building the kernel manually, do this using `dkms` and `initramfs-tools`.
Run DKMS. Replace this <kernel-version> with actual kernel version.
```bash_session
sudo dkms autoinstall -k <kernel-version>
```
For example.
```bash_session
sudo dkms autoinstall -k 4.19.0-6-amd64
```
Update initramfs.
```bash_session
sudo update-initramfs -u
```
The output should look like this:
```shell_session
$ sudo dkms autoinstall -k 3.16.0-4-amd64
u2mfn:
Running module version sanity check.
- Original module
- No original module exists within this kernel
- Installation
- Installing to /lib/modules/3.16.0-4-amd64/updates/dkms/
depmod....
DKMS: install completed.
$ sudo update-initramfs -u
update-initramfs: Generating /boot/initrd.img-3.16.0-4-amd64
```
#### Troubleshooting
In case of problems, visit the [VM Troubleshooting guide](/doc/vm-troubleshooting/#vm-kernel-troubleshooting) to learn how to access the VM console, view logs and fix a VM kernel installation.

97
user/advanced-topics/mount-from-other-os.md Normal file
View file

@ -0,0 +1,97 @@
---
lang: en
layout: doc
permalink: /doc/mount-from-other-os/
redirect_from:
- /en/doc/mount-from-other-os/
- /doc/MountFromOtherOs/
- /wiki/MountFromOtherOs/
ref: 175
title: How to Mount a Qubes Partition from Another OS
---
When a Qubes OS install is unbootable or booting it is otherwise undesirable, this process allows for the recovery of files stored within the system.
These functions are manual and do not require any Qubes specific tools. All steps assume the default Qubes install with the following components:
- LUKS encrypted disk
- LVM based VM storage
Before beginning, if attempting to access one Qubes system from another, it is recommended to pass the entire encrypted Qubes disk to an isolated AppVM.
This can be done with the command `qvm-block attach <isolated vm> dom0:<disk>` in dom0.
Decrypting the Disk
-----------------
1. Find the disk to be accessed:
1. Open a Linux terminal in either dom0 or the AppVM the disk was passed through to and enter `lsblk`, which will result in an output similar to the following.
In this example, the currently booted Qubes system is installed on `sda` and the qubes system to be accessed is on `nvme0n1p2`.
```
sda 8:0 0 111.8G 0 disk
├─sda1 8:1 0 200M 0 part /boot/efi
├─sda2 8:2 0 1G 0 part /boot
└─sda3 8:3 0 110.6G 0 part
└─luks-fed62fc2-2674-266d-2667-2667259cbdec 253:0 0 110.6G 0 crypt
├─qubes_dom0-pool00_tmeta 253:1 0 88M 0 lvm
│ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm
│ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm /
│ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm
├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm
├─qubes_dom0-pool00_tdata 253:2 0 84.4G 0 lvm
│ └─qubes_dom0-pool00-tpool 253:3 0 84.4G 0 lvm
│ ├─qubes_dom0-root 253:4 0 84.4G 0 lvm /
│ ├─qubes_dom0-pool00 253:6 0 84.4G 0 lvm
│ ├─qubes_dom0-vm--fedora--30--dvm--private--1576749131--back 253:7 0 2G 0 lvm
└─qubes_dom0-swap 253:5 0 4G 0 lvm [SWAP]
sdb 8:16 0 447.1G 0 disk
├─sdb1 8:17 0 549M 0 part
└─sdb2 8:18 0 446.6G 0 part
sr0 11:0 1 1024M 0 rom
nvme0n1 259:0 0 465.8G 0 disk
├─nvme0n1p1 259:1 0 1G 0 part
└─nvme0n1p2 259:2 0 464.8G 0 part
```
2. Decrypt the disk using the command `cryptsetup luksOpen /dev/<disk>`.
Accessing LVM Logical Volumes
-----------------------------
3. If using an AppVM or standard Linux, LVM should automatically discover the Qubes LVM configuration. In this case, continue to step 4.
1. Qubes uses the default name `qubes_dom0` for it's LVM VG.
This will conflict with the name of the VG of the currently installed system.
To read both, you will have to rename the VG.
*Note:* If this is not reversed, the Qubes install being accessed will not be bootable.
2. Find the UUID of the vg to be accessed using the command `vgdisplay`.
This will be the VG named `qubes_dom0` which is not marked active.
3. The command `vgrename <UUID> other_install` will rename the VG.
4. Run the command `vgscan` to add any new VGs to the device list.
Mounting the disk
-----------------
5. Find the disk to be accessed. The `lsblk` command above may be of use. The following rules apply by default:
| Disk name | Data type | Explanation |
| ----------------------------- | ----------------- | ------------------------------------------- |
| other\_install/root | dom0 root | The root partition of dom0. |
| other\_install/<vm>-private | VM | The /rw partition of the named VM. |
| other\_install/<vm>-root | templateVM root | The root partition of the named TemplateVM. |
| other\_install/pool00\_tmeta | LVM Metadata | The metadata LV of this disk. |
6. Mount the disk using the command `mount /dev/other_install/<lv name> <mountpoint>`.
*Note:* Any compromised data which exists in the volume to be mounted will be accessible here.
Do not mount untrusted partitions in dom0.
At this point, all files are available in the chosen mountpoint.
Reverting Changes
-----------------------------------------
Any changes which were made to the system in the above steps will need to be reverted before the disk will properly boot.
However, LVM will not allow an VG to be renamed to a name already in use.
Thes steps must occur either in an AppVM or using recovery media.
1. Unmount any disks that were accessed.
2. Rename the VG back to qubes\_dom0 using the command `vgrename other_install qubes_dom0`.

25
user/advanced-topics/qubes-service.md Normal file
View file

@ -0,0 +1,25 @@
---
lang: en
layout: doc
permalink: /doc/qubes-service/
redirect_from:
- /en/doc/qubes-service/
- /doc/QubesService/
- /wiki/QubesService/
ref: 138
title: Qubes Service
---
Usage documentation is in the `qvm-service` man page. There are also described predefined services.
Under the hood, an enabled service in a VM is signaled by a file in `/var/run/qubes-service`.
This can be used to implement an almost enable/disable **per-VM** switch controlled by dom0.
Adding support for systemd services is pretty simple. In the VM, create the following file (and directory, if needed): `/etc/systemd/system/<service name>.service.d/30_qubes.conf`. It should contain the following:
~~~
[Unit]
ConditionPathExists=/var/run/qubes-service/<service name>
~~~
This will cause the service to be started only when you enable it with `qvm-service` for this VM.

110
user/advanced-topics/resize-disk-image.md Normal file
View file

@ -0,0 +1,110 @@
---
lang: en
layout: doc
permalink: /doc/resize-disk-image/
redirect_from:
- /en/doc/resize-disk-image/
- /en/doc/resize-root-disk-image/
- /doc/ResizeDiskImage/
- /doc/ResizeRootDiskImage/
- /wiki/ResizeDiskImage/
- /wiki/ResizeRootDiskImage/
ref: 182
title: Resize Disk Image
---
## Resizing Disk Images
By default Qubes uses thin volumes for the disk images.
This means that space is not actually allocated for the volume until it is used.
So a 2GB private volume with 100M of files will only use 100M.
This explains how you can have *many* qubes with large private volumes on quite a small disk.
This is called over provisioning.
You should keep an eye on the disk-space widget to see how much free space you actually have.
It is easy to increase the size of disk images.
There are risks attached to reducing the size of an image, and in general you should not need to do this.
## Increasing the size of Disk Images
There are several disk images which can be easily extended, but pay attention to the overall consumed space of your sparse/thin disk images.
In most cases, the GUI tool Qube Settings (available for every qube from the Start menu, and also in the Qube Manager) will allow you to easily increase maximum disk image size.
![vm-settings-disk-image.png](/attachment/wiki/DiskSize/r4.0-vm-settings-disk-image.png)
In case of standalone qubes and templates, just change the Disk Storage settings above.
In case of template-based qubes, the private storage (the /home directory and user files) can be changed in the qube's own settings, but the system root image is [inherited from the template](/getting-started/), and so it must be changed in the template settings.
If you are increasing the disk image size for Linux-based qubes installed from Qubes OS repositories in Qubes 4.0 or later, changing the settings above is all you need to do - in other cases, you may need to do more, according to instructions below.
See also the OS-specific follow-up instructions below.
### Increasing the size of Disk Images
Use either GUI tool Qube Settings (`qubes-vm-settings`) or the CLI tool `qvm-volume`.
Maximum size which can be assigned through Qube Settings is 1048576 MiB - if you need more, use `qvm-volume`:
~~~
qvm-volume extend <vm_name>:root <size>
~~~
OR
~~~
qvm-volume extend <vm_name>:private <size>
~~~
Note: Size is the target size (i.e. 4096MB or 16GB, ...), not the size to add to the existing disk.
If you have run out of space for software in your Template, you need to increase *root image* of the Template (not private storage!).
**Make sure changes in the Template between reboots don't exceed 10G.**
It is recommended that you restart (or start and then shutdown, if it is not running) the template after resizing the root image.
If you are **not** using Linux in the qube, you will also need to:
1. Start the template.
2. Resize the filesystem using OS appropriate tools.
3. Verify available space in the template using `df -h` or OS specific tools.
4. Shutdown the template.
#### Windows 7
1. Click Start
2. type "diskmgmt.msc" - this takes you to Disk Management
3. Right-click on your existing volume, select "Extend Volume..."
4. Click through the wizard.
No reboot required.
#### FreeBSD
~~~
gpart recover ada0
sysctl kern.geom.debugflags=0x10
gpart resize -i index ada0
zpool online -e poolname ada0
~~~
#### Linux
Qubes will automatically grow the filesystem for you on all AppVMs with Qubes packages installed (which are all AppVMs installed from templates, cloned from templates etc. - if you have not created an empty HVM and installed a Linux distribution in it, without using Qubes repositories, you are almost certainly safe).
Otherwise, you will see that there is unallocated free space at the end of your primary disk.
You can use standard linux tools like `fdisk` and `resize2fs` to make this space available.
## Decreasing the size of Disk Images
The number shown for "storage max size" does not mean that the storage is really using that amount. In most cases you need not worry about the size shown.
If you have increased the max size, and do not need it, then you *can* reduce the allocated size, but there is a risk of data loss.
Remember you really dont need to do this.
You can create a new qube, copy your files in to the new qube, and delete the old qube. (Simple and effective.)
Or you can take the risk of reducing the size of the disk.
For example, to reduce the private storage of qube1 to 1GiB:
Open a terminal in dom0:
```
qvm-shutdown qube1
sudo lvresize --size 1024M /dev/qubes_dom0/vm-qube1-private
```
If you have a SSD see [here](/doc/disk-trim) for information on using fstrim.

70
user/advanced-topics/rpc-policy.md Normal file
View file

@ -0,0 +1,70 @@
---
lang: en
layout: doc
permalink: /doc/rpc-policy/
ref: 178
title: RPC Policies
---
This document explains the basics of RPC policies in Qubes.
For more information, see [Qrexec: command execution in VMs](/doc/qrexec3/).
Here's an example of an RPC policy file in dom0:
```
[user@dom0 user ~]$ cat /etc/qubes-rpc/policy/qubes.FileCopy
(...)
@tag:work @default ask
@tag:work @tag:work allow
@tag:work @anyvm deny
@anyvm @tag:work deny
@anyvm @anyvm ask
```
It has three columns (from left to right): source, destination, and permission.
Each row is a rule.
For example, the second row says that we're **allowed** (third column) to copy a file (since this is the policy file for `qubes.FileCopy`) **from** (first column) any VM tagged with "work" **to** (second column) any VM tagged with "work".
In other words, all the VMs tagged with "work" are allowed to copy files to each other without any prompts.
(If the third column were "ask" instead of "allow", there would be prompts.
I.e., we would be **asked** to approve the action, instead of it always being **allowed**.)
Now, the whole policy file is parsed from top to bottom.
As soon as a rule is found that matches the action being evaluated, parsing stops.
We can see what this means by looking at the third row.
It says that we're **denied** from attempting to copy a file **from** any VM tagged with "work" **to** any VM whatsoever.
(That's what the `@anyvm` keyword means -- literally any VM in the system, except for dom0).
But, wait a minute, didn't we just say (in the second row) that all the VMs tagged with work are **allowed** to copy files to each other?
That's exactly right.
The second and third rows contradict each other, but that's intentional.
Since we know that parsing goes from top to bottom (and stops at the first match), we intentionally put the second row above the third row so that it would take precedence.
This is how we create a policy that says: "VMs tagged with 'work' are allowed to copy files to each other but not to any *other* VMs (i.e., not to VMs that *aren't* tagged with 'work')."
When an operation is initiated with a specific target, e.g. `qvm-copy-to-vm other_work_vm some_file` the policy mechanism looks for a row
matching `source_work_vm other_work_vm PERMISSION`. In this case, assuming both VMs have the `work` tag, the second row would match, and
the operation would be `allow`ed without any prompts. When an operation is initiated without a specific target, e.g. `qvm-copy some_file`,
the policy mechanism looks for a row matching `source_work_vm @default PERMISSION`. In this case, the first row indicates that the user
should be prompted for the destination. The list of destination VMs in the prompt is filtered to only include VMs that are valid as per
the policy (so in this example, only other work VMs would be listed). If the first row was commented out, the second row would not match
(the `@default` placeholder is not included in `@tag:work`) but the third row would match (the `@default` placeholder is included in
`@anyvm`). The `qvm-copy` operation would therefore terminate immediately with the message `Request refused`, without prompting the user
with a list of valid destination VMs, and only `qvm-copy-to-vm` operations with valid destinations would be allowed.
The fourth row says that we're **denied** from copying files **from** any VM in the system **to** any VM tagged with "work".
Again, since parsing goes from top to bottom, this doesn't mean that no files can ever be copied from *any* VM to a VM tagged with "work".
Rather, it means that only VMs that match an earlier rule can do so (in this case, only VMs tagged with "work").
The fifth and final row says that we're **asked** (i.e., prompted) to copy files **from** any VM in the system **to** any VM in the system.
(This rule was already in the policy file by default.
We added the first four.)
Note that it wouldn't make sense to add any rules after this one, since every possible pair of VMs will match the `@anyvm @anyvm` pattern.
Therefore, parsing will always stop at this rule, and no rules below it will ever be evaluated.
All together, the four rules we added say that all VMs tagged with "work" are allowed to copy files to each other; however, they're denied from copying files to other VMs (without the "work" tag), and other VMs (without the "work" tag) are denied from copying files to them.
The fifth rule means that the user gets prompted for any situation not already covered.
Further details about how this system works can be found in [Qrexec: command execution in VMs](/doc/qrexec3/).
(***Note**: the `$` character is deprecated in qrexec keywords -- please use `@` instead (e.g. `@anyvm`).
For more information, see the bulletin [here](https://github.com/QubesOS/qubes-secpack/blob/master/QSBs/qsb-038-2018.txt).*)

612
user/advanced-topics/salt.md Normal file
View file

@ -0,0 +1,612 @@
---
lang: en
layout: doc
permalink: /doc/salt/
ref: 185
title: Salt (management stack)
---
Since the Qubes R3.1 release we have included the Salt (also called SaltStack)
management engine in dom0 as default (with some states already configured).
Salt allows administrators to easily configure their systems.
In this guide we will show how it is set up and how you can modify it for your
own purpose.
In the current form the **API is provisional** and subject to change between
*minor* releases.
## Understanding Salt
This document is not meant to be comprehensive Salt documentation; however,
before writing anything it is required you have at least *some* understanding of
basic Salt-related vocabulary.
For more exhaustive documentation, visit [official site](https://docs.saltstack.com/en/latest/), though we
must warn you that it is not easy to read if you just start working with Salt
and know nothing.
### The Salt Architecture
Salt is a client-server model, where the server (called *master*) manages
its clients (called *minions*).
In typical situations, it is intended that the administrator interacts only
with the master and keeps the configurations there.
In Qubes, we don't have a master.
Instead we have one minion which resides in `dom0` and manages domains from
there.
This setup is also supported by Salt.
Salt is a management engine (similar to Ansible, Puppet, and Chef), that
enforces a particular state of a minion system.
A *state* is an end effect *declaratively* expressed by the administrator.
This is the most important concept in the entire engine.
All configurations (i.e., the states) are written in YAML.
A *pillar* is a data back-end declared by the administrator.
When states become repetitive, instead of pure YAML they can be written using a
template engine (preferably Jinja2); which can use data structures specified in
pillars.
A *formula* is a ready to use, packaged solution that combines a state and a
pillar (possibly with some file templates and other auxiliary files).
There are many formulas made by helpful people all over the Internet.
A *grain* is some data that is also available in templates, but its value is not
directly specified by administrator.
For example, the distribution (e.g., `"Debian"` or `"Gentoo"`) is a value of
the grain `"os"`. It also contains other information about the kernel,
hardware, etc.
A *module* is a Python extension to Salt that is responsible for actually
enforcing the state in a particular area.
It exposes some *imperative* functions for the administrator.
For example, there is a `system` module that has a `system.halt` function that,
when issued, will immediately halt a domain.
There is another function called `state.highstate` which will synchronize the
state of the system with the administrator's configuration/desires.
### Configuration
#### States
The smallest unit of configuration is a state.
A state is written in YAML and looks like this:
```
stateid:
cmd.run: #this is the execution module. in this case it will execute a command on the shell
- name: echo 'hello world' #this is a parameter of the state.
```
The stateid has to be unique throughout all states running for a minion and can
be used to order the execution of the references state.
`cmd.run` is an execution module.
It executes a command on behalf of the administrator.
`name: echo 'hello world'` is a parameter for the execution module `cmd.run`.
The module used defines which parameters can be passed to it.
There is a list of [officially available states](https://docs.saltstack.com/en/latest/ref/states/all/).
There are many very useful states:
- For [managing files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html): Use this to create files or
directories and change them (append lines, replace text, set their content etc.)
- For [installing and uninstalling](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html) packages.
- For [executing shell commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html).
With these three states you can define most of the configuration of a VM.
You can also [order the execution](https://docs.saltstack.com/en/latest/ref/states/ordering.html) of your states:
```
D:
cmd.run:
- name: echo 1
- order: last
C:
cmd.run:
- name: echo 1
B:
cmd.run:
- name: echo 1
- require:
- cmd: A
- require_in:
- cmd:C
A:
cmd.run:
- name: echo 1
- order: 1
```
The order of execution will be `A, B, C, D`.
The official documentation has more details on the
[require](https://docs.saltstack.com/en/latest/ref/states/requisites.html) and [order](https://docs.saltstack.com/en/latest/ref/states/ordering.html#the-order-option) arguments.
#### State Files
When configuring a system you will write one or more state files (`*.sls`) and
put (or symlink) them into the main Salt directory `/srv/salt/`.
Each state file contains multiple states and should describe some unit of
configuration (e.g., a state file `mail.sls` could setup a VM for e-mail).
#### Top Files
After you have several state files, you need something to assign them to a VM.
This is done by `*.top` files ([official documentation](https://docs.saltstack.com/en/latest/ref/states/top.html)).
Their structure looks like this:
```
environment:
target_matching_clause:
- statefile1
- folder2.statefile2
```
In most cases, the environment will be called `base`.
The `target_matching_clause` will be used to select your minions (VMs).
It can be either the name of a VM or a regular expression.
If you are using a regular expressions, you need to give Salt a hint you are
doing so:
```
environment:
^app-(work|(?!mail).*)$:
- match: pcre
- statefile
```
For each target you can write a list of state files.
Each line is a path to a state file (without the `.sls` extension) relative to
the main directory.
Each `/` is exchanged with a `.`, so you can't reference files or directories
with a `.` in their name.
### Enabling Top Files and Applying the States
Now, because we use custom extensions to manage top files (instead of just
enabling them all), to enable a particular top file you should issue command:
```
$ qubesctl top.enable my-new-vm
```
To list all enabled top files:
```
$ qubesctl top.enabled
```
And to disable one:
```
$ qubesctl top.disable my-new-vm
```
To apply the states to dom0 and all VMs:
```
$ qubesctl --all state.highstate
```
(More information on the `qubesctl` command further down.)
### Template Files
You will sometimes find yourself writing repetitive states.
To solve this, there is the ability to template files or states.
This is most commonly done with [Jinja](http://jinja.pocoo.org/).
Jinja is similar to Python and in many cases behaves in a similar fashion, but
there are sometimes differences when, for example, you set some variable inside
a loop: the variable outside will not get changed.
Instead, to get this behavior, you would use a `do` statement.
So you should take a look at the [Jinja API documentation](http://jinja.pocoo.org/docs/2.9/templates/).
Documentation about using Jinja to directly call Salt functions and get data
about your system can be found in the official
[Salt documentation](https://docs.saltstack.com/en/getstarted/config/jinja.html#get-data-using-salt).
## Salt Configuration, QubesOS layout
All Salt configuration files are in the `/srv/` directory, as usual.
The main directory is `/srv/salt/` where all state files reside.
States are contained in `*.sls` files.
However, the states that are part of the standard Qubes distribution are mostly
templates and the configuration is done in pillars from formulas.
The formulas are in `/srv/formulas`, including stock formulas for domains in
`/srv/formulas/dom0/virtual-machines-formula/qvm`, which are used by firstboot.
Because we use some code that is not found in older versions of Salt, there is
a tool called `qubesctl` that should be run instead of `salt-call --local`.
It accepts all the same arguments of the vanilla tool.
## Configuring a VM's System from Dom0
Salt in Qubes can be used to configure VMs from dom0.
Simply set the VM name as the target minion name in the top file.
You can also use the `qubes` pillar module to select VMs with a particular
property (see below).
If you do so, then you need to pass additional arguments to the `qubesctl` tool:
```
usage: qubesctl [-h] [--show-output] [--force-color] [--skip-dom0]
[--targets TARGETS | --templates | --app | --all]
...
positional arguments:
command Salt command to execute (e.g., state.highstate)
optional arguments:
-h, --help show this help message and exit
--show-output Show output of management commands
--force-color Force color output, allow control characters from VM,
UNSAFE
--skip-dom0 Skip dom0 configuration (VM creation etc)
--targets TARGETS Coma separated list of VMs to target
--templates Target all templates
--app Target all AppVMs
--all Target all non-disposable VMs (TemplateVMs and AppVMs)
```
To apply a state to all templates, call `qubesctl --templates state.highstate`.
The actual configuration is applied using `salt-ssh` (running over `qrexec`
instead of `ssh`).
Which means you don't need to install anything special in a VM you want to
manage.
Additionally, for each target VM, `salt-ssh` is started from a temporary VM.
This way dom0 doesn't directly interact with potentially malicious target VMs;
and in the case of a compromised Salt VM, because they are temporary, the
compromise cannot spread from one VM to another.
Beginning with Qubes 4.0 and after [QSB #45](/news/2018/12/03/qsb-45/), we implemented two changes:
1. Added the `management_dispvm` VM property, which specifies the DVM
Template that should be used for management, such as Salt
configuration. TemplateBasedVMs inherit this property from their
parent TemplateVMs. If the value is not set explicitly, the default
is taken from the global `management_dispvm` property. The
VM-specific property is set with the `qvm-prefs` command, while the
global property is set with the `qubes-prefs` command.
2. Created the `default-mgmt-dvm` DisposableVM Template, which is hidden from
the menu (to avoid accidental use), has networking disabled, and has
a black label (the same as TemplateVMs). This VM is set as the global
`management_dispvm`. Keep in mind that this DVM template has full control
over the VMs it's used to manage.
## Writing Your Own Configurations
Let's start with a quick example:
```
my new and shiny VM:
qvm.present:
- name: salt-test # can be omitted when same as ID
- template: fedora-21
- label: yellow
- mem: 2000
- vcpus: 4
- flags:
- proxy
```
It uses the Qubes-specific `qvm.present` state, which ensures that the domain is
present (if not, it creates it).
- The `name` flag informs Salt that the domain should be named `salt-test` (not
`my new and shiny VM`).
- The `template` flag informs Salt which template should be used for the domain.
- The `label` flag informs Salt what color the domain should be.
- The `mem` flag informs Salt how much RAM should be allocated to the domain.
- The `vcpus` flag informs Salt how many Virtual CPUs should be allocated to the
domain
- The `proxy` flag informs Salt that the domain should be a ProxyVM.
As you will notice, the options are the same (or very similar) to those used in
`qvm-prefs`.
This should be put in `/srv/salt/my-new-vm.sls` or another `.sls` file.
A separate `*.top` file should be also written:
```
base:
dom0:
- my-new-vm
```
**Note** The third line should contain the name of the previous state file,
without the `.sls` extension.
To enable the particular top file you should issue the command:
```
$ qubesctl top.enable my-new-vm
```
To apply the state:
```
$ qubesctl state.highstate
```
### Example of Configuring a VM's System from Dom0
Lets make sure that the `mc` package is installed in all templates.
Similar to the previous example, you need to create a state file
(`/srv/salt/mc-everywhere.sls`):
```
mc:
pkg.installed: []
```
Then the appropriate top file (`/srv/salt/mc-everywhere.top`):
```
base:
qubes:type:template:
- match: pillar
- mc-everywhere
```
Now you need to enable the top file:
```
$ qubesctl top.enable mc-everywhere
```
And apply the configuration:
```
$ qubesctl --all state.highstate
```
## All Qubes-specific States
### `qvm.present`
As in the example above, it creates a domain and sets its properties.
### `qvm.prefs`
You can set properties of an existing domain:
```
my preferences:
qvm.prefs:
- name: salt-test2
- netvm: sys-firewall
```
***Note*** The `name:` option will not change the name of a domain, it will only
be used to match a domain to apply the configurations to it.
### `qvm.service`
```
services in my domain:
qvm.service:
- name: salt-test3
- enable:
- service1
- service2
- disable:
- service3
- service4
- default:
- service5
```
This enables, disables, or sets to default, services as in `qvm-service`.
### `qvm.running`
Ensures the specified domain is running:
```
domain is running:
qvm.running:
- name: salt-test4
```
## Virtual Machine Formulae
You can use these formulae to download, install, and configure VMs in Qubes.
These formulae use pillar data to define default VM names and configuration details.
The default settings can be overridden in the pillar data located in:
```
/srv/pillar/base/qvm/init.sls
```
In dom0, you can apply a single state with `sudo qubesctl state.sls STATE_NAME`.
For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (TemplateVM, `sys-firewall`, and `sys-net`).
### Available states
#### `qvm.sys-net`
System NetVM
#### `qvm.sys-usb`
System USB VM
#### `qvm.sys-net-with-usb`
System USB VM bundled into NetVM. Do not enable together with `qvm.sys-usb`.
#### `qvm.usb-keyboard`
Enable USB keyboard together with USB VM, including for early system boot (for LUKS passhprase).
This state implicitly creates a USB VM (`qvm.sys-usb` state), if not already done.
#### `qvm.sys-firewall`
System firewall ProxyVM
#### `qvm.sys-whonix`
Whonix gateway ProxyVM
#### `qvm.personal`
Personal AppVM
#### `qvm.work`
Work AppVM
#### `qvm.untrusted`
Untrusted AppVM
#### `qvm.vault`
Vault AppVM with no NetVM enabled.
#### `qvm.default-dispvm`
Default DisposableVM template - fedora-26-dvm AppVM
#### `qvm.anon-whonix`
Whonix workstation AppVM.
#### `qvm.whonix-ws-dvm`
Whonix workstation AppVM for Whonix DisposableVMs.
#### `qvm.updates-via-whonix`
Setup UpdatesProxy to route all templates updates through Tor (sys-whonix here).
#### `qvm.template-fedora-21`
Fedora-21 TemplateVM
#### `qvm.template-fedora-21-minimal`
Fedora-21 minimal TemplateVM
#### `qvm.template-debian-7`
Debian 7 (wheezy) TemplateVM
#### `qvm.template-debian-8`
Debian 8 (jessie) TemplateVM
#### `qvm.template-whonix-gw`
Whonix Gateway TemplateVM
#### `qvm.template-whonix-ws`
Whonix Workstation TemplateVM
#### `update.qubes-dom0`
Updates dom0. Example (executed in dom0):
```
$ sudo qubesctl --show-output state.sls update.qubes-dom0
```
#### `update.qubes-vm`
Updates domUs. Example to update all TemplateVMs (executed in dom0):
```
$ sudo qubesctl --show-output --skip-dom0 --templates state.sls update.qubes-vm
```
Useful options:
- `--max-concurrency` --- Limits how many templates are updated at the same time.
Adjust to your available RAM.
The default is 4, and the GUI updater sets it to 1.
- `--targets=vm1,vm2,...` --- Limit to specific VMs, instead of all of them.
(Use instead of `--templates` or `--standalones`.)
- `--show-output` --- Show an update summary instead of just OK/FAIL.
For other options, see `qubesctl --help`.
## The `qubes` Pillar Module
Additional pillar data is available to ease targeting configurations (for example all templates).
**Note:** This list is subject to change in future releases.
### `qubes:type`
VM type. Possible values:
- `admin` - Administration domain (`dom0`)
- `template` - Template VM
- `standalone` - Standalone VM
- `app` - Template based AppVM
### `qubes:template`
Template name on which a given VM is based (if any).
### `qubes:netvm`
VM which provides network to the given VM
## Debugging
The output for each VM is logged in `/var/log/qubes/mgmt-VM_NAME.log`.
If the log does not contain useful information:
1. Run `sudo qubesctl --skip-dom0 --target=VM_NAME state.highstate`
2. When your VM is being started (yellow) press Ctrl-z on qubesctl.
3. Open terminal in disp-mgmt-VM_NAME.
4. Look at /etc/qubes-rpc/qubes.SaltLinuxVM - this is what is
executed in the management VM.
5. Get the last two lines:
```shell_session
$ export PATH="/usr/lib/qubes-vm-connector/ssh-wrapper:$PATH"
$ salt-ssh "$target_vm" $salt_command
```
Adjust $target_vm (VM_NAME) and $salt_command (state.highstate).
6. Execute them, fix problems, repeat.
## Known Pitfalls
### Using fedora-24-minimal
The fedora-24-minimal package is missing the `sudo` package.
You can install it via:
```shell_session
$ qvm-run -p -u root fedora-24-minimal-template 'dnf install -y sudo'
```
The `-p` will cause the execution to wait until the package is installed.
Having the `-p` flag is important when using a state with `cmd.run`.
### Disk Quota Exceeded (When Installing Templates)
If you install multiple templates you may encounter this error.
The solution is to shut down the updateVM between each install:
```
install template and shutdown updateVM:
cmd.run:
- name: sudo qubes-dom0-update -y fedora-24; qvm-shutdown {% raw %}{{ salt.cmd.run(qubes-prefs updateVM) }}{% endraw %}
```
## Further Reading
- [Salt documentation](https://docs.saltstack.com/en/latest/)
- [Salt states](https://docs.saltstack.com/en/latest/ref/states/all/) ([files](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html), [commands](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.file.html),
[packages](https://docs.saltstack.com/en/latest/ref/states/all/salt.states.pkg.html), [ordering](https://docs.saltstack.com/en/latest/ref/states/ordering.html))
- [Top files](https://docs.saltstack.com/en/latest/ref/states/top.html)
- [Jinja templates](http://jinja.pocoo.org/)
- [Qubes specific modules](https://github.com/QubesOS/qubes-mgmt-salt-dom0-qvm/blob/master/README.rst)
- [Formulas for default Qubes VMs](https://github.com/QubesOS/qubes-mgmt-salt-dom0-virtual-machines/tree/master/qvm)

115
user/advanced-topics/secondary-storage.md Normal file
View file

@ -0,0 +1,115 @@
---
lang: en
layout: doc
permalink: /doc/secondary-storage/
redirect_from:
- /en/doc/secondary-storage/
- /doc/SecondaryStorage/
- /wiki/SecondaryStorage/
ref: 187
title: Secondary Storage
---
Suppose you have a fast but small primary SSD and a large but slow secondary HDD.
You want to store a subset of your AppVMs on the HDD.
## Instructions
Qubes 4.0 is more flexible than earlier versions about placing different VMs on different disks.
For example, you can keep templates on one disk and AppVMs on another, without messy symlinks.
These steps assume you have already created a separate [volume group](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/vg_admin#VG_create) and [thin pool](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/logical_volume_manager_administration/thinly_provisioned_volume_creation) (not thin volume) for your HDD.
See also [this example](https://www.linux.com/blog/how-full-encrypt-your-linux-system-lvm-luks) if you would like to create an encrypted LVM pool (but note you can use a single logical volume if preferred, and to use the `-T` option on `lvcreate` to specify it is thin). You can find the commands for this example applied to Qubes at the bottom of this R4.0 section.
First, collect some information in a dom0 terminal:
```
sudo pvs
sudo lvs
```
Take note of the VG and thin pool names for your HDD, then register it with Qubes:
```shell_session
# <pool_name> is a freely chosen pool name
# <vg_name> is LVM volume group name
# <thin_pool_name> is LVM thin pool name
qvm-pool --add <pool_name> lvm_thin -o volume_group=<vg_name>,thin_pool=<thin_pool_name>,revisions_to_keep=2
```
Now, you can create qubes in that pool:
```
qvm-create -P <pool_name> --label red <vmname>
```
It isn't possible to directly migrate an existing qube to the new pool, but you can clone it there, then remove the old one:
```
qvm-clone -P <pool_name> <sourceVMname> <cloneVMname>
qvm-remove <sourceVMname>
```
If that was a template, or other qube referenced elsewhere (NetVM or such), you will need to adjust those references manually after moving.
For example:
```
qvm-prefs <appvmname_based_on_old_template> template <new_template_name>
```
In theory, you can still use file-based disk images ("file" pool driver), but it lacks some features such as you won't be able to do backups without shutting down the qube.
### Example HDD setup
Assuming the secondary hard disk is at /dev/sdb (it will be completely erased), you can set it up for encryption by doing in a dom0 terminal (use the same passphrase as the main Qubes disk to avoid a second password prompt at boot):
```
sudo cryptsetup luksFormat --hash=sha512 --key-size=512 --cipher=aes-xts-plain64 --verify-passphrase /dev/sdb
sudo blkid /dev/sdb
```
Note the device's UUID (in this example "b209..."), we will use it as its luks name for auto-mounting at boot, by doing:
```
sudo nano /etc/crypttab
```
And adding this line (change both "b209..." for your device's UUID from blkid) to crypttab:
```
luks-b20975aa-8318-433d-8508-6c23982c6cde UUID=b20975aa-8318-433d-8508-6c23982c6cde none
```
Reboot the computer so the new luks device appears at /dev/mapper/luks-b209... and we can then create its pool, by doing this on a dom0 terminal (substitute the b209... UUIDs with yours):
First create the physical volume
```
sudo pvcreate /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
```
Then create the LVM volume group, we will use for example "qubes" as the <vg_name>:
```
sudo vgcreate qubes /dev/mapper/luks-b20975aa-8318-433d-8508-6c23982c6cde
```
And then use "poolhd0" as the <thin_pool_name> (LVM thin pool name):
```
sudo lvcreate -T -n poolhd0 -l +100%FREE qubes
```
Finally we will tell Qubes to add a new pool on the just created thin pool
```
qvm-pool --add poolhd0_qubes lvm_thin -o volume_group=qubes,thin_pool=poolhd0,revisions_to_keep=2
```
By default VMs will be created on the main Qubes disk (i.e. a small SSD), to create them on this secondary HDD do the following on a dom0 terminal:
```
qvm-create -P poolhd0_qubes --label red unstrusted-hdd
```

338
user/advanced-topics/standalone-and-hvm.md Normal file
View file

@ -0,0 +1,338 @@
---
lang: en
layout: doc
permalink: /doc/standalone-and-hvm/
redirect_from:
- /doc/hvm/
- /doc/hvm-create/
- /en/doc/hvm-create/
- /doc/HvmCreate/
- /wiki/HvmCreate/
ref: 130
title: StandaloneVMs and HVMs
---
A [StandaloneVM](/doc/glossary/#standalonevm) is a type of VM in Qubes that is created by cloning a [TemplateVM](/doc/templates/).
Unlike TemplateVMs, however, StandaloneVMs do not supply their root filesystems to other VMs.
Examples of situations in which StandaloneVMs can be useful include:
- VMs used for development (dev environments often require a lot of specific packages and tools)
- VMs used for installing untrusted packages.
Normally, you install digitally signed software from Red Hat/Fedora repositories, and it's reasonable that such software has non malicious *installation* scripts (rpm pre/post scripts).
However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone VM might be a better way.
Meanwhile, a [Hardware-assisted Virtual Machine (HVM)](/doc/glossary/#hvm), also known as a "Fully-Virtualized Virtual Machine," utilizes the virtualization extensions of the host CPU.
These are typically contrasted with [Paravirtualized (PV)](/doc/glossary/#pv) VMs.
HVMs allow you to create qubes based on any OS for which you have an installation ISO, so you can easily have qubes running Windows, *BSD, or any Linux distribution.
You can also use HVMs to run "live" distros.
By default, every Qubes VM runs in [PVH](/doc/glossary/#pvhvm) mode (which has security advantages over both PV and HVM) except for those with attached PCI devices, which run in HVM mode.
See [here](https://blog.invisiblethings.org/2017/07/31/qubes-40-rc1.html) for a discussion of the switch from PV to HVM and [here](/news/2018/01/11/qsb-37/) for the announcement about the change to using PVH as default.
The StandaloneVM/TemplateVM distinction and the HVM/PV/PVH distinctions are orthogonal.
The former is about root filesystem inheritance, whereas the latter is about the virtualization mode.
In practice, however, it is most common for StandaloneVMs to be HVMs and for HVMs to be StandaloneVMs.
In fact, this is so common that [StandaloneHVMs](/doc/glossary/#standalonehvm) are typically just called "HVMs."
Hence, this page covers both topics.
## Creating a StandaloneVM
You can create a StandaloneVM in the Qube Manager by selecting the "Type" of "Standalone qube copied from a template" or "Empty standalone qube (install your own OS)."
Alternatively, from the dom0 command line:
```
qvm-create --class StandaloneVM --label <label> --property virt_mode=hvm <vmname>
```
(Note: Technically, `virt_mode=hvm` is not necessary for every StandaloneVM.
However, it makes sense if you want to use a kernel from within the VM.)
## Creating an HVM
### Using the GUI:
In Qube Manager, select "Create new qube" from the Qube menu, or select the "Create a new qube" button.
In the "create new qube" dialog box set Type to "Empty standalone qube (install your own OS)".
If "install system from device" is selected (which is by default), then `virt_mode` will be set to `hvm` automatically.
Otherwise, open the newly created qube's Settings GUI and in the "Advanced" tab select `HVM` in the virtualization mode drop-down list.
Also, make sure "Kernel" is set to `(none)` on the same tab.
## Command line:
Qubes are template-based by default so you must set the `--class StandaloneVM` option to create a StandaloneVM:
(name and label color are for illustration purposes).
~~~
qvm-create my-new-vm --class StandaloneVM --property virt_mode=hvm --property kernel='' --label=green
~~~
If you receive an error like this one, then you must first enable VT-x in your BIOS:
~~~
libvirt.libvirtError: invalid argument: could not find capabilities for arch=x86_64
~~~
Make sure that you give the new qube adequate memory to install and run.
## Installing an OS in an HVM
You will have to boot the qube with the installation media "attached" to it. You may either use the GUI or use command line instructions.
At the command line you can do this in three ways:
1. If you have the physical cdrom media and a disk drive
~~~
qvm-start my-new-vm --cdrom=/dev/cdrom
~~~
2. If you have an ISO image of the installation media located in dom0
~~~
qvm-start my-new-vm --cdrom=dom0:/usr/local/iso/installcd.iso
~~~
3. If you have an ISO image of the installation media located in a qube (obviously the qube where the media is located must be running)
~~~
qvm-start my-new-vm --cdrom=someVM:/home/user/installcd.iso
~~~
For security reasons you should *never* copy untrusted data to dom0. Qubes doesn't provide any easy to use mechanism for copying files between qubes and Dom0 and generally tries to discourage such actions.
Next, the qube will start booting from the attached installation media, and you can start installation.
Whenever the installer wants to "reboot the system" it actually shuts down the qube, and Qubes won't automatically start it.
You may have to restart the qube several times in order to complete installation, (as is the case with Windows 7 installations).
Several invocations of `qvm-start` command (as shown above) might be needed.
## Setting up networking for HVMs
Just like standard paravirtualized AppVMs, the HVM qubes get fixed IP addresses centrally assigned by Qubes.
Normally Qubes agent scripts (or services on Windows) running within each AppVM are responsible for setting up networking within the VM according to the configuration created by Qubes (through [keys](/doc/vm-interface/#qubesdb) exposed by dom0 to the VM).
Such centrally managed networking infrastructure allows for [advanced networking configuration](https://blog.invisiblethings.org/2011/09/28/playing-with-qubes-networking-for-fun.html).
A generic HVM domain such as a standard Windows or Ubuntu installation, however, has no Qubes agent scripts running inside it initially and thus requires manual configuration of networking so that it matches the values assigned by Qubes for this qube.
Even though we do have a small DHCP server that runs inside HVM untrusted stub domain to make the manual network configuration unnecessary for many VMs, this won't work for most modern Linux distributions which contain Xen networking PV drivers (but not Qubes tools) which bypass the stub-domain networking (their net frontends connect directly to the net backend in the netvm).
In this instance our DHCP server is not useful.
In order to manually configure networking in a VM, one should first find out the IP/netmask/gateway assigned to the particular VM by Qubes.
This can be seen e.g. in the Qube Manager in the qube's properties:
![r2b1-manager-networking-config.png](/attachment/wiki/HvmCreate/r2b1-manager-networking-config.png)
Alternatively, one can use the `qvm-ls -n` command to obtain the same information, (IP/netmask/gateway).
The DNS IP addresses are `10.139.1.1` and `10.139.1.2`.
There is [opt-in support](/doc/networking/#ipv6) for IPv6 forwarding.
## Using TemplateBasedHVMs
Qubes allows HVMs to share a common root filesystem from a select TemplateVM (see [TemplateHVM](/doc/glossary/#templatehvm) and [TemplateBasedHVM](/doc/glossary/#templatebasedhvm)).
This mode can be used for any HVM (e.g. FreeBSD running in a HVM).
In order to create a TemplateHVM you use the following command, suitably adapted:
~~~
qvm-create --class TemplateVM <qube> --property virt_mode=HVM --property kernel='' -l green
~~~
Set memory as appropriate, and install the OS into this template in the same way you would install it into a normal HVM -- please see instructions on [this page](/doc/hvm-create/).
Generally you should install in to the first "system" disk. (Resize it as needed before starting installation.)
You can then create a new qube using the new template.
If you use this Template as it is, then any HVMs that use it will effectively be DisposableVMs - all file system changes will be wiped when the HVM is closed down.
Please see [this page](/doc/windows-appvms/) for specific advice on installing and using Windows-based Templates.
## Cloning HVMs
Just like normal AppVMs, the HVM domains can also be cloned either using the command-line `qvm-clone` or via the Qube Manager's 'Clone VM' option in the right-click menu.
The cloned VM will get identical root and private images and will essentially be identical to the original VM except that it will get a different MAC address for the networking interface:
~~~
[joanna@dom0 ~]$ qvm-prefs my-new-vm
name : my-new-vm
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/my-new-vm
config : /var/lib/qubes/appvms/my-new-vm/my-new-vm.conf
pcidevs : []
root img : /var/lib/qubes/appvms/my-new-vm/root.img
private img : /var/lib/qubes/appvms/my-new-vm/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
[joanna@dom0 ~]$ qvm-clone my-new-vm my-new-vm-copy
/.../
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy
name : my-new-vm-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/my-new-vm-copy
config : /var/lib/qubes/appvms/my-new-vm-copy/my-new-vm-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/my-new-vm-copy/root.img
private img : /var/lib/qubes/appvms/my-new-vm-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:01 (auto)
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
~~~
Note how the MAC addresses differ between those two otherwise identical VMs.
The IP addresses assigned by Qubes will also be different of course to allow networking to function properly:
~~~
[joanna@dom0 ~]$ qvm-ls -n
/.../
my-new-vm-copy | | Halted | Yes | | *firewallvm | green | 10.137.2.3 | n/a | 10.137.2.1 |
my-new-vm | | Halted | Yes | | *firewallvm | green | 10.137.2.7 | n/a | 10.137.2.1 |
/.../
~~~
If for any reason you would like to make sure that the two VMs have the same MAC address, you can use `qvm-prefs` to set a fixed MAC address for the VM:
~~~
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy -s mac 00:16:3E:5E:6C:05
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy
name : my-new-vm-copy
label : green
type : HVM
netvm : firewallvm
updateable? : True
installed by RPM? : False
include in backups: False
dir : /var/lib/qubes/appvms/my-new-vm-copy
config : /var/lib/qubes/appvms/my-new-vm-copy/my-new-vm-copy.conf
pcidevs : []
root img : /var/lib/qubes/appvms/my-new-vm-copy/root.img
private img : /var/lib/qubes/appvms/my-new-vm-copy/private.img
vcpus : 4
memory : 512
maxmem : 512
MAC : 00:16:3E:5E:6C:05
debug : off
default user : user
qrexec_installed : False
qrexec timeout : 60
drive : None
timezone : localtime
~~~
## Assigning PCI devices to HVMs
HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs.
E.g. one can assign one of the USB controllers to the Windows VM and should be able to use various devices that require Windows software, such as phones, electronic devices that are configured via FTDI, etc.
One problem at the moment however, is that after the whole system gets suspended into S3 sleep and subsequently resumed, some attached devices may stop working and should be restarted within the VM.
This can be achieved under a Windows HVM by opening the Device Manager, selecting the actual device (such as a USB controller), 'Disabling' the device, and then 'Enabling' the device again.
This is illustrated on the screenshot below:
![r2b1-win7-usb-disable.png](/attachment/wiki/HvmCreate/r2b1-win7-usb-disable.png)
## Converting VirtualBox VMs to Qubes HVMs
You can convert any VirtualBox VM to a Qubes HVM using this method.
For example, Microsoft provides [free 90 day evaluation VirtualBox VMs for browser testing](https://developer.microsoft.com/en-us/microsoft-edge/tools/vms/).
About 60 GB of disk space is required for conversion.
Use an external harddrive if needed.
The final root.img size is 40 GB.
In Debian AppVM, install `qemu-utils` and `unzip`:
~~~
sudo apt install qemu-utils unzip
~~~
Unzip VirtualBox zip file:
~~~
unzip *.zip
~~~
Extract OVA tar archive:
~~~
tar -xvf *.ova
~~~
Convert vmdk to raw:
~~~
qemu-img convert -O raw *.vmdk win10.raw
~~~
Copy the root image file from the originating qube (here called `untrusted`) to a temporary location in dom0, typing this in a Dom0 terminal:
~~~
qvm-run --pass-io untrusted 'cat "/media/user/externalhd/win10.raw"' > /home/user/win10-root.img
~~~
From within Dom0, create a new HVM (here called `win10`) with the root image we just copied to Dom0 (change the amount of RAM in GB as you wish):
~~~
qvm-create --property=virt_mode=hvm --property=memory=4096 --property=kernel='' --label red --standalone --root-move-from /home/user/win10-root.img win10
~~~
Start win10 VM:
~~~
qvm-start win10
~~~
**Optional ways to get more information**
Filetype of OVA file:
~~~
file *.ova
~~~
List files of OVA tar archive:
~~~
tar -tf *.ova
~~~
List filetypes supported by qemu-img:
~~~
qemu-img -h | tail -n1
~~~
## Further reading
Other documents related to HVM:
- [Windows VMs](/doc/windows-vm/)
- [LinuxHVMTips](/doc/linux-hvm-tips/)

204
user/advanced-topics/usb-qubes.md Normal file
View file

@ -0,0 +1,204 @@
---
lang: en
layout: doc
permalink: /doc/usb-qubes/
redirect_from:
- /doc/usbvm/
- /en/doc/usbvm/
- /doc/USBVM/
- /wiki/USBVM/
- /doc/sys-usb/
ref: 181
title: USB Qubes
---
If during installation you enabled the creation of a USB-qube, your system should be setup already and none of the mentioned steps here should be necessary. (Unless you want to [remove your USB-qube](#removing-a-usb-qube).) If for any reason no USB-qube was created during installation, this guide will show you how to do so.
**Caution:** If you want to use a USB-keyboard, please beware of the possibility to lock yourself out! To avoid this problem [enable your keyboard for login](#enable-a-usb-keyboard-for-login)!
## Creating and Using a USB qube ##
**Warning:** This has the potential to prevent you from connecting a keyboard to Qubes via USB.
There are problems with doing this in an encrypted install (LUKS).
If you find yourself in this situation, see this [issue](https://github.com/QubesOS/qubes-issues/issues/2270#issuecomment-242900312).
A USB qube acts as a secure handler for potentially malicious USB devices, preventing them from coming into contact with dom0 (which could otherwise be fatal to the security of the whole system). It thereby mitigates some of the [security implications](/doc/device-handling-security/#usb-security) of using USB devices.
With a USB qube, every time you connect an untrusted USB drive to a USB port managed by that USB controller, you will have to attach it to the qube in which you wish to use it (if different from the USB qube itself), either by using Qubes VM Manager or the command line (see instructions above).
The USB controller may be assigned on the **Devices** tab of a qube's settings page in Qubes VM Manager or by using the [qvm-pci](/doc/pci-devices/) command.
For guidance on finding the correct USB controller, see the [according passage on PCI-devices](/doc/usb-devices/#finding-the-right-usb-controller).
You can create a USB qube using the management stack by performing the following steps as root in dom0:
```
sudo qubesctl state.sls qvm.sys-usb
```
Alternatively, you can create a USB qube manually as follows:
1. Read the [PCI Devices](/doc/pci-devices/) page to learn how to list and identify your USB controllers.
Carefully check whether you have a USB controller that would be appropriate to assign to a USB qube.
Note that it should be free of input devices, programmable devices, and any other devices that must be directly available to dom0.
If you find a free controller, note its name and proceed to step 2.
2. Create a new qube.
Give it an appropriate name and color label (recommended: `sys-usb`, red).
3. In the qube's settings, go to the "Devices" tab.
Find the USB controller that you identified in step 1 in the "Available" list.
Move it to the "Selected" list by highlighting it and clicking the single arrow `>` button.
**Caution:** By assigning a USB controller to a USB qube, it will no longer be available to dom0.
This can make your system unusable if, for example, you have only one USB controller, and you are running Qubes off of a USB drive.
4. Click `OK`.
Restart the qube.
5. Recommended: Check the box on the "Basic" tab which says "Start VM automatically on boot".
(This will help to mitigate attacks in which someone forces your system to reboot, then plugs in a malicious USB device.)
If the USB qube will not start, please have a look at the [faq](/faq/#i-created-a-usb-vm-and-assigned-usb-controllers-to-it-now-the-usb-vm-wont-boot).
## Enable a USB keyboard for login ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding!
If you use USB keyboard, automatic USB qube creation during installation is disabled.
Additional steps are required to avoid locking you out from the system.
Those steps are not performed by default, because of risk explained in [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices).
### Automatic setup ###
To allow USB keyboard usage (including early boot for LUKS passphrase), make sure you have the latest `qubes-mgmt-salt-dom0-virtual-machines` package (simply [install dom0 updates](/doc/software-update-dom0/#how-to-update-dom0)) and execute in dom0:
```
sudo qubesctl state.sls qvm.usb-keyboard
```
The above command will take care of all required configuration, including creating USB qube if not present.
Note that it will expose dom0 to USB devices while entering LUKS passphrase.
Users are advised to physically disconnect other devices from the system for that time, to minimize the risk.
To undo these changes, please follow the section on [**Removing a USB qube**](#removing-a-usb-qube)!
If you wish to perform only a subset of this configuration (for example do not enable USB keyboard during boot), see manual instructions below.
### Manual setup ###
In order to use a USB keyboard, you must first attach it to a USB qube, then give that qube permission to pass keyboard input to dom0.
Edit the `qubes.InputKeyboard` policy file in dom0, which is located here:
```
/etc/qubes-rpc/policy/qubes.InputKeyboard
```
Add a line like this one to the top of the file:
```
sys-usb dom0 allow
```
(Change `sys-usb` to your desired USB qube.)
You can now use your USB keyboard to login and for LUKS decryption during boot.
For a confirmation dialog each time the USB keyboard is connected, *which will effectively disable your USB keyboard for login and LUKS decryption*, change this line to:
```
sys-usb dom0 ask,default_target=dom0
```
*Don't do that if you want to unlock your device with a USB keyboard!*
Additionally, if you want to use USB keyboard to enter LUKS passphrase, it is incompatible with [hiding USB controllers from dom0](#how-to-hide-all-usb-controllers-from-dom0).
You need to revert that procedure (remove `rd.qubes.hide_all_usb` option from files mentioned there) and employ alternative protection during system boot - disconnect other devices during startup.
## Auto Enabling A USB Mouse ##
**Caution:** Please carefully read the [Security Warning about USB Input Devices](/doc/device-handling-security/#security-warning-on-usb-input-devices) before proceeding.
Handling a USB mouse isn't as critical as handling a keyboard, since you can login using the keyboard and accept the popup dialogue using your keyboard alone.
If you want to attach the USB mouse automatically anyway, you have to edit the `qubes.InputMouse` policy file in dom0, located at:
```
/etc/qubes-rpc/policy/qubes.InputMouse
```
The first line should read similar to:
```
sys-usb dom0 ask,default_target=dom0
```
which will ask for conformation each time a USB mouse is attached. If the file is empty or does not exist, maybe something went wrong during setup, try to rerun `qubesctl state.sls qvm.sys-usb` in dom0.
In case you are absolutely sure you do not want to confirm mouse access from `sys-usb` to `dom0`, you may add the following line on top of the file:
```
sys-usb dom0 allow
```
(Change `sys-usb` to your desired USB qube.)
## How to hide all USB controllers from dom0 ##
(Note: `rd.qubes.hide_all_usb` is set automatically if you opt to create a USB qube during installation.
This also occurs automatically if you choose to [create a USB qube](#creating-and-using-a-usb-qube) using the `qubesctl` method, which is the
first pair of steps in the linked section.)
**Warning:** A USB keyboard cannot be used to type the disk passphrase if USB controllers were hidden from dom0.
Before hiding USB controllers, make sure your laptop keyboard is not internally connected via USB (by checking output of the `lsusb` command) or that you have a PS/2 keyboard at hand (if using a desktop PC).
Failure to do so will render your system unusable.
If you create a USB qube manually, there will be a brief period of time during the boot process when dom0 will be exposed to your USB controllers (and any attached devices).
This is a potential security risk, since even brief exposure to a malicious USB device could result in dom0 being compromised.
There are two approaches to this problem:
1. Physically disconnect all USB devices whenever you reboot the host.
2. Hide (i.e., blacklist) all USB controllers from dom0.
**Warning:** If you use a USB [AEM](/doc/anti-evil-maid/) device, do not use the second option.
Using a USB AEM device requires dom0 to have access to the USB controller to which your USB AEM device is attached.
If dom0 cannot read your USB AEM device, AEM will hang.
The procedure to hide all USB controllers from dom0 is as follows:
* GRUB2
1. Open the file `/etc/default/grub` in dom0.
2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
3. Add `rd.qubes.hide_all_usb` to that line.
4. Save and close the file.
5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
6. Reboot.
* EFI
1. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
2. Find the lines that begin with `kernel=`. There may be more than one.
3. Add `rd.qubes.hide_all_usb` to those lines.
4. Save and close the file.
5. Reboot.
## Removing a USB qube ##
**Warning:** This procedure will result in your USB controller(s) being attached directly to dom0.
* GRUB2
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/etc/default/grub` in dom0.
4. Find the line(s) that begins with `GRUB_CMDLINE_LINUX`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
8. Reboot.
* EFI
1. Shut down the USB qube.
2. In Qubes Manager, right-click on the USB qube and select "Remove VM."
3. Open the file `/boot/efi/EFI/qubes/xen.cfg` in dom0.
4. Find the line(s) that begins with `kernel=`.
5. If `rd.qubes.hide_all_usb` appears anywhere in those lines, remove it.
6. Save and close the file.
7. Reboot.

51
user/advanced-topics/volume-backup-revert.md Normal file
View file

@ -0,0 +1,51 @@
---
lang: en
layout: doc
permalink: /doc/volume-backup-revert/
redirect_from:
- /en/doc/volume-backup-revert/
- /doc/VolumeBackupRevert/
- /wiki/VolumeBackupRevert/
ref: 206
title: Volume Backup and Revert
---
With Qubes, it is possible to revert one of a VM's storage volumes to a previous
state using the automatic snapshot that is normally saved every time a VM is
shutdown. (Note that this is a different, lower level activity than the
[Backup, Restoration, and Migration](/doc/backup-restore/) process.)
In Qubes, when you create a new VM, it's volumes are stored in one of the
system's [Storage Pools](/doc/storage-pools/). On pool creation, a
revisions_to_keep default value is set for the entire pool. (For a pool creation
example, see [Storing AppVMs on Secondary Drives](/doc/secondary-storage/).)
Thereafter, each volume associated with a VM that is stored in this pool
inherits the pool default revisions_to_keep.
For the private volume associated with a VM named vmname, you may inspect the
value of revisions_to_keep from the dom0 CLI as follows:
```
qvm-volume info vmname:private
```
The output of the above command will also display the "Available revisions
(for revert)" at the bottom. For a very large volume in a small pool,
revisions_to_keep should probably be set to the minimum value of 1 to minimize
the possibility of the pool being accidentally filled up by snapshots. For a
smaller volume for which you would like to have the future option of reverting,
revisions_to_keep should probably be set to at least 2. To set
revisions_to_keep for this same VM / volume example:
```
qvm-volume config vmname:private revisions_to_keep 2
```
With the VM stopped, you may revert to an older snapshot of the private volume
from the the above list of "Available revisions (for revert)", where the last
item on the list with the largest integer is the most recent snapshot:
```
qvm-volume revert vmname:private <revision>
```

18
user/advanced-topics/windows.md Normal file
View file

@ -0,0 +1,18 @@
---
lang: en
layout: doc
permalink: /doc/windows/
ref: 129
title: Windows VMs
---
Like any other unmodified OSes, Windows can be installed in Qubes as an [HVM](/doc/standalone-and-hvm/) domain.
Qubes Windows Tools are then usually installed to provide integration with the rest of the Qubes system; they also include Xen's paravirtualized (PV) drivers to increase performance compared to qemu emulated devices. Alternatively, only Xen's PV drivers can be installed if integration with Qubes isn't required or if the tools aren't supported on a give version of Windows. In the latter case, one would have to [enable inter-VM networking](/doc/firewall/#enabling-networking-between-two-qubes) to be able to exchange files with HVMs.
For more information about Windows VMs in Qubes OS, please see the following external resources:
* [Installing and Using Windows-based VMs](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md)
* [Installing and Using Qubes Windows Tools](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md)
* [Issue #3585 - Installation and know limitations of Qubes Windows Tools in Qubes R4.0](https://github.com/QubesOS/qubes-issues/issues/3585)