Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'mass-replace-terms'

Browse Source 
QubesOS/qubes-issues#1015
This commit is contained in:
Andrew David Wong 2021-06-18 04:03:33 -07:00
commit ba376404e0
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
57 changed files with 597 additions and 598 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
introduction/faq.md
View File

@ -78,7 +78,7 @@ For more information about how to use this powerful tool correctly and safely, p
### What about privacy in non-Whonix qubes?
Qubes OS does not claim to provide special privacy (as opposed to security) properties in non-[Whonix](/doc/whonix/) qubes.
This includes [DisposableVMs](/doc/disposablevm/).
This includes [disposables](/doc/how-to-use-disposables/).
For example, a standard [Fedora](/doc/templates/fedora/) qube is expected to have basically the same privacy properties as that upstream Fedora distribution, enhanced to some degree by the control Qubes provides over that qube.
For most users, this level of privacy may be good enough for many common activities.
@ -88,7 +88,7 @@ Privacy is far more difficult than is commonly understood.
In addition to the [web browser](https://www.torproject.org/projects/torbrowser/design/), there is also [VM fingerprinting](https://www.whonix.org/wiki/VM_Fingerprinting) and [advanced deanonymization attacks](https://www.whonix.org/wiki/Advanced_Deanonymization_Attacks) that most users have never considered (and this is just to mention a few examples).
The [Whonix Project](https://www.whonix.org/) specializes in [protecting against these risks](https://www.whonix.org/wiki/Protocol-Leak-Protection_and_Fingerprinting-Protection).
In order to achieve the same results in non-Whonix qubes (including DisposableVMs), one would have to reinvent Whonix.
In order to achieve the same results in non-Whonix qubes (including disposables), one would have to reinvent Whonix.
Such duplication of effort makes no sense when Whonix already exists and is already integrated into Qubes OS.
Therefore, when you need privacy, you should use Whonix qubes.
@ -325,7 +325,7 @@ Those won’t fly.
We do not provide GPU virtualization for Qubes.
This is mostly a security decision, as implementing such a feature would most likely introduce a great deal of complexity into the GUI virtualization infrastructure.
However, Qubes does allow for the use of accelerated graphics (e.g. OpenGL) in dom0’s Window Manager, so all the fancy desktop effects should still work.
AppVMs use a software-only (CPU-based) implementation of OpenGL, which may be good enough for basic games and applications.
App qubes use a software-only (CPU-based) implementation of OpenGL, which may be good enough for basic games and applications.
For further discussion about the potential for GPU passthrough on Xen/Qubes, please see the following threads:
@ -357,9 +357,9 @@ See [Certified Hardware](/doc/certified-hardware/).
### How much disk space does each qube require?
Each qube is created from a TemplateVM and shares the root filesystem with this TemplateVM (in a read-only manner).
Each qube is created from a template and shares the root filesystem with this template (in a read-only manner).
This means that each qube needs only as much disk space as is necessary to store its own private data.
This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the TemplateVM upon which those qubes are based.
This also means that it is possible to update the software for several qubes simultaneously by running a single update process in the template upon which those qubes are based.
(These qubes will then have to be restarted in order for the update to take effect in them.)
### How much memory is recommended for Qubes?
@ -424,8 +424,8 @@ See introductions on Wikibooks: [here](https://en.wikibooks.org/wiki/Fedora_And_
You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes.
You may need to install a binary blob, which provides drivers, from the linux-firmware package.
Open a terminal and run `sudo dnf install linux-firmware` in the TemplateVM upon which your NetVM is based.
You have to restart the NetVM after the TemplateVM has been shut down.
Open a terminal and run `sudo dnf install linux-firmware` in the template upon which your NetVM is based.
You have to restart the NetVM after the template has been shut down.
### Can I install Qubes OS together with other operating system (dual-boot/multi-boot)?
@ -437,21 +437,21 @@ It begins with an explanation of the risks with such a setup.
See [here](/doc/version-scheme/#check-installed-version).
### My qubes lost internet access after a TemplateVM update. What should I do?
### My qubes lost internet access after a template update. What should I do?
See [Update Troubleshooting](/doc/update-troubleshooting/#lost-internet-access-after-a-templatevm-update).
See [Update Troubleshooting](/doc/update-troubleshooting/#lost-internet-access-after-a-template-update).
### My keyboard layout settings are not behaving correctly. What should I do?
See [Hardware Troubleshooting](/doc/hardware-troubleshooting/#keyboard-layout-settings-not-behaving-correctly).
### My dom0 and/or TemplateVM update stalls when attempting to update via the GUI tool. What should I do?
### My dom0 and/or template update stalls when attempting to update via the GUI tool. What should I do?
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run `sudo qubes-dom0-update`.
In your TemplateVMs, open a terminal and run `sudo dnf upgrade`.
In your templates, open a terminal and run `sudo dnf upgrade`.
### How do I run a Windows HVM in non-seamless mode (i.e., as a single window)?
@ -487,12 +487,12 @@ See also [here](/doc/assigning-devices/).
If you're having trouble playing a video file in a qube, you're probably missing the required codecs.
The easiest way to resolve this is to install VLC Media Player and use that to play your video files.
You can do this in multiple different TemplateVM distros (Fedora, Debian, etc.).
You can do this in multiple different template distros (Fedora, Debian, etc.).
For Debian:
1. (Recommended) Clone an existing Debian TemplateVM
2. Install VLC in that TemplateVM:
1. (Recommended) Clone an existing Debian template
2. Install VLC in that template:
```bash_session
$ sudo apt install vlc
@ -502,9 +502,9 @@ For Debian:
For Fedora:
1. (Recommended) Clone an existing Fedora TemplateVM
2. [Enable the appropriate RPMFusion repos in the desired Fedora TemplateVM](/doc/how-to-install-software/#rpmfusion-for-fedora-templatevms).
3. Install VLC in that TemplateVM:
1. (Recommended) Clone an existing Fedora template
2. [Enable the appropriate RPMFusion repos in the desired Fedora template](/doc/how-to-install-software/#rpmfusion-for-fedora-templates).
3. Install VLC in that template:
```bash_session
$ sudo dnf install vlc
@ -577,9 +577,9 @@ From a `dom0` prompt, enter:
qvm-prefs <HVMname> kernel ""
```
### When I try to install a TemplateVM, it says no match is found.
### When I try to install a template, it says no match is found.
See [VM Troubleshooting](/doc/vm-troubleshooting/#no-match-found-when-trying-to-install-a-templatevm).
See [VM Troubleshooting](/doc/vm-troubleshooting/#no-match-found-when-trying-to-install-a-template).
### I keep getting "Failed to synchronize cache for repo" errors when trying to update my Fedora templates
@ -627,7 +627,7 @@ Specifically:
- If PGP signatures are used, the signing key(s) should have well-publicized fingerprint(s) verifiable via multiple independent channels or be accessible to the developers through a web of trust.
- If the software is security-sensitive and requires communication with the outside world, a "split" implementation is highly preferred (for examples, see [Split GPG](/doc/split-gpg/) and [Split Bitcoin](/doc/split-bitcoin/)).
- If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templatevms) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation).
- If the software has dependencies, these should be packaged and available in repos for a [current, Qubes-supported version](/doc/supported-versions/#templates) of Fedora (preferred) or Debian (unless all the insecure dependencies can run in an untrusted VM in a "split" implementation).
- If the software must be built from source, the source code and any builders must be signed.
(Practically speaking, the more cumbersome and time-consuming it is to build from source, the less likely the developers are to use it.)

7
introduction/intro.html
View File

@ -77,8 +77,7 @@ title: Introduction
<h3>Strong isolation</h3>
<p>
Isolate different pieces of software as if they were installed on separate
physical machines using <a href="/doc/glossary/#pv">PV</a> or
<a href="/doc/glossary/#hvm">HVM</a> virtualization techniques.
physical machines using advanced virtualization techniques.
</p>
</div>
<div class="col-lg-4 col-md-4 col-xs-12">
@ -104,9 +103,9 @@ title: Introduction
<div class="row">
<div class="col-lg-4 col-md-4 col-xs-12">
<h3>DisposableVMs</h3>
<h3>Disposables</h3>
<p>
Create <a href="/doc/disposablevm/">DisposableVMs</a> on the fly that
Create <a href="/doc/how-to-use-disposables/">disposables</a> on the fly that
self-destruct when shut down.
</p>
</div>

20
user/advanced-topics/bind-dirs.md
View File

@ -12,22 +12,22 @@ 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.
any arbitrary files or folders can be made persistent in app qubes.
## 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.
In an app qube 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 app qube 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.
In this way sys-whonix can benefit from the Tor anonymity feature 'persistent Tor entry guards' but does not have to be a standalone.
## How to use bind-dirs.sh? ##
In this example, we want to make `/var/lib/tor` persistent.
Inside the TemplateBasedVM.
Inside the app qube.
1. Make sure folder `/rw/config/qubes-bind-dirs.d` exists.
@ -45,7 +45,7 @@ Inside the TemplateBasedVM.
4. Save.
5. Reboot the TemplateBasedVM.
5. Reboot the app qube.
6. Done.
@ -67,17 +67,17 @@ binds+=( '/etc/tor/torrc' )
## 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.
bind-dirs.sh is called at startup of an app qube, 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.
Creation of the files and folders in `/rw/bind-dirs` should be automatic the first time the app qube 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.
* Files that exist in the template root image cannot be deleted in the app qubes 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.
@ -102,5 +102,5 @@ binds=( "${binds[@]/'/var/lib/tor'}" )
## 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)
[app qubes: 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)

6
user/advanced-topics/config-files.md
View File

@ -36,7 +36,7 @@ The scripts here all run as root.
- `/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.
- In ProxyVMs (or app qubes 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.
~~~
@ -49,7 +49,7 @@ The scripts here all run as root.
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`:
- 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 app qube `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
@ -75,7 +75,7 @@ The scripts here all run as root.
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.
Also, take a look at [bind-dirs](/doc/bind-dirs) for instructions on how to easily modify arbitrary system files in an app qube and have those changes persist.
GUI and audio configuration in dom0
-----------------------------------

135
user/advanced-topics/disposablevm-customization.md → user/advanced-topics/disposable-customization.md
View File

@ -1,29 +1,30 @@
---
lang: en
layout: doc
permalink: /doc/disposablevm-customization/
permalink: /doc/disposable-customization/
redirect_from:
- /doc/disposablevm-customization/
- /doc/dispvm-customization/
- /en/doc/dispvm-customization/
- /doc/DispVMCustomization/
- /doc/UserDoc/DispVMCustomization/
- /wiki/UserDoc/DispVMCustomization/
ref: 174
title: DisposableVM Customization
title: Disposable 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:
A [disposable](/doc/disposable/) can be based on any [app qube](/doc/glossary/#app-qube).
You can also choose to use different [disposable templates](/doc/glossary/#disposable-template) for different disposables.
To prepare an app qube to be a disposable 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:
Additionally, if you want to have menu entries for starting applications in disposable based on this app qube (instead of in the app qube itself), you can achieve it with `appmenus-dispvm` feature:
```shell_session
[user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1
@ -33,41 +34,41 @@ Note: application shortcuts that existed before setting this feature will not be
## 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.
If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised.
Therefore, you should not make any risky customizations (e.g., installing untrusted browser plugins) in important disposable templates.
In particular, the *default* disposable template is important because it is used by the "Open in disposable" 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.
For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customizations to it.
## Creating a new DisposableVM Template
## Creating a new disposable 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:
In Qubes 4.0, you're no longer restricted to a single disposable template. Instead, you can create as many as you want. Whenever you start a new disposable, you can choose to base it on whichever disposable template you like.
To create new disposable template, lets say `custom-disposable-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
[user@dom0 ~]$ qvm-create --template debian-9 --label red custom-disposable-template
[user@dom0 ~]$ qvm-prefs custom-disposable-template template_for_dispvms True
[user@dom0 ~]$ qvm-features custom-disposable-template appmenus-dispvm 1
```
Additionally you may want to set it as default DisposableVM Template:
Additionally you may want to set it as default disposable template:
```shell_session
[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposablevm-template
[user@dom0 ~]$ qubes-prefs default_dispvm custom-disposable-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.
The above default is used whenever a qube request starting a new disposable 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.
If you wish to use a [Minimal Template](/doc/templates/minimal/) as a disposable template, please see the [Minimal Template](/doc/templates/minimal/) page.
## Customization of DisposableVM
## Customization of disposable
_**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)._
_**Note:** If you are trying to customize Tor Browser in a Whonix disposable, please consult the [Whonix documentation](https://www.whonix.org/wiki/Tor_Browser/Advanced_Users#disposable_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:
It is possible to change the settings for each new disposable.
This can be done by customizing the disposable 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).
1. Start a terminal in the `fedora-26-dvm` qube (or another disposable 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 disposable 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
@ -76,16 +77,16 @@ This can be done by customizing the DisposableVM Template on which it is based:
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.
- Changing the disposable's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new disposable, you can choose your desired ProxyVM manually (by changing the newly-started disposables settings). This is useful if you sometimes wish to use a disposable with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected disposable.
4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal).
## Using static DisposableVMs for sys-*
## Using static disposables for sys-*
You can use a static DisposableVM for `sys-*` as long as it is stateless.
You can use a static disposable 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.
In most cases `sys-firewall` will also work, even if you have configured app qube 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 app qube.
To create one that has no PCI devices attached, such as for `sys-firewall`:
@ -113,7 +114,7 @@ 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
# optional, if this disposable will be providing networking
qvm-prefs <sys-VMName> provides_network true
~~~
@ -137,52 +138,52 @@ qvm-prefs sys-firewall netvm sys-net2
qubes-prefs clockvm sys-net2
~~~
## Adding programs to DisposableVM Application Menu
## Adding programs to disposable Application Menu
For added convenience, arbitrary programs can be added to the Application Menu of the DisposableVM.
For added convenience, arbitrary programs can be added to the Application Menu of the disposable.
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.
In order to do that, select "Qube settings" entry in selected base app qube, 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
## Create Custom sys-net sys-firewall and sys-usb disposables
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.
Users have the option of creating customized disposables for the `sys-net`, `sys-firewall` and `sys-usb` VMs. In this configuration, a fresh VM instance is created each time a disposable 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.
- Set disposables 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.
Using disposables 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.
>_**Note:**_ Users who want customized VPN or firewall rule sets must create a separate disposable template for use by each disposable. If disposable template customization is not needed, then a single disposable template is used as a template for all disposables.
### Create and configure the DisposableVM Template on which the DisposableVM will be based
### Create and configure the disposable template on which the disposable will be based
1. Create the DisposableVM Template:
1. Create the disposable template:
```shell_session
[user@dom0 ~]$ qvm-create --class AppVM --label gray <DisposableVM-Template-Name>
[user@dom0 ~]$ qvm-create --class AppVM --label gray <disposable-Template-Name>
```
2. _(optional)_ In the DisposableVM Template, add custom firewall rule sets, Qubes VPN scripts, etc.
2. _(optional)_ In the disposable 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:
3. Set the disposable template as template for disposables:
```shell_session
[user@dom0 ~]$ qvm-prefs <DisposableVM-Template-Name> template_for_dispvms true
[user@dom0 ~]$ qvm-prefs <disposable-Template-Name> template_for_dispvms true
```
### Create the sys-net DisposableVM
### Create the sys-net disposable
1. Create `sys-net` DisposableVM based on the DisposableVM Template:
1. Create `sys-net` disposable based on the disposable template:
```shell_session
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label red disp-sys-net
[user@dom0 ~]$ qvm-create --template <disposable-Template-Name> --class DispVM --label red disp-sys-net
```
2. Set `disp-sys-net` virtualization mode to [hvm](/doc/hvm/):
@ -221,7 +222,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[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):
8. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-net is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-net appmenus-dispvm ''
@ -235,12 +236,12 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
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
### Create the sys-firewall disposable
1. Create `sys-firewall` DisposableVM:
1. Create `sys-firewall` disposable:
```shell_session
[user@dom0 ~]$ qvm-create --template <DisposableVM-Template-Name> --class DispVM --label green disp-sys-firewall
[user@dom0 ~]$ qvm-create --template <disposable-Template-Name> --class DispVM --label green disp-sys-firewall
```
2. Set `disp-sys-firewall` to provide network for other VMs:
@ -255,7 +256,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[user@dom0 ~]$ qvm-prefs disp-sys-firewall netvm disp-sys-net
```
4. Set `disp-sys-firewall` as NetVM for other AppVMs:
4. Set `disp-sys-firewall` as NetVM for other app qubes:
```shell_session
[user@dom0 ~]$ qvm-prefs <vm_name> netvm disp-sys-firewall
@ -267,7 +268,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[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):
6. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-firewall is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-firewall appmenus-dispvm ''
@ -279,12 +280,12 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[user@dom0 ~]$ qubes-prefs default_netvm disp-sys-firewall
```
### Create the sys-usb DisposableVM
### Create the sys-usb disposable
1. Create the `disp-sys-usb`:
```shell_session
[user@dom0 ~]$ qvm-create --template <disposablevm-template-name> --class DispVM --label red disp-sys-usb
[user@dom0 ~]$ qvm-create --template <disposable-template-name> --class DispVM --label red disp-sys-usb
```
2. Set the `disp-sys-usb` virtualization mode to hvm:
@ -318,7 +319,7 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
[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):
7. _(recommended)_ Disable the `appmenus-dispvm` feature, as disp-sys-usb is not itself a disposable template (Note: this is only necessary if you enabled the `appmenus-dispvm` feature for the disposable template):
```shell_session
[user@dom0 ~]$ qvm-features disp-sys-usb appmenus-dispvm ''
@ -339,9 +340,9 @@ Using DisposableVMs in this manner is ideal for untrusted qubes which require pe
disp-sys-usb dom0 allow,user=root
```
### Starting the DisposableVMs
### Starting the disposables
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.
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 disposables fail to start.
Detach PCI device from VM:
@ -353,28 +354,28 @@ Detach PCI device from VM:
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
## Deleting disposables
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:
While working in a disposable, you may want to open a document in another disposable.
For this reason, the property `default_dispvm` may be set to the name of your disposable in a number of VMs:
```shell_session
[user@dom0 ~]$ qvm-prefs workvm | grep default_dispvm
default_dispvm - custom-disposablevm-template
default_dispvm - custom-disposable-template
```
This will prevent the deletion of the DisposableVM Template. In order to fix this you need to unset the `default_dispvm` property:
This will prevent the deletion of the disposable 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:
You can then delete the disposable template:
```shell_session
[user@dom0 ~]$ qvm-remove custom-disposablevm-template
[user@dom0 ~]$ qvm-remove custom-disposable-template
This will completely remove the selected VM(s)
custom-disposablevm-template
custom-disposable-template
```

2
user/advanced-topics/how-to-install-software-in-dom0.md
View File

@ -31,7 +31,7 @@ This separation of duties significantly reduces the attack surface, since all of
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.
While we could, in theory, write a custom solution, it would only be effective if Qubes repos included all of the regular template distro's updates, and this would be far too costly for us to maintain.
## How to update dom0

4
user/advanced-topics/installing-contributed-packages.md
View File

@ -35,8 +35,8 @@ In a Debian-based template, use `apt`:
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:
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 template.
For example, in a Fedora template on Qubes 4.0, the new repository definition would be:
```
/etc/yum.repos.d/qubes-contrib-vm-r4.0.repo

2
user/advanced-topics/managing-vm-kernels.md
View File

@ -278,7 +278,7 @@ Booting to a kernel inside the template is not supported under `PVH`.
#### Distribution kernel
Apply the following instruction in a Debian TemplateVM or in a Debian StandaloneVM.
Apply the following instruction in a Debian template or in a Debian standalone.
Using a distribution kernel package the initramfs and kernel modules should be handled automatically.

10
user/advanced-topics/mount-from-other-os.md
View File

@ -17,14 +17,14 @@ These functions are manual and do not require any Qubes specific tools. All step
- 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.
Before beginning, if attempting to access one Qubes system from another, it is recommended to pass the entire encrypted Qubes disk to an isolated app qube.
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.
1. Open a Linux terminal in either dom0 or the app qube 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`.
```
@ -58,7 +58,7 @@ Decrypting the 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.
3. If using an app qube 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.
@ -77,7 +77,7 @@ Mounting the disk
| ----------------------------- | ----------------- | ------------------------------------------- |
| 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/<vm>-root | template root | The root partition of the named template. |
| 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>`.
@ -91,7 +91,7 @@ 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.
Thes steps must occur either in an app qube 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`.

2
user/advanced-topics/resize-disk-image.md
View File

@ -85,7 +85,7 @@ 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).
Qubes will automatically grow the filesystem for you on all app qubes with Qubes packages installed (which are all app qubes 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.

50
user/advanced-topics/salt.md
View File

@ -243,8 +243,8 @@ optional arguments:
--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)
--app Target all app qubes
--all Target all non-disposables (templates and app qubes)
```
To apply a state to all templates, call `qubesctl --templates state.highstate`.
@ -260,18 +260,18 @@ 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
1. Added the `management_dispvm` VM property, which specifies the disposable
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
configuration. App qubes inherit this property from their
parent templates. 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
2. Created the `default-mgmt-dvm` disposable 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
a black label (the same as templates). This VM is set as the global
`management_dispvm`. Keep in mind that this disposable template has full control
over the VMs it's used to manage.
## Writing Your Own Configurations
@ -420,7 +420,7 @@ The default settings can be overridden in the pillar data located in:
```
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`).
For example, `sudo qubesctl state.sls qvm.personal` will create a `personal` VM (if it does not already exist) with all its dependencies (template, `sys-firewall`, and `sys-net`).
### Available states
@ -451,31 +451,31 @@ Whonix gateway ProxyVM
#### `qvm.personal`
Personal AppVM
Personal app qube
#### `qvm.work`
Work AppVM
Work app qube
#### `qvm.untrusted`
Untrusted AppVM
Untrusted app qube
#### `qvm.vault`
Vault AppVM with no NetVM enabled.
Vault app qube with no NetVM enabled.
#### `qvm.default-dispvm`
Default DisposableVM template - fedora-26-dvm AppVM
Default disposable template - fedora-26-dvm app qube
#### `qvm.anon-whonix`
Whonix workstation AppVM.
Whonix workstation app qube.
#### `qvm.whonix-ws-dvm`
Whonix workstation AppVM for Whonix DisposableVMs.
Whonix workstation app qube for Whonix disposables.
#### `qvm.updates-via-whonix`
@ -483,27 +483,27 @@ Setup UpdatesProxy to route all templates updates through Tor (sys-whonix here).
#### `qvm.template-fedora-21`
Fedora-21 TemplateVM
Fedora-21 template
#### `qvm.template-fedora-21-minimal`
Fedora-21 minimal TemplateVM
Fedora-21 minimal template
#### `qvm.template-debian-7`
Debian 7 (wheezy) TemplateVM
Debian 7 (wheezy) template
#### `qvm.template-debian-8`
Debian 8 (jessie) TemplateVM
Debian 8 (jessie) template
#### `qvm.template-whonix-gw`
Whonix Gateway TemplateVM
Whonix Gateway template
#### `qvm.template-whonix-ws`
Whonix Workstation TemplateVM
Whonix Workstation template
#### `update.qubes-dom0`
@ -515,7 +515,7 @@ $ sudo qubesctl --show-output state.sls update.qubes-dom0
#### `update.qubes-vm`
Updates domUs. Example to update all TemplateVMs (executed in dom0):
Updates domUs. Example to update all templates (executed in dom0):
```
$ sudo qubesctl --show-output --skip-dom0 --templates state.sls update.qubes-vm
@ -543,9 +543,9 @@ Additional pillar data is available to ease targeting configurations (for exampl
VM type. Possible values:
- `admin` - Administration domain (`dom0`)
- `template` - Template VM
- `template` - template
- `standalone` - Standalone VM
- `app` - Template based AppVM
- `app` - Template based app qube
### `qubes:template`

4
user/advanced-topics/secondary-storage.md
View File

@ -12,12 +12,12 @@ 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.
You want to store a subset of your app qubes 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.
For example, you can keep templates on one disk and app qubes 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.

63
user/advanced-topics/standalone-and-hvm.md → user/advanced-topics/standalones-and-hvm.md
View File

@ -1,45 +1,44 @@
---
lang: en
layout: doc
permalink: /doc/standalone-and-hvm/
permalink: /doc/standalones-and-hvm/
redirect_from:
- /doc/standalone-and-hvm/
- /doc/hvm/
- /doc/hvm-create/
- /en/doc/hvm-create/
- /doc/HvmCreate/
- /wiki/HvmCreate/
ref: 130
title: StandaloneVMs and HVMs
title: Standalones and HVMs
---
A [standalone](/doc/glossary/#standalone) is a type of qube that is created by cloning a [template](/doc/templates/).
Unlike templates, however, standalones do not supply their root filesystems to other qubes.
Examples of situations in which standalones can be useful include:
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.
- Qubes used for development (dev environments often require a lot of specific packages and tools)
- Qubes 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.
However, when you would like to install some packages from less trusted sources, or unsigned, then using a dedicated (untrusted) standalone 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.
These are typically contrasted with Paravirtualized (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.
By default, every Qubes VM runs in PVH 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 standalone/template 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."
In practice, however, it is most common for standalones to be HVMs and for HVMs to be standalones.
Hence, this page covers both topics.
## Creating a StandaloneVM
## Creating a standalone
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)."
You can create a standalone 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:
@ -47,7 +46,7 @@ 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.
(Note: Technically, `virt_mode=hvm` is not necessary for every standalone.
However, it makes sense if you want to use a kernel from within the VM.)
## Creating an HVM
@ -62,7 +61,7 @@ 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:
Qubes are template-based by default so you must set the `--class StandaloneVM` option to create a standalone:
(name and label color are for illustration purposes).
~~~
@ -109,8 +108,8 @@ 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).
Just like standard paravirtualized app qubes, the HVM qubes get fixed IP addresses centrally assigned by Qubes.
Normally Qubes agent scripts (or services on Windows) running within each app qube 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.
@ -130,7 +129,7 @@ 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)).
Qubes allows HVMs to share a common root filesystem from a select template.
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:
@ -139,17 +138,17 @@ 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/).
Set memory as appropriate, and install the OS into this template in the same way you would install it into a normal HVM.
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.
If you use this Template as it is, then any HVMs that use it will effectively be disposables - 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.
Please see [this page](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-tools.md) 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.
Just like normal app qubes, 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:
@ -207,7 +206,7 @@ drive : None
timezone : localtime
~~~
Note how the MAC addresses differ between those two otherwise identical VMs.
Note how the MAC addresses differ between those two otherwise identical qubes.
The IP addresses assigned by Qubes will also be different of course to allow networking to function properly:
~~~
@ -218,7 +217,7 @@ The IP addresses assigned by Qubes will also be different of course to allow net
/.../
~~~
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:
If for any reason you would like to make sure that the two qubes have the same MAC address, you can use `qvm-prefs` to set a fixed MAC address for the qube:
~~~
[joanna@dom0 ~]$ qvm-prefs my-new-vm-copy -s mac 00:16:3E:5E:6C:05
@ -249,10 +248,10 @@ timezone : localtime
## Assigning PCI devices to HVMs
HVM domains (including Windows VMs) can be [assigned PCI devices](/doc/assigning-devices/) just like normal AppVMs.
HVM domains (including Windows qubes) can be [assigned PCI devices](/doc/how-to-use-pci-devices/) just like normal app qubes.
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.
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 qube.
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:
@ -268,7 +267,7 @@ 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`:
In Debian app qube, install `qemu-utils` and `unzip`:
~~~
sudo apt install qemu-utils unzip
@ -334,5 +333,5 @@ qemu-img -h | tail -n1
Other documents related to HVM:
- [Windows VMs](/doc/windows-vm/)
- [LinuxHVMTips](/doc/linux-hvm-tips/)
- [Windows VMs](https://github.com/Qubes-Community/Contents/blob/master/docs/os/windows/windows-vm.md)
- [Linux HVM Tips](https://github.com/Qubes-Community/Contents/blob/master/docs/os/linux-hvm-tips.md)

2
user/advanced-topics/volume-backup-revert.md
View File

@ -19,7 +19,7 @@ shutdown. (Note that this is a different, lower level activity than the
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/).)
example, see [Storing app qubes 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.

2
user/downloading-installing-upgrading/install-security.md
View File

@ -71,7 +71,7 @@ Cons:
(This mainly applies if you're upgrading from a previous version of Qubes.)
Currently, the only options for recording optical discs (e.g., CDs, DVDs, BRDs) in Qubes are:
1. Use a USB optical drive.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to an AppVM.
2. Attach a SATA optical drive to a secondary SATA controller, then assign this secondary SATA controller to an app qube.
3. Use a SATA optical drive attached to dom0.
(Option 3 violates the Qubes security model since it entails transferring an untrusted ISO to dom0 in order to burn it to disc, which leaves only the other two options.)

6
user/downloading-installing-upgrading/installation-guide.md
View File

@ -216,7 +216,7 @@ Two options are available:
Whonix lets you route some or all of your network traffic through Tor for greater privacy.
Depending on your threat model, you may need to install Whonix templates right away.
Regardless of your choices on this screen, you will always be able to install these and other [TemplateVMs](/doc/templates/) later.
Regardless of your choices on this screen, you will always be able to install these and other [templates](/doc/templates/) later.
If you're short on disk space, you may wish to deselect these options.
By default, Qubes OS comes preinstalled with the lightweight Xfce4 desktop environment.
@ -325,7 +325,7 @@ Let's briefly go over the options:
* **Create Whonix Gateway and Workstation qubes:**
If you want to use Whonix, you should select this option.
* **Enabling system and template updates over the Tor anonymity network using Whonix:**
If you select this option, then whenever you install or update software in dom0 or a TemplateVM, the internet traffic will go through Tor.
If you select this option, then whenever you install or update software in dom0 or a template, the internet traffic will go through Tor.
* **Create USB qube holding all USB controllers:**
Just like the network qube for the network stack, the USB qube isolates the USB controllers.
* **Use sys-net qube for both networking and USB devices:**
@ -360,7 +360,7 @@ It is important to make sure that you receive all QSBs in a timely manner so tha
(While [updating](#updating) will handle most security needs, there may be cases in which additional action from you is required.)
For this reason, we strongly recommend that every Qubes user subscribe to the [qubes-announce](/support/#qubes-announce) mailing list.
In addition to QSBs, the Qubes OS Project also publishes [Canaries](/security/canaries/), XSA summaries, TemplateVM releases and end-of-life notices, and other items of interest to Qubes users.
In addition to QSBs, the Qubes OS Project also publishes [Canaries](/security/canaries/), XSA summaries, template releases and end-of-life notices, and other items of interest to Qubes users.
Since these are not essential for all Qubes users to read, they are not sent to [qubes-announce](/support/#qubes-announce) in order to keep the volume on that list low.
However, we expect that most users, especially novice users, will find them helpful.
If you are interested in these additional items, we encourage you to subscribe to the [Qubes News RSS feed](/feed.xml) or join one of our other [venues](/support/), where these news items are also announced.

24
user/downloading-installing-upgrading/supported-versions.md
View File

@ -53,12 +53,12 @@ Dom0 is isolated from domUs. DomUs can access only a few interfaces, such as Xen
These components are [security-critical](/doc/security-critical-code/), and we provide updates for all of them (when necessary), regardless of the support status of the base distribution.
For this reason, we consider it safe to continue using a given base distribution in dom0 even after it has reached end-of-life (EOL).
## TemplateVMs
## Templates
The following table shows select [TemplateVM](/doc/templates/) versions that are currently supported.
Currently, only [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/) TemplateVMs are officially supported by the Qubes OS Project.
[Whonix](/doc/whonix/) TemplateVMs are supported by our partner, the [Whonix Project](https://www.whonix.org/).
Qubes support for each TemplateVM ends when that upstream release reaches end-of-life (EOL).
The following table shows select [template](/doc/templates/) versions that are currently supported.
Currently, only [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/) templates are officially supported by the Qubes OS Project.
[Whonix](/doc/whonix/) templates are supported by our partner, the [Whonix Project](https://www.whonix.org/).
Qubes support for each template ends when that upstream release reaches end-of-life (EOL).
Please see below for distribution-specific notes.
It is the responsibility of each distribution to clearly notify its users in advance of its own EOL dates, and it is users' responsibility to heed these notices by upgrading to supported releases.
@ -83,17 +83,17 @@ Qubes support ends at the *regular* EOL date, *not* the LTS EOL date, unless a s
### Note on Whonix support
[Whonix](/doc/whonix/) TemplateVMs are supported by our partner, the [Whonix Project](https://www.whonix.org/).
The Whonix Project has set its own support policy for Whonix TemplateVMs in Qubes.
[Whonix](/doc/whonix/) templates are supported by our partner, the [Whonix Project](https://www.whonix.org/).
The Whonix Project has set its own support policy for Whonix templates in Qubes.
This policy requires Whonix TemplateVM users to stay reasonably close to the cutting edge by upgrading to new stable versions of Qubes OS and Whonix TemplateVMs within a month of their respective releases.
This policy requires Whonix template users to stay reasonably close to the cutting edge by upgrading to new stable versions of Qubes OS and Whonix templates within a month of their respective releases.
To be precise:
* One month after a new stable version of Qubes OS is released, Whonix TemplateVMs will no longer be supported on any older version of Qubes OS.
This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Qubes OS version within one month of its release.
* One month after a new stable version of Qubes OS is released, Whonix templates will no longer be supported on any older version of Qubes OS.
This means that users who wish to continue using Whonix templates on Qubes must always upgrade to the latest stable Qubes OS version within one month of its release.
* One month after new stable versions of Whonix TemplateVMs are released, older versions of Whonix TemplateVMs will no longer be supported.
This means that users who wish to continue using Whonix TemplateVMs on Qubes must always upgrade to the latest stable Whonix TemplateVM versions within one month of their release.
* One month after new stable versions of Whonix templates are released, older versions of Whonix templates will no longer be supported.
This means that users who wish to continue using Whonix templates on Qubes must always upgrade to the latest stable Whonix template versions within one month of their release.
We aim to announce both types of events one month in advance in order to remind users to upgrade.

2
user/downloading-installing-upgrading/testing.md
View File

@ -36,7 +36,7 @@ Updates
How to test updates:
* Enable [dom0 testing repositories](/doc/how-to-install-software-in-dom0/#testing-repositories).
* Enable [TemplateVM testing repositories](/doc/how-to-install-software/#testing-repositories).
* Enable [template testing repositories](/doc/how-to-install-software/#testing-repositories).
Every new update is first uploaded to the `security-testing` repository if it is a security update or `current-testing` if it is a normal update.
The update remains in `security-testing` or `current-testing` for a minimum of one week.

4
user/downloading-installing-upgrading/upgrade/upgrade-to-r2.md
View File

@ -23,9 +23,9 @@ Upgrade Template and Standalone VM(s)
- **It also possible to download a new Fedora 20-based template from our repositories**. To do this please first upgrade the Dom0 distro as described in the section below.
While technically it is possible to use old Fedora 18 template on R2, it is strongly recommended to upgrade all the Template VMs and Standalone VMs, because Fedora 18 no longer receive security updates.
While technically it is possible to use old Fedora 18 template on R2, it is strongly recommended to upgrade all the templates and Standalone VMs, because Fedora 18 no longer receive security updates.
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. If more than one template and/or Standalone VMs are used, then it is recommended to upgrade/replace all of them. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/).
By default, in Qubes R2, there is only one template, however users are free to create more templates for special purposes, as well as Standalone VMs. If more than one template and/or Standalone VMs are used, then it is recommended to upgrade/replace all of them. More information on using multiple templates, as well as Standalone VMs, can be found [here](/doc/software-update-vm/).
Upgrading dom0
--------------

6
user/downloading-installing-upgrading/upgrade/upgrade-to-r2b1.md
View File

@ -20,9 +20,9 @@ Existing users of Qubes R1 (but not R1 betas!) can upgrade their systems to the
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R1, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/templates/) and [here](/doc/standalone-and-hvm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
By default, in Qubes R1, there is only one template, however users are free to create more templates for special purposes, as well as Standalone VMs. More information on using multiple templates, as well as Standalone VMs, can be found [here](/doc/templates/) and [here](/doc/standalone-and-hvm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
1. Open terminal in the template (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
~~~
@ -46,7 +46,7 @@ By default, in Qubes R1, there is only one Template VM, however users are free t
Is this ok [y/N]:
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your template's filesystem:
- via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
- via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).

6
user/downloading-installing-upgrading/upgrade/upgrade-to-r2b2.md
View File

@ -18,9 +18,9 @@ Upgrade all Template and Standalone VM(s)
**If you have already R2 Beta1 installed, follow standard template update procedure (e.g. "Update VM" button in Qubes Manager) and skip the rest of this section**
By default, in Qubes R1, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/templates/) and [here](/doc/standalone-and-hvm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
By default, in Qubes R1, there is only one template, however users are free to create more templates for special purposes, as well as Standalone VMs. More information on using multiple templates, as well as Standalone VMs, can be found [here](/doc/templates/) and [here](/doc/standalone-and-hvm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
1. Open terminal in the template (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package (this package brings in R2 repo definitions and R2 keys)
~~~
@ -44,7 +44,7 @@ By default, in Qubes R1, there is only one Template VM, however users are free t
Is this ok [y/N]:
~~~
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your Template VM's filesystem:
If you see (as is the case on the "screenshot" above) that the new key was imported from a local filesystem (`/etc/pki/rpm-gpg/...`) you can safely accept the key, without checking its fingerprint. This is because there were only two ways for such a key to make it to your template's filesystem:
- via a legitimate RPM package previously installed (in our case it was the `qubes-upgrade-vm` RPM). Such an RPM must have been signed by one of the keys you decided to trust previously, by default this would be either via the Qubes R1 signing key, or Fedora 17 signing key.
- via system compromise or via some illegal RPM package (e.g. Fedora released package pretending to bring new Firefox). In that case, however, your VM is already compromised, and it careful checking of the new R2 key would not change this situation to any better one. The game is lost for this VM anyway (and all VMs based on this template).

4
user/downloading-installing-upgrading/upgrade/upgrade-to-r2b3.md
View File

@ -20,11 +20,11 @@ Experienced users may be comfortable accepting the risks of upgrading in-place.
Upgrade all Template and Standalone VM(s)
-----------------------------------------
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
By default, in Qubes R2, there is only one template, however users are free to create more templates for special purposes, as well as Standalone VMs. More information on using multiple templates, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in *all* user's Template and Standalone VMs.
It is critical to complete this step **before** proceeding to dom0 upgrade. Otherwise you will most likely ends with unusable system.
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
1. Open terminal in the template (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Proceed with normal update in the template:
~~~

12
user/downloading-installing-upgrading/upgrade/upgrade-to-r3_0.md
View File

@ -21,13 +21,13 @@ Experienced users may be comfortable accepting the risks of upgrading in-place.
## Upgrade all Template and Standalone VM(s)
By default, in Qubes R2, there is only one Template VM, however users are free to create more Template VMs for special purposes, as well as Standalone VMs. More information on using multiple Template VMs, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in **all** user's Template and Standalone VMs.
By default, in Qubes R2, there is only one template, however users are free to create more templates for special purposes, as well as Standalone VMs. More information on using multiple templates, as well as Standalone VMs, can be found [here](/doc/software-update-vm/). The steps described in this section should be repeated in **all** user's Template and Standalone VMs.
It is critical to complete this step **before** proceeding to dom0 upgrade. Otherwise you will most likely end with unusable system.
### Upgrade Fedora template:
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
1. Open terminal in the template (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Install `qubes-upgrade-vm` package:
```
@ -42,11 +42,11 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
You'll need to accept "Qubes Release 3 Signing Key" - it is delivered by signed qubes-upgrade-vm package (verify that the message is about local file), so you don't need to manually verify it.
4. Shutdown the template VM.
4. Shutdown the template.
### Upgrade Debian template:
1. Open terminal in the template VM (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
1. Open terminal in the template (or standalone VM). E.g. use the Qubes Manager's right-click menu and choose Run Command in VM and type `gnome-terminal` there.
2. Update repository definition:
```
@ -68,7 +68,7 @@ It is critical to complete this step **before** proceeding to dom0 upgrade. Othe
(after 3min timeout), but you can ignore this problem for now. After
completing the whole upgrade the service will be properly restarted.
4. Shutdown the template VM.
4. Shutdown the template.
## Upgrading dom0
@ -137,7 +137,7 @@ Because of above limitations, you will need to configure some of those manually.
```shell_session
[user@dom0 ~]$ qvm-start custom-template
--> Loading the VM (type = TemplateVM)...
--> Loading the VM (type = template)...
--> Starting Qubes DB...
--> Setting Qubes DB info for the VM...
--> Updating firewall rules...

14
user/downloading-installing-upgrading/upgrade/upgrade-to-r3_1.md
View File

@ -19,15 +19,15 @@ by following the procedure below.
## Upgrade all Template and Standalone VM(s)
By default, in Qubes R3.0, there is only one TemplateVM. However, users are
free to create more TemplateVMs for special purposes, as well as StandaloneVMs.
More information on using multiple TemplateVMs, as well as StandaloneVMs, can be
By default, in Qubes R3.0, there is only one template. However, users are
free to create more templates for special purposes, as well as standalones.
More information on using multiple templates, as well as standalones, can be
found [here](/doc/software-update-vm/). The steps described in this
section should be repeated in **all** the user's Template and Standalone VMs.
### Upgrade Fedora templates:
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
1. Open a terminal in the template (or standalone). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
@ -43,11 +43,11 @@ section should be repeated in **all** the user's Template and Standalone VMs.
sudo yum upgrade
```
4. Shut down the template VM.
4. Shut down the template.
### Upgrade Debian (and Whonix) templates:
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
1. Open a terminal in the template (or standalone). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
@ -71,7 +71,7 @@ section should be repeated in **all** the user's Template and Standalone VMs.
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
```
5. Shut down the template VM.
5. Shut down the template.
## Upgrading dom0

14
user/downloading-installing-upgrading/upgrade/upgrade-to-r3_2.md
View File

@ -114,9 +114,9 @@ your favorite desktop environment and continue.
## Upgrade all Template and Standalone VM(s)
By default, in Qubes R3.1, there are few TemplateVMs and no StandaloneVMs.
However, users are free to create StandaloneVMs More information on using
multiple TemplateVMs, as well as StandaloneVMs, can be found
By default, in Qubes R3.1, there are few templates and no standalones.
However, users are free to create standalones More information on using
multiple templates, as well as standalones, can be found
[here](/doc/software-update-vm/). The steps described in this section should be
repeated in **all** the user's Template and Standalone VMs.
@ -127,7 +127,7 @@ repeated in **all** the user's Template and Standalone VMs.
In order to do that, please see the
[Fedora 23 template upgrade instructions](/doc/templates/fedora/#upgrading).
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
1. Open a terminal in the template (or standalone). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
@ -149,11 +149,11 @@ In order to do that, please see the
sudo dnf install qubes-mgmt-salt-vm-connector
```
5. Shut down the template VM.
5. Shut down the template.
### Upgrade Debian (and Whonix) templates:
1. Open a terminal in the TemplateVM (or StandaloneVM). (E.g., use Qubes VM
1. Open a terminal in the template (or standalone). (E.g., use Qubes VM
Manager's right-click menu, choose "Run Command in VM," and type
`gnome-terminal` there.)
@ -183,4 +183,4 @@ In order to do that, please see the
sudo rm -f /etc/apt/sources.list.d/qubes-r3-upgrade.list
```
6. Shut down the template VM.
6. Shut down the template.

36
user/downloading-installing-upgrading/upgrade/upgrade-to-r4_0.md
View File

@ -82,38 +82,38 @@ Restore from your backup
4. Go to **Qubes menu -> System Tools -> Qubes Manager** to start it.
5. Follow the **Restoring from a Backup** section in the [Backup, Restoration, and Migration](/doc/backup-restore/) guide.
We recommend that you restore only your [TemplateBasedVMs](/doc/glossary/#templatebasedvm) and [StandaloneVMs](/doc/glossary/#standalonevm) from R3.2.
Using [TemplateVMs](/doc/templates/) and [SystemVMs](/doc/glossary/#systemvm) from R3.2 is not fully supported (see [#3514](https://github.com/QubesOS/qubes-issues/issues/3514)).
Instead, we recommend using the TemplateVMs that were created specifically for R4.0, which you can [customize](/doc/software-update-vm/) according to your needs.
For the TemplateVM OS versions supported in R4.0, see [Supported Versions](/doc/supported-versions/#templatevms).
If the restore tool complains about missing templates, you can select the option to restore the AppVMs anyway, then change them afterward to use one of the default R4.0 templates.
We recommend that you restore only your [app qubes](/doc/glossary/#app-qube) and [standalones](/doc/glossary/#standalone) from R3.2.
Using [templates](/doc/templates/) and [service qubes](/doc/glossary/#service-qube) from R3.2 is not fully supported (see [#3514](https://github.com/QubesOS/qubes-issues/issues/3514)).
Instead, we recommend using the templates that were created specifically for R4.0, which you can [customize](/doc/software-update-vm/) according to your needs.
For the template OS versions supported in R4.0, see [Supported Versions](/doc/supported-versions/#templates).
If the restore tool complains about missing templates, you can select the option to restore the app qubes anyway, then change them afterward to use one of the default R4.0 templates.
Note about additional disp-* qubes created during restore
---------------------------------------------------------
One of differences between R3.2 and R4.0 is the handling of DisposableVMs.
In R3.2, a DisposableVM inherited its network settings (NetVM and firewall rules) from the calling qube.
One of differences between R3.2 and R4.0 is the handling of disposables.
In R3.2, a disposable inherited its network settings (NetVM and firewall rules) from the calling qube.
In R4.0, this is no longer the case.
Instead, in R4.0 it's possible to create multiple DisposableVM Templates and choose which one should be used by each qube.
It's even possible to use different DisposableVM Templates for different operations from the same qube.
Instead, in R4.0 it's possible to create multiple disposable templates and choose which one should be used by each qube.
It's even possible to use different disposable templates for different operations from the same qube.
This allows much more flexibility, since it allows you to differentiate not only network settings, but all of a qube's properties (including its template, memory settings, etc.).
Restoring a backup from R3.2 preserves the old behavior by creating separate DisposableVM Template for each network-providing qube (and also `disp-no-netvm` for network-isolated qubes).
Then, each restored qube is configured to use the appropriate DisposableVM Template according to its `netvm` or `dispvm_netvm` property from R3.2.
This way, DisposableVMs started on R4.0 by qubes restored from a R3.2 backup have the same NetVM settings as they had on R3.2.
Restoring a backup from R3.2 preserves the old behavior by creating separate disposable template for each network-providing qube (and also `disp-no-netvm` for network-isolated qubes).
Then, each restored qube is configured to use the appropriate disposable template according to its `netvm` or `dispvm_netvm` property from R3.2.
This way, disposables started on R4.0 by qubes restored from a R3.2 backup have the same NetVM settings as they had on R3.2.
If you find this behavior undesirable and want to configure it differently, you can remove those `disp-*` DisposableVM Templates.
If you find this behavior undesirable and want to configure it differently, you can remove those `disp-*` disposable templates.
But, to do so, you must first make sure they are not set as the value for the `default_dispvm` property on any other qube.
Both Qubes Manager and the `qvm-remove` tool will show you where a DisposableVM Template is being used, so you can go there and change the setting.
Both Qubes Manager and the `qvm-remove` tool will show you where a disposable template is being used, so you can go there and change the setting.
Upgrade all Template and Standalone VM(s)
-----------------------------------------
We strongly recommend that you update **all** TemplateVMs and StandaloneVMs before use so that you have the latest security patches from upstream distributions.
We strongly recommend that you update **all** templates and standalones before use so that you have the latest security patches from upstream distributions.
In addition, if the default templates have reached EOL (end-of-life) by the time you install R4.0, we strongly recommend that you upgrade them before use.
Please see [Supported Versions](/doc/supported-versions/) for information on supported OS versions and consult the guides below for specific upgrade instructions:
* [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading)
* [Upgrading Debian TemplateVMs](/doc/templates/debian/#upgrading)
* [Updating Whonix TemplateVMs](https://www.whonix.org/wiki/Qubes/Update)
* [Upgrading Fedora templates](/doc/templates/fedora/#upgrading)
* [Upgrading Debian templates](/doc/templates/debian/#upgrading)
* [Updating Whonix templates](https://www.whonix.org/wiki/Qubes/Update)

2
user/hardware/certified-hardware.md
View File

@ -82,7 +82,7 @@ Among other things, this implies **proper DMAR ACPI table** construction.
Finally, we require that Qubes-certified hardware does not have any built-in _USB-connected_ microphones (e.g. as part of a USB-connected built-in camera) that cannot be easily physically disabled by the user, e.g. via a convenient mechanical switch.
Thankfully, the majority of laptops on the market that we have seen already satisfy this condition out-of-the-box, because their built-in microphones are typically connected to the internal audio device, which itself is a type of PCIe device.
This is important, because such PCIe audio devices are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through our carefully designed protocol only to select AppVMs when the user explicitly chooses to do so.
This is important, because such PCIe audio devices are --- by default --- assigned to Qubes' (trusted) dom0 and exposed through our carefully designed protocol only to select app qubes when the user explicitly chooses to do so.
The rest of the time, they should be outside the reach of malware.
While we also recommend a physical kill switch on the built-in camera (or, if possible, not to have a built-in camera), we also recognize this isn't a critical requirement, because users who are concerned about it can easily cover it a piece of tape (something that, regrettably, is far less effective on a microphone).

6
user/how-to-guides/how-to-back-up-restore-and-migrate.md
View File

@ -56,7 +56,7 @@ Creating a backup
3. Select the destination for the backup:
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target AppVM**.
If you wish to send your backup to a (currently running) VM, select the VM in the drop-down box next to **Target app qube**.
If you wish to send your backup to a [USB mass storage device](/doc/usb/), you can use the directory selection widget to mount a connected device (under "Other locations" item on the left); or first mount the device in a VM, then select the mount point inside that VM as the backup destination.
You must also specify a directory on the device or in the VM, or a command to be executed in the VM as a destination for your backup.
@ -95,7 +95,7 @@ This brings up the **Qubes Restore VMs** window.
2. Select the source location of the backup to be restored:
- If your backup is located on a [USB mass storage device](/doc/usb/), attach it first to another VM or select `sys-usb` in the next item.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **AppVM**.
- If your backup is located in a (currently running) VM, select the VM in the drop-down box next to **app qube**.
You must also specify the directory and filename of the backup (or a command to be executed in a VM) in the **Backup file** field.
If you followed the instructions in the previous section, "Creating a Backup," then your backup is most likely in the location you chose as the destination in step 3.
@ -103,7 +103,7 @@ This brings up the **Qubes Restore VMs** window.
Once you've located the backup file, double-click it or select it and hit **OK**.
3. There are three options you may select when restoring from a backup:
1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or TemplateVM that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
1. **ignore missing templates and net VMs**: If any of the VMs in your backup depended upon a NetVM or template that is not present in (i.e., "missing from") the current system, checking this box will ignore the fact that they are missing and restore the VMs anyway and set them to use the default NetVM and system default template.
2. **ignore username mismatch**: This option applies only to the restoration of dom0's home directory.
If your backup was created on a Qubes system which had a different dom0 username than the dom0 username of the current system, then checking this box will ignore the mismatch between the two usernames and proceed to restore the home directory anyway.
3. **Verify backup integrity, do not restore the data**: This will scan the backup file for corrupted data.

2
user/how-to-guides/how-to-copy-and-move-files.md
View File

@ -21,7 +21,7 @@ Qubes OS supports the secure copying and moving of files and directories (folder
For simplicity, these instructions will refer to copying/moving a single file, but they apply equally well to groups of files and directories, which are copied recursively.
1. Open a file manager in the qube containing the file you wish to copy (the source qube), right-click on the file you wish to copy or move, and select `Copy to Other AppVM...` or `Move to Other AppVM...`.
1. Open a file manager in the qube containing the file you wish to copy (the source qube), right-click on the file you wish to copy or move, and select `Copy to Other app qube...` or `Move to Other app qube...`.
2. A dialog box will appear in dom0 asking for the name of the target qube (qube B).
Enter or select the desired destination qube name.

2
user/how-to-guides/how-to-copy-and-paste-text.md
View File

@ -67,7 +67,7 @@ The Qubes clipboard [RPC policy](/doc/rpc-policy/) is configurable in:
~~~
You may wish to configure this policy in order to prevent user error.
For example, if you are certain that you never wish to paste *into* your "vault" AppVM (and it is highly recommended that you do not), then you should edit the policy as follows:
For example, if you are certain that you never wish to paste *into* your "vault" app qube (and it is highly recommended that you do not), then you should edit the policy as follows:
~~~
@anyvm vault deny

2
user/how-to-guides/how-to-copy-from-dom0.md
View File

@ -69,7 +69,7 @@ For this reason, there is no simple means of copying anything into dom0, unlike
There should normally be few reasons for the user to want to copy anything from domUs to dom0, as dom0 only acts as a "thin trusted terminal", and no user applications run there.
Sometimes, new users feel the urge to copy a desktop wallpaper image into dom0, but that is not necessary.
A safer approach is simply to display the image in [full-screen mode](/doc/full-screen-mode/) in an AppVM, then take a screenshot from dom0, which results in exactly the image needed for a wallpaper, created securely and natively in dom0.
A safer approach is simply to display the image in [full-screen mode](/doc/full-screen-mode/) in an app qube, then take a screenshot from dom0, which results in exactly the image needed for a wallpaper, created securely and natively in dom0.
If you are determined to copy some files to dom0 anyway, you can use the following method.
(If you want to copy text, first save it into a text file.)

40
user/how-to-guides/how-to-install-software.md
View File

@ -81,13 +81,13 @@ Debian also has three Qubes VM testing repositories (where `*` denotes the Relea
To enable or disable any of these repos permanently, uncomment the corresponding `deb` line in `/etc/apt/sources.list.d/qubes-r*.list`.
### StandaloneVMs
### Standalones
When you create a [StandaloneVM](/doc/standalone-and-hvm/) from a template, the StandaloneVM is a complete clone of the template, including the entire filesystem.
After the moment of creation, the StandaloneVM is completely independent from the template.
When you create a [standalone](/doc/standalone-and-hvm/) from a template, the standalone is a complete clone of the template, including the entire filesystem.
After the moment of creation, the standalone is completely independent from the template.
Therefore, it will not be updated when the template is updated.
Rather, it must be updated individually.
The process for installing and updating software in StandaloneVMs is the same as described above for templates.
The process for installing and updating software in standalones is the same as described above for templates.
### RPMFusion for Fedora templates
@ -156,15 +156,15 @@ This is like the simple revert, except:
### Temporarily allowing networking for software installation
Some third-party applications cannot be installed using the standard repositories and need to be manually downloaded and installed.
When the installation requires internet connection to access third-party repositories, it will naturally fail when run in a Template VM because the default firewall rules for templates only allow connections from package managers.
When the installation requires internet connection to access third-party repositories, it will naturally fail when run in a template because the default firewall rules for templates only allow connections from package managers.
So it is necessary to modify firewall rules to allow less restrictive internet access for the time of the installation, if one really wants to install those applications into a template.
As soon as software installation is completed, firewall rules should be returned back to the default state.
The user should decide by themselves whether such third-party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default Template VM, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
The user should decide by themselves whether such third-party applications should be equally trusted as the ones that come from the standard Fedora signed repositories and whether their installation will not compromise the default template, and potentially consider installing them into a separate template or a standalone VM (in which case the problem of limited networking access doesn't apply by default), as described above.
### Updates proxy
Updates proxy is a service which allows access only from package managers.
This is meant to mitigate user errors (like using browser in the template VM), rather than some real isolation.
This is meant to mitigate user errors (like using browser in the template), rather than some real isolation.
It is done with http proxy (tinyproxy) instead of simple firewall rules because it is hard to list all the repository mirrors (and keep that list up to date).
The proxy is used only to filter the traffic, not to cache anything.
@ -196,13 +196,13 @@ Example policy file in R4.0 (with Whonix installed, but not set as default Updat
@tag:whonix-updatevm @anyvm deny
# other templates use sys-net
@type:TemplateVM @default allow,target=sys-net
@type:template @default allow,target=sys-net
@anyvm @anyvm deny
```
### Installing Snap Packages
Snap packages do not use the normal update channels for Debian and Fedora (apt and dnf) and are often installed as the user rather than as root. To support these in an AppVM you need to take the following steps:
Snap packages do not use the normal update channels for Debian and Fedora (apt and dnf) and are often installed as the user rather than as root. To support these in an app qube you need to take the following steps:
1. In the **template** you must install `snapd` and `qubes-snapd-helper`. Open a terminal in the template and run:
@ -256,29 +256,29 @@ Shutdown the template:
[user@fedora-30-snap-demo ~]$ sudo shutdown -h now
```
2. Now open the **AppVM** in which you would like to install the Snap application and run a terminal:
2. Now open the **app qube** in which you would like to install the Snap application and run a terminal:
```shell_session
[user@snap-demo-AppVM ~]$ snap install <package>
[user@snap-demo-app qube ~]$ snap install <package>
```
When the install is complete you can close the terminal window.
3. Refresh the Applications list for the AppVM.
In the Qubes Menu for the **AppVM*** launch the Qube Settings.
3. Refresh the Applications list for the app qube.
In the Qubes Menu for the **app qube*** launch the Qube Settings.
Then go to the Applications tab and click "Refresh Applications"
The refresh will take a few minutes; after it's complete the Snap app will appear in the AppVM's list of available applications. At this point the snap will be persistent within the AppVM and will receive updates when the AppVM is running.
The refresh will take a few minutes; after it's complete the Snap app will appear in the app qube's list of available applications. At this point the snap will be persistent within the app qube and will receive updates when the app qube is running.
### Autostarting Installed Applications
If you want a desktop app to start automatically every time a qube starts you can create a link to it in the `~/.config/autostart` directory of the **AppVM**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app.
If you want a desktop app to start automatically every time a qube starts you can create a link to it in the `~/.config/autostart` directory of the **app qube**. This might be useful for Qubes that you set to automatically start on boot or for Qubes that have a set of apps you typically use all day, such as a chat app.
1. Open a terminal in the **AppVM** where you would like the app to launch.
1. Open a terminal in the **app qube** where you would like the app to launch.
2. List the names of the available desktop shortcuts by running the command `ls /usr/share/applications` and find the exact name of the shortcut to the app you want to autostart:
```shell_session
[user@example-AppVM ~]$ ls /usr/share/applications/
[user@example-app qube ~]$ ls /usr/share/applications/
bluetooth-sendto.desktop
eog.desktop
firefox.desktop
@ -290,14 +290,14 @@ yelp.desktop
3. Create the autostart directory:
```
[user@example-AppVM ~]$ mkdir -p ~/.config/autostart
[user@example-app qube ~]$ mkdir -p ~/.config/autostart
```
4. Make a link to the desktop app file you'd like to start in the autostart directory. For example, the command below will link the Thunderbird app into the autostart directory:
```
[user@example-AppVM ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop
[user@example-app qube ~]$ ln -s /usr/share/applications/mozilla-thunderbird.desktop ~/.config/autostart/mozilla-thunderbird.desktop
```
Note that the app will autostart only when the AppVM starts. If you would like the AppVM to autostart, select the "Start qube automatically on boot" checkbox in the AppVM's Qube Settings.
Note that the app will autostart only when the app qube starts. If you would like the app qube to autostart, select the "Start qube automatically on boot" checkbox in the app qube's Qube Settings.

12
user/how-to-guides/how-to-update.md
View File

@ -33,8 +33,8 @@ It is important to keep your Qubes OS system up-to-date to ensure you have the l
Fully updating your Qubes OS system means updating:
- [Dom0](/doc/how-to-install-software-in-dom0/)
- [TemplateVMs](/doc/how-to-install-software/#updating-software-in-templatevms)
- [StandaloneVMs](/doc/how-to-install-software/#standalonevms) (if you have any)
- [templates](/doc/how-to-install-software/#instructions)
- [standalones](/doc/how-to-install-software/#standalones) (if you have any)
You can accomplish this using the **Qubes Update** tool.
@ -56,18 +56,18 @@ Even if no updates have been detected, you can use this tool to check for update
The above covers updating *within* a given operating system release.
Eventually, however, most operating system releases will reach [end-of-life (EOL)](https://fedoraproject.org/wiki/End_of_life), after which point they will no longer be supported.
This applies to [Qubes OS itself](/doc/supported-versions/#qubes-os) as well as operating systems used for TemplateVMs and StandaloneVMs, such as [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/).
This applies to [Qubes OS itself](/doc/supported-versions/#qubes-os) as well as operating systems used for templates and standalones, such as [Fedora](/doc/templates/fedora/) and [Debian](/doc/templates/debian/).
It is very important to use only supported releases, since generally only supported releases receive security updates.
This means that you must periodically upgrade to a newer release before your current release reaches EOL.
In the case of Qubes OS itself, we will always [announce](/news/categories/#releases) when a given Qubes OS release is approaching and has reached EOL, and we will provide [instructions for upgrading to the next stable supported Qubes OS release](/doc/upgrade/).
Again, you can always see the current support status for all Qubes OS releases [here](/doc/supported-versions/#qubes-os).
Periodic upgrades are also important for TemplateVMs and StandaloneVMs.
For example, you might be using a [Fedora TemplateVM](/doc/templates/fedora/).
Periodic upgrades are also important for templates and standalones.
For example, you might be using a [Fedora Template](/doc/templates/fedora/).
The [Fedora Project](https://getfedora.org/) is independent of the Qubes OS Project.
They set their own [schedule](https://fedoraproject.org/wiki/Fedora_Release_Life_Cycle#Maintenance_Schedule) for when each Fedora release reaches EOL.
You can always find out when an operating system reaches EOL from the upstream project that maintains it, but we also make EOL [announcements](/news/categories/#announcements) and publish guides for official TemplateVM operating systems as a convenience to Qubes users.
You can always find out when an operating system reaches EOL from the upstream project that maintains it, but we also make EOL [announcements](/news/categories/#announcements) and publish guides for official template operating systems as a convenience to Qubes users.
When this happens, you should make sure to follow the guide to upgrade to a supported version of that operating system (see the [Fedora upgrade guides](/doc/templates/fedora/#upgrading) and the [Debian upgrade guides](/doc/templates/debian/#upgrading)).
The one exception to all this is the specific release used for dom0 (not to be confused with Qubes OS as a whole), which [doesn't have to be upgraded](/doc/supported-versions/#note-on-dom0-and-eol).

4
user/how-to-guides/how-to-use-block-storage-devices.md
View File

@ -36,8 +36,8 @@ In our example, this is `sys-usb:sda`, so hover over it.
This will pop up a submenu showing running VMs to which the USB drive can be connected.
Click on one and your USB drive will be attached!
**Note:** attaching individual partitions (e.g. `sys-usb:sda1`) can be slightly more secure because it doesn't force the target AppVM to parse the partition table.
However, it often means the AppVM won't detect the new partition and you will need to manually mount it inside the AppVM.
**Note:** attaching individual partitions (e.g. `sys-usb:sda1`) can be slightly more secure because it doesn't force the target app qube to parse the partition table.
However, it often means the app qube won't detect the new partition and you will need to manually mount it inside the app qube.
See below for more detailed steps.
## Block Devices in VMs

190
user/how-to-guides/how-to-use-disposables.md Normal file
View File

@ -0,0 +1,190 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-disposables/
redirect_from:
- /doc/how-to-use-disposablevms/
- /doc/disposable/
- /doc/dispvm/
- /en/doc/dispvm/
- /doc/DisposableVms/
- /wiki/disposables/
ref: 203
title: How to Use Disposables
---
A **disposable** is a lightweight VM that can be created quickly and will disappear when closed.
disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
From inside an app qube, choosing the `Open in disposable` option on a file will launch a disposable for just that file.
Changes made to a file opened in a disposable are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
disposables can be launched either directly from dom0's Start Menu or terminal window, or from within app qubes.
While running, disposables will appear in Qubes VM Manager with the name `disp####`.
[![disposablevm-example.png](/attachment/wiki/DisposableVms/disposablevm-example.png)](/attachment/wiki/DisposableVms/disposablevm-example.png)
This diagram provides a general example of how disposables can be used to safely open untrusted links and attachments in disposables. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a disposable.
## Security
If a [disposable template](/doc/glossary/#disposable-template) becomes compromised, then any disposable based on that disposable template could be compromised.
In particular, the *default* disposable template is important because it is used by the "Open in disposable" 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 disposable template on a trusted template.
### Disposables and Local Forensics
At this time, disposables should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
## Disposables and Networking
Similarly to how app qubes are based on their underlying [template](/doc/glossary/#template), disposables are based on their underlying [disposable template](/doc/glossary/#disposable-template).
R4.0 introduces the concept of multiple disposable templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default disposable template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default template).
If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` disposable template available for your use.
You can set any app qube to have the ability to act as a disposable template with:
```
qvm-prefs <vmname> template_for_dispvms True
```
The default system wide disposable template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in disposable` from inside an app qube will open the document in a disposable based on the default disposable template you specified.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "Default disposable" setting to specify which disposable template will be used to launch disposables from that VM.
This can also be changed from the command line with:
```
qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
```
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an app qube that has also been configured as a disposable template to use itself, so disposables launched from within the app qube/disposable template would inherit the same settings.
NetVM and firewall rules for disposable templates can be set as they can for a normal VM.
By default a disposable will inherit the NetVM and firewall settings of the disposable template on which it is based.
This is a change in behaviour from R3.2, where disposables would inherit the settings of the app qube from which they were launched.
Therefore, launching a disposable from an app qube will result in it using the network/firewall settings of the disposable template on which it is based.
For example, if an app qube uses sys-net as its NetVM, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its NetVM.
**Warning:** The opposite is also true.
This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default disposable uses sys-net, launching a disposable from inside anon-whonix will result in the disposable using sys-net.
A disposable launched from the Start Menu inherits the NetVM and firewall settings of the disposable template on which it is based.
Note that changing the "NetVM" setting for the system default disposable template *does* affect the NetVM of disposables launched from the Start Menu.
Different disposable templates with individual NetVM settings can be added to the Start Menu.
**Important Notes:**
Some disposable templates will automatically create a menu item to launch a disposable, if you do not see an entry and want to add one please use the command:
```
qvm-features <DISPOSABLE> appmenus-dispvm 1
```
To launch a disposable template from the command line, in dom0 please type the following:
```
qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+NameOfApp
```
## Opening a file in a disposable via GUI
In an app qube's file manager, right click on the file you wish to open in a disposable, then choose "View in disposable" or "Edit in disposable".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a disposable created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole disposable will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original app qube, overwriting the original.
![r4.0-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-2.png)
## Opening a fresh web browser instance in a new disposable
Sometimes it is desirable to open an instance of Firefox within a new fresh disposable.
This can be done easily using the Start Menu: just go to **Application Menu -\> disposable -\> disposable:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole disposable will be destroyed.
![r4.0-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-3.png)
## Opening a file in a disposable via command line (from app qube)
Use the `qvm-open-in-dvm` command from a terminal in your app qube:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the disposable.
## Starting an arbitrary program in a disposable from an app qube
Sometimes it can be useful to start an arbitrary program in a disposable.
The disposable will stay running so long as the process which started the disposable has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
Starting an arbitrary program can be done from an app qube by running
~~~
[user@vault ~]$ qvm-run '@dispvm' xterm
~~~
The created disposable can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
## Starting an arbitrary application in a disposable via command line from dom0
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated disposables, since these are very common tasks.
The disposable will stay running so long as the process which started the disposable has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
It is possible to start an arbitrary application in a disposable directly from dom0 by running:
~~~
$ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+xterm
~~~
The label color will be inherited from `<DISPOSABLE_TEMPLATE>`.
(The disposable Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
### Opening a link in a disposable based on a non-default disposable template from a qube
Suppose that the default disposable template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
However, sometimes you want to open email links in disposables.
Obviously, you can't use the default disposable template, since it has no networking, so you need to be able to specify a different disposable template.
You can do that with this command from the `email` qube (as long as your RPC policies allow it):
~~~
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> https://www.qubes-os.org
~~~
This will create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>`, open the default web browser in that disposable, and navigate to `https://www.qubes-os.org`.
#### Example of RPC policies to allow this behavior
In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL`
~~~
@anyvm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> allow
~~~
This line means:
- FROM: Any VM
- TO: A disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>`
- WHAT: Allow sending an "Open URL" request
In other words, any VM will be allowed to create a new disposable based on `<ONLINE_DISPOSABLE_TEMPLATE>` and open a URL inside of that disposable.
More information about RPC policies for disposables can be found [here](/doc/qrexec/#qubes-rpc-administration).
## Customizing disposables
You can change the template used to generate the disposables, and change settings used in the disposable savefile.
These changes will be reflected in every new disposable based on that template.
Full instructions can be found [here](/doc/disposable-customization/).

190
user/how-to-guides/how-to-use-disposablevms.md
View File

@ -1,190 +0,0 @@
---
lang: en
layout: doc
permalink: /doc/how-to-use-disposablevms/
redirect_from:
- /doc/disposablevm/
- /doc/dispvm/
- /en/doc/dispvm/
- /doc/DisposableVms/
- /wiki/DisposableVMs/
ref: 203
title: How to Use DisposableVMs
---
A DisposableVM (previously known as a "DispVM") is a lightweight VM that can be created quickly and will disappear when closed.
DisposableVMs are usually created in order to host a single application, like a viewer, editor, or web browser.
From inside an AppVM, choosing the `Open in DisposableVM` option on a file will launch a DisposableVM for just that file.
Changes made to a file opened in a DisposableVM are passed back to the originating VM.
This means that you can safely work with untrusted files without risk of compromising your other VMs.
DisposableVMs can be launched either directly from dom0's Start Menu or terminal window, or from within AppVMs.
While running, DisposableVMs will appear in Qubes VM Manager with the name `disp####`.
[![disposablevm-example.png](/attachment/wiki/DisposableVms/disposablevm-example.png)](/attachment/wiki/DisposableVms/disposablevm-example.png)
This diagram provides a general example of how DisposableVMs can be used to safely open untrusted links and attachments in DisposableVMs. See [this article](https://blog.invisiblethings.org/2010/06/01/disposable-vms.html) for more on why one would want to use a DisposableVM.
## Security
If a [DisposableVM Template](/doc/glossary/#disposablevm-template) becomes compromised, then any DisposableVM based on that DisposableVM Template could be compromised.
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.
### DisposableVMs and Local Forensics
At this time, DisposableVMs should not be relied upon to circumvent local forensics, as they do not run entirely in RAM.
For details, see [this thread](https://groups.google.com/d/topic/qubes-devel/QwL5PjqPs-4/discussion).
When it is essential to avoid leaving any trace, consider using [Tails](https://tails.boum.org/).
## DisposableVMs and Networking
Similarly to how AppVMs are based on their underlying [TemplateVM](/doc/glossary/#templatevm), DisposableVMs are based on their underlying [DisposableVM Template](/doc/glossary/#disposablevm-template).
R4.0 introduces the concept of multiple DisposableVM Templates, whereas R3.2 was limited to only one.
On a fresh installation of Qubes, the default DisposableVM Template is called `fedora-XX-dvm` (where `XX` is the Fedora version of the default TemplateVM).
If you have included the Whonix option in your install, there will also be a `whonix-ws-dvm` DisposableVM Template available for your use.
You can set any AppVM to have the ability to act as a DisposableVM Template with:
```
qvm-prefs <vmname> template_for_dispvms True
```
The default system wide DisposableVM Template can be changed with `qubes-prefs default_dispvm`.
By combining the two, choosing `Open in DisposableVM` from inside an AppVM will open the document in a DisposableVM based on the default DisposableVM Template you specified.
You can change this behaviour for individual VMs: in the Application Menu, open Qube Settings for the VM in question and go to the "Advanced" tab.
Here you can edit the "Default DisposableVM" setting to specify which DisposableVM Template will be used to launch DisposableVMs from that VM.
This can also be changed from the command line with:
```
qvm-prefs <VM> default_dispvm <DISPOSABLEVM_TEMPLATE>
```
For example, `anon-whonix` has been set to use `whonix-ws-dvm` as its `default_dispvm`, instead of the system default.
You can even set an AppVM that has also been configured as a DisposableVM Template to use itself, so DisposableVMs launched from within the AppVM/DisposableVM Template would inherit the same settings.
NetVM and firewall rules for DisposableVM Templates can be set as they can for a normal VM.
By default a DisposableVM will inherit the NetVM and firewall settings of the DisposableVM Template on which it is based.
This is a change in behaviour from R3.2, where DisposableVMs would inherit the settings of the AppVM from which they were launched.
Therefore, launching a DisposableVM from an AppVM will result in it using the network/firewall settings of the DisposableVM Template on which it is based.
For example, if an AppVM uses sys-net as its NetVM, but the default system DisposableVM uses sys-whonix, any DisposableVM launched from this AppVM will have sys-whonix as its NetVM.
**Warning:** The opposite is also true.
This means if you have changed anon-whonix's `default_dispvm` to use the system default, and the system default DisposableVM uses sys-net, launching a DisposableVM from inside anon-whonix will result in the DisposableVM using sys-net.
A DisposableVM launched from the Start Menu inherits the NetVM and firewall settings of the DisposableVM Template on which it is based.
Note that changing the "NetVM" setting for the system default DisposableVM Template *does* affect the NetVM of DisposableVMs launched from the Start Menu.
Different DisposableVM Templates with individual NetVM settings can be added to the Start Menu.
**Important Notes:**
Some DisposableVM Templates will automatically create a menu item to launch a DVM, if you do not see an entry and want to add one please use the command:
```
qvm-features <DISPOSABLEVM> appmenus-dispvm 1
```
To launch a DisposableVM Template from the command line, in dom0 please type the following:
```
qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+NameOfApp
```
## Opening a file in a DisposableVM via GUI
In an AppVM's file manager, right click on the file you wish to open in a DisposableVM, then choose "View in DisposableVM" or "Edit in DisposableVM".
Wait a few seconds and the default application for this file type should appear displaying the file content.
This app is running in its own dedicated VM -- a DisposableVM created for the purpose of viewing or editing this very file.
Once you close the viewing application the whole DisposableVM will be destroyed.
If you have edited the file and saved the changes, the changed file will be saved back to the original AppVM, overwriting the original.
![r4.0-open-in-dispvm-1.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-1.png) ![r4.0-open-in-dispvm-2.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-2.png)
## Opening a fresh web browser instance in a new DisposableVM
Sometimes it is desirable to open an instance of Firefox within a new fresh DisposableVM.
This can be done easily using the Start Menu: just go to **Application Menu -\> DisposableVM -\> DisposableVM:Firefox web browser**.
Wait a few seconds until a web browser starts.
Once you close the viewing application the whole DisposableVM will be destroyed.
![r4.0-open-in-dispvm-3.png](/attachment/wiki/DisposableVms/r4.0-open-in-dispvm-3.png)
## Opening a file in a DisposableVM via command line (from AppVM)
Use the `qvm-open-in-dvm` command from a terminal in your AppVM:
~~~
[user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
~~~
Note that the `qvm-open-in-dvm` process will not exit until you close the application in the DisposableVM.
## Starting an arbitrary program in a DisposableVM from an AppVM
Sometimes it can be useful to start an arbitrary program in a DisposableVM.
The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
Starting an arbitrary program can be done from an AppVM by running
~~~
[user@vault ~]$ qvm-run '@dispvm' xterm
~~~
The created DisposableVM can be accessed via other tools (such as `qvm-copy-to-vm`) using its `disp####` name as shown in the Qubes Manager or `qvm-ls`.
## Starting an arbitrary application in a DisposableVM via command line from dom0
The Application Launcher has shortcuts for opening a terminal and a web browser in dedicated DisposableVMs, since these are very common tasks.
The DisposableVM will stay running so long as the process which started the DisposableVM has not exited.
Some applications, such as GNOME Terminal, do not wait for the application to close before the process exits (details [here](https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009)).
It is possible to start an arbitrary application in a DisposableVM directly from dom0 by running:
~~~
$ qvm-run --dispvm=<DISPOSABLEVM_TEMPLATE> --service qubes.StartApp+xterm
~~~
The label color will be inherited from `<DISPOSABLEVM_TEMPLATE>`.
(The DisposableVM Application Launcher shortcut used for starting programs runs a very similar command to the one above.)
### Opening a link in a DisposableVM based on a non-default DisposableVM Template from a qube
Suppose that the default DisposableVM Template for your `email` qube has no networking (e.g., so that untrusted attachments can't phone home).
However, sometimes you want to open email links in DisposableVMs.
Obviously, you can't use the default DisposableVM Template, since it has no networking, so you need to be able to specify a different DisposableVM Template.
You can do that with this command from the `email` qube (as long as your RPC policies allow it):
~~~
$ qvm-open-in-vm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> https://www.qubes-os.org
~~~
This will create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`, open the default web browser in that DisposableVM, and navigate to `https://www.qubes-os.org`.
#### Example of RPC policies to allow this behavior
In dom0, add the following line at the beginning of the file `/etc/qubes-rpc/policy/qubes.OpenURL`
~~~
@anyvm @dispvm:<ONLINE_DISPOSABLEVM_TEMPLATE> allow
~~~
This line means:
- FROM: Any VM
- TO: A DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>`
- WHAT: Allow sending an "Open URL" request
In other words, any VM will be allowed to create a new DisposableVM based on `<ONLINE_DISPOSABLEVM_TEMPLATE>` and open a URL inside of that DisposableVM.
More information about RPC policies for DisposableVMs can be found [here](/doc/qrexec/#qubes-rpc-administration).
## Customizing DisposableVMs
You can change the template used to generate the DisposableVMs, and change settings used in the DisposableVM savefile.
These changes will be reflected in every new DisposableVM based on that template.
Full instructions can be found [here](/doc/disposablevm-customization/).

6
user/reference/glossary.md
View File

@ -17,12 +17,12 @@ Any [qube](#qube) that depends on a [template](#template) for its root filesyste
* Historical note: This term originally meant "a qube intended for running user software applications" (hence the name "app").
* Historical note: This is the preferred term replacing the deprecated term "TemplateBasedVM."
* Historical note: This is the preferred term replacing the deprecated term "app qube."
disposable
----------
See [Dispoables](/doc/disposables/).
See [Dispoables](/doc/how-to-use-disposables/).
A temporary [app qube](#app-qube) based on a [disposable template](#disposable-template) that can quickly be created, used, and destroyed.
@ -68,7 +68,7 @@ By default, most domUs lack direct hardware access.
HVM
---
[Hardware-assisted Virtual Machine](/doc/standalone-and-HVM/).
[Hardware-assisted Virtual Machine](/doc/standalones-and-HVM/).
Any fully virtualized, or hardware-assisted, [VM](#vm) utilizing the virtualization extensions of the host CPU.
Although HVMs are typically slower than paravirtualized qubes due to the required emulation, HVMs allow the user to create domains based on any operating system.

10
user/security-in-qubes/data-leaks.md
View File

@ -17,14 +17,14 @@ The Role of the Firewall
**[Firewalling in Qubes](/doc/firewall/) is not intended to be a leak-prevention mechanism.**
There are several reasons for this, which will be explained below.
However, the main reason is that Qubes cannot prevent an attacker who has compromised one AppVM with restrictive firewall rules from leaking data via cooperative covert channels through another compromised AppVM with nonrestrictive firewall rules.
However, the main reason is that Qubes cannot prevent an attacker who has compromised one app qube with restrictive firewall rules from leaking data via cooperative covert channels through another compromised app qube with nonrestrictive firewall rules.
For example, suppose you have an `email` AppVM.
For example, suppose you have an `email` app qube.
You have set the firewall rules for `email` such that it can communicate only with your email server.
Now suppose that an attacker sends you a GPG-encrypted message which exploits a hypothetical bug in the GnuPG process.
There are now multiple ways the attacker could proceed to leak data (such as confidential email messages) from `email`.
The most obvious way is by simply emailing the data to himself.
Another possibility is that the attacker has also compromised another one of your AppVMs, such as your `netvm`, which is normally assumed to be untrusted and has unrestricted access to the network.
Another possibility is that the attacker has also compromised another one of your app qubes, such as your `netvm`, which is normally assumed to be untrusted and has unrestricted access to the network.
In this case, the attacker might move data from `email` to the `netvm` via a covert channel, such as the CPU cache.
Such covert channels have been described and even implemented in some "lab environments" and might allow for bandwidths of even a few tens of bits/sec.
It is unclear whether such channels could be implemented in a real world system, where multiple VMs are running at the same time, each handling tens or hundreds of processes, all using the same cache memory, but it is worth keeping in mind.
@ -41,7 +41,7 @@ Types of Data Leaks
In order to understand and attempt to prevent data leaks in Qubes, we must distinguish among three different types of relevant data leaks:
1. **Intentional leaks.** Malicious software which actively tries to leak data out of an AppVM, perhaps via cooperative covert channels established with other malicious software in another AppVM or on some server via networking, if networking, even limited, is allowed for the AppVM.
1. **Intentional leaks.** Malicious software which actively tries to leak data out of an app qube, perhaps via cooperative covert channels established with other malicious software in another app qube or on some server via networking, if networking, even limited, is allowed for the app qube.
2. **Intentional sniffing.** Malicious software trying to use side channels to, e.g., actively guess some key material used in another VM by some non-malicious software there (e.g., non-leak-proof GPG accidentally leaking out bits of the private key by generating some timing patterns when using this key for some crypto operation).
Such attacks have been described in the academic literature, but it is doubtful that they would succeed in practice in a moderately busy general purpose system like Qubes OS where the attacker normally has no way to trigger the target crypto operation explicitly and it is normally required that the attacker trigger many such operations.
@ -49,7 +49,7 @@ Such attacks have been described in the academic literature, but it is doubtful
3. **Unintentional leaks.** Non-malicious software which is either buggy or doesn't maintain the privacy of user data, whether by design or accident.
For example, software which automatically sends error reports to a remote server, where these reports contain details about the system which the user did not want to share.
Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an AppVM to "none") can fully protect against leaks of type 3.
Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3.
However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2.
There are few effective, practical policy measures available to end-users today to stop the leaks of type 1.
It is likely that the only way to fully protect against leaks of type 2 is to either pause or shut down all other VMs while performing sensitive operations in the target VM(s) (such as key generation).

2
user/security-in-qubes/firewall.md
View File

@ -494,7 +494,7 @@ Where to put firewall rules
---------------------------
Implicit in the above example [scripts](/doc/config-files/), but worth calling attention to: for all qubes *except* those supplying networking, iptables commands should be added to the `/rw/config/rc.local` script.
For AppVMs supplying networking (`sys-firewall` inclusive), iptables commands should be added to `/rw/config/qubes-firewall-user-script`.
For app qubes supplying networking (`sys-firewall` inclusive), iptables commands should be added to `/rw/config/qubes-firewall-user-script`.
Firewall troubleshooting
------------------------

24
user/security-in-qubes/split-gpg.md
View File

@ -16,7 +16,7 @@ ref: 168
title: Split GPG
---
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" is played by another Qubes AppVM.
Split GPG implements a concept similar to having a smart card with your private GPG keys, except that the role of the "smart card" is played by another Qubes app qube.
This way one not-so-trusted domain, e.g. the one where Thunderbird is running, can delegate all crypto operations -- such as encryption/decryption and signing -- to another, more trusted, network-isolated domain.
This way the compromise of your domain where Thunderbird or another client app is running -- arguably a not-so-unthinkable scenario -- does not allow the attacker to automatically also steal all your keys.
(We should make a rather obvious comment here that the so-often-used passphrases on private keys are pretty meaningless because the attacker can easily set up a simple backdoor which would wait until the user enters the passphrase and steal the key then.)
@ -64,9 +64,9 @@ For Fedora:
### Setting up the GPG backend domain
First, create a dedicated AppVM for storing your keys (we will be calling it the GPG backend domain).
First, create a dedicated app qube for storing your keys (we will be calling it the GPG backend domain).
It is recommended that this domain be network disconnected (set its netvm to `none`) and only used for this one purpose.
In later examples this AppVM is named `work-gpg`, but of course it might have any other name.
In later examples this app qube is named `work-gpg`, but of course it might have any other name.
Make sure that gpg is installed there.
At this stage you can add the private keys you want to store there, or you can now set up Split GPG and add the keys later.
@ -116,7 +116,7 @@ ssb 4096R/30498E2A 2012-11-15
(...)
```
Note that running normal `gpg -K` in the demo above shows no private keys stored in this AppVM.
Note that running normal `gpg -K` in the demo above shows no private keys stored in this app qube.
A note on `gpg` and `gpg2`:
@ -125,20 +125,20 @@ If you encounter trouble while trying to set up Split GPG, make sure you're usin
### Advanced Configuration
The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the AppVM reboot, of course.
The `qubes-gpg-client-wrapper` script sets the `QUBES_GPG_DOMAIN` variable automatically based on the content of the file `/rw/config/gpg-split-domain`, which should be set to the name of the GPG backend VM. This file survives the app qube reboot, of course.
```shell_session
[user@work-email ~]$ sudo bash
[root@work-email ~]$ echo "work-gpg" > /rw/config/gpg-split-domain
```
Split GPG's default qrexec policy requires the user to enter the name of the AppVM containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` place the following line at the top of the file `/etc/qubes-rpc/policy/qubes.Gpg`:
Split GPG's default qrexec policy requires the user to enter the name of the app qube containing GPG keys on each invocation. To improve usability for applications like Thunderbird with Enigmail, in `dom0` place the following line at the top of the file `/etc/qubes-rpc/policy/qubes.Gpg`:
```
work-email work-gpg allow
```
where `work-email` is the Thunderbird + Enigmail AppVM and `work-gpg` contains your GPG keys.
where `work-email` is the Thunderbird + Enigmail app qube and `work-gpg` contains your GPG keys.
You may also edit the qrexec policy file for Split GPG in order to tell Qubes your default gpg vm (qrexec prompts will appear with the gpg vm preselected as the target, instead of the user needing to type a name in manually). To do this, append `,default_target=<vmname>` to `ask` in `/etc/qubes-rpc/policy/qubes.Gpg`. For the examples given on this page:
@ -146,7 +146,7 @@ You may also edit the qrexec policy file for Split GPG in order to tell Qubes yo
@anyvm @anyvm ask,default_target=work-gpg
```
Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple AppVMs with Split GPG set up.
Note that, because this makes it easier to accept Split GPG's qrexec authorization prompts, it may decrease security if the user is not careful in reviewing presented prompts. This may also be inadvisable if there are multiple app qubes with Split GPG set up.
## Using Thunderbird
@ -222,7 +222,7 @@ The following command will configure Keybase to use `/usr/bin/qubes-gpg-client-w
$ keybase config set gpg.command /usr/bin/qubes-gpg-client-wrapper
```
Now that Keybase is configured to use `qubes-gpg-client-wrapper`, you will be able to use `keybase pgp select` to choose a GPG key from your backend GPG AppVM and link that key to your Keybase identity.
Now that Keybase is configured to use `qubes-gpg-client-wrapper`, you will be able to use `keybase pgp select` to choose a GPG key from your backend GPG app qube and link that key to your Keybase identity.
## Using Git with Split GPG
@ -271,7 +271,7 @@ Now you can use `git stag` to add a signed tag to a commit and `git vtag` to ver
## Importing public keys
Use `qubes-gpg-import-key` in the client AppVM to import the key into the GPG backend VM.
Use `qubes-gpg-import-key` in the client app qube to import the key into the GPG backend VM.
```shell_session
[user@work-email ~]$ export QUBES_GPG_DOMAIN=work-gpg
@ -369,7 +369,7 @@ Rather, the master secret key remains in the `vault` VM, which is extremely unli
<sup>\*</sup> The attacker might nonetheless be able to leak the secret subkeys from the `work-gpg` VM in the manner described above, but even if this is successful, the secure master secret key can simply be used to revoke the compromised subkeys and to issue new subkeys in their place.
(This is significantly less devastating than having to create a new *master* keypair.)
<sup>\*</sup>In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the TemplateVM](/doc/templates/#trusting-your-templatevms) upon which the `vault` VM is based.
<sup>\*</sup>In order to gain access to the `vault` VM, the attacker would require the use of, e.g., a general Xen VM escape exploit or a [signed, compromised package which is already installed in the template](/doc/templates/#trusting-your-templates) upon which the `vault` VM is based.
### Subkey Tutorials and Discussions
@ -388,7 +388,7 @@ As always, exercise caution and use your good judgment.)
See ticket [#474](https://github.com/QubesOS/qubes-issues/issues/474) for more details and plans how to get around this problem, as well as the section on [using Split GPG with subkeys](#advanced-using-split-gpg-with-subkeys).
* It doesn't solve the problem of allowing the user to know what is to be signed before the operation gets approved.
Perhaps the GPG backend domain could start a DisposableVM and have the to-be-signed document displayed there? To Be Determined.
Perhaps the GPG backend domain could start a disposable and have the to-be-signed document displayed there? To Be Determined.
* The Split GPG client will fail to sign or encrypt if the private key in the GnuPG backend is protected by a passphrase.
It will give an `Inappropriate ioctl for device` error.

10
user/security-in-qubes/u2f-proxy.md
View File

@ -79,20 +79,20 @@ $ qvm-service --enable work qubes-u2f-proxy
The above assumes a `work` qube in which you would like to enable u2f. Repeat the `qvm-service` command for all qubes that should have the proxy enabled. Alternatively, you can add `qubes-u2f-proxy` in VM settings -> Services in the Qube Manager of each qube you would like to enable the service.
In Fedora TemplateVMs:
In Fedora templates:
```
$ sudo dnf install qubes-u2f
```
In Debian TemplateVMs:
In Debian templates:
```
$ sudo apt install qubes-u2f
```
As usual with software updates, shut down the templates after installation, then restart `sys-usb` and all qubes that use the proxy.
After that, you may use your U2F token (but see [Browser support](#templatevm-and-browser-support) below).
After that, you may use your U2F token (but see [Browser support](#template-and-browser-support) below).
## Advanced usage: per-qube key access
@ -125,9 +125,9 @@ systemctl disable qubes-u2fproxy@sys-usb.service
Replace `USB_QUBE` with the actual USB qube name.
## TemplateVM and browser support
## Template and browser support
The large number of possible combinations of TemplateVM (Fedora 27, 28; Debian 8, 9) and browser (multiple Google Chrome versions, multiple Chromium versions, multiple Firefox versions) made it impractical for us to test every combination that users are likely to attempt with the Qubes U2F Proxy.
The large number of possible combinations of template (Fedora 27, 28; Debian 8, 9) and browser (multiple Google Chrome versions, multiple Chromium versions, multiple Firefox versions) made it impractical for us to test every combination that users are likely to attempt with the Qubes U2F Proxy.
In some cases, you may be the first person to try a particular combination.
Consequently (and as with any new feature), users will inevitably encounter bugs.
We ask for your patience and understanding in this regard.

6
user/security-in-qubes/vm-sudo.md
View File

@ -118,9 +118,9 @@ Do not rely on this for extra security.**
>/etc/qubes-rpc/policy/qubes.VMAuth
```
(Note: any VMs you would like still to have passwordless root access (e.g. TemplateVMs) can be specified in the second file with "\<vmname\> dom0 allow")
(Note: any VMs you would like still to have passwordless root access (e.g. Templates) can be specified in the second file with "\<vmname\> dom0 allow")
2. Configuring Fedora TemplateVM to prompt Dom0 for any authorization request:
2. Configuring Fedora template to prompt Dom0 for any authorization request:
- In `/etc/pam.d/system-auth`, replace all lines beginning with "auth" with these lines:
```
@ -143,7 +143,7 @@ Do not rely on this for extra security.**
[root@fedora-20-x64]# rm /etc/polkit-1/localauthority/50-local.d/qubes-allow-all.pkla
```
3. Configuring Debian/Whonix TemplateVM to prompt Dom0 for any authorization request:
3. Configuring Debian/Whonix template to prompt Dom0 for any authorization request:
- In `/etc/pam.d/common-auth`, replace all lines beginning with "auth" with these lines:
```

6
user/security-in-qubes/yubi-key.md
View File

@ -24,7 +24,7 @@ Same as in the OTP case, you will need to set up your YubiKey, choose a separate
To use this mode you need to:
1. Install yubikey personalization the packages in your TemplateVM on which your USB VM is based.
1. Install yubikey personalization the packages in your template on which your USB VM is based.
For Fedora.
@ -38,8 +38,8 @@ To use this mode you need to:
sudo apt-get install yubikey-personalization yubikey-personalization-gui
```
Shut down your TemplateVM.
Then, either reboot your USB VM (so changes inside the TemplateVM take effect in your USB TemplateBasedVM) or install the packages inside your USB VM if you would like to avoid rebooting it.
Shut down your template.
Then, either reboot your USB VM (so changes inside the template take effect in your USB app qube) or install the packages inside your USB VM if you would like to avoid rebooting it.
2. Configure your YubiKey for challenge-response `HMAC-SHA1` mode, for example [following this tutorial](https://www.yubico.com/products/services-software/personalization-tools/challenge-response/).

24
user/templates/debian/debian-upgrade.md
View File

@ -14,16 +14,16 @@ title: How to Upgrade a Debian Template In-place
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> This page is intended for advanced users only. Most users seeking to upgrade should instead <a href="/doc/templates/debian/#installing">install a new Debian TemplateVM</a>. Learn more about the two options <a href="/doc/templates/debian/#upgrading">here</a>.
<b>Warning:</b> This page is intended for advanced users only. Most users seeking to upgrade should instead <a href="/doc/templates/debian/#installing">install a new Debian template</a>. Learn more about the two options <a href="/doc/templates/debian/#upgrading">here</a>.
</div>
This page provides instructions for performing an in-place upgrade of an installed [Debian TemplateVM](/doc/templates/debian/).
If you wish to install a new, unmodified Debian TemplateVM instead of upgrading a template that is already installed in your system, please see the [Debian TemplateVM](/doc/templates/debian/) page instead. ([Learn more about the two options.](/doc/templates/debian/#upgrading))
This page provides instructions for performing an in-place upgrade of an installed [Debian Template](/doc/templates/debian/).
If you wish to install a new, unmodified Debian template instead of upgrading a template that is already installed in your system, please see the [Debian Template](/doc/templates/debian/) page instead. ([Learn more about the two options.](/doc/templates/debian/#upgrading))
In general, upgrading a Debian TemplateVM follows the same process as [upgrading a native Debian system](https://wiki.debian.org/DebianUpgrade).
In general, upgrading a Debian template follows the same process as [upgrading a native Debian system](https://wiki.debian.org/DebianUpgrade).
## Summary instructions for Debian TemplateVMs
## Summary instructions for Debian templates
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian version number *from* which you are upgrading, and `<new>` is the Debian version number *to* which you are upgrading.
@ -40,10 +40,10 @@ In general, upgrading a Debian TemplateVM follows the same process as [upgrading
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
## Detailed instructions for Debian TemplateVMs
## Detailed instructions for Debian templates
These instructions will show you how to upgrade Debian TemplateVMs.
The same general procedure may be used to upgrade any template based on the standard Debian TemplateVM.
These instructions will show you how to upgrade Debian templates.
The same general procedure may be used to upgrade any template based on the standard Debian template.
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `debian-<old>`, or `debian-<new>`, where `<old>` is the Debian version number *from* which you are upgrading, and `<new>` is the Debian version number *to* which you are upgrading.
@ -101,7 +101,7 @@ The same general procedure may be used to upgrade any template based on the stan
[user@debian-<new> ~]$ sudo fstrim -av
```
8. Shut down the new TemplateVM.
8. Shut down the new template.
```
[user@dom0 ~]$ qvm-shutdown debian-<new>
@ -118,9 +118,9 @@ The same general procedure may be used to upgrade any template based on the stan
11. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling)
Make sure that the template you're uninstalling is the old one, not the new one!
## StandaloneVMs
## Standalones
The procedure for upgrading a Debian [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
The procedure for upgrading a Debian [standalone](/doc/standalone-and-hvm/) is the same as for a template.
## Release-specific notes
@ -138,7 +138,7 @@ Please see [Debian's Buster upgrade instructions](https://www.debian.org/release
* If sound is not working, you may need to enable the Qubes testing repository to get the testing version of `qubes-gui-agent`.
This can be done by editing the `/etc/apt/sources.list.d/qubes-r4.list` file and uncommenting the `Qubes Updates Candidates` repo.
* User-initiated updates/upgrades may not run when a templateVM first starts.
* User-initiated updates/upgrades may not run when a template first starts.
This is due to a new Debian config setting that attempts to update automatically; it should be disabled with `sudo systemctl disable apt-daily.{service,timer}`.
Relevant discussions:

22
user/templates/debian/debian.md
View File

@ -12,14 +12,14 @@ title: Debian Templates
---
The Debian [TemplateVM](/doc/templates/) is an officially [supported](/doc/supported-versions/#templatevms) TemplateVM in Qubes OS.
This page is about the standard (or "full") Debian TemplateVM.
For the minimal version, please see the [Minimal TemplateVMs](/doc/templates/minimal/) page.
The Debian [template](/doc/templates/) is an officially [supported](/doc/supported-versions/#templates) template in Qubes OS.
This page is about the standard (or "full") Debian template.
For the minimal version, please see the [Minimal templates](/doc/templates/minimal/) page.
There is also a [Qubes page on the Debian Wiki](https://wiki.debian.org/Qubes).
## Installing
To [install](/doc/templates/#installing) a specific Debian TemplateVM that is not currently installed in your system, use the following command in dom0:
To [install](/doc/templates/#installing) a specific Debian template that is not currently installed in your system, use the following command in dom0:
```
$ sudo qubes-dom0-update qubes-template-debian-XX
@ -27,25 +27,25 @@ $ sudo qubes-dom0-update qubes-template-debian-XX
(Replace `XX` with the Debian version number of the template you wish to install.)
To reinstall a Debian TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
To reinstall a Debian template that is already installed in your system, see [How to Reinstall a template](/doc/reinstall-template/).
## After Installing
After installing a fresh Debian TemplateVM, we recommend performing the following steps:
After installing a fresh Debian template, we recommend performing the following steps:
1. [Update the TemplateVM](/doc/software-update-vm/).
1. [Update the template](/doc/software-update-vm/).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
2. [Switch any app qubes that are based on the old template to the new one](/doc/templates/#switching).
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
3. If desired, [uninstall the old template](/doc/templates/#uninstalling).
## Updating
For routine daily TemplateVM updates within a given Debian release, see [Updating software in TemplateVMs](/doc/how-to-install-software/#updating-software-in-templatevms).
For routine daily template updates within a given Debian release, see [Updating software in templates](/doc/how-to-install-software/#instructions).
## Upgrading
There are two ways to upgrade your TemplateVM to a new Debian release:
There are two ways to upgrade your template to a new Debian release:
- [Install a fresh template to replace the existing one.](#installing) **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. In the old Debian template, see `/var/log/dpkg.log` and `/var/log/apt/history.log` for logs of package manager actions.

32
user/templates/fedora/fedora-upgrade.md
View File

@ -25,13 +25,13 @@ title: How to Upgrade a Fedora Template In-place
<div class="alert alert-danger" role="alert">
<i class="fa fa-exclamation-triangle"></i>
<b>Warning:</b> This page is intended for advanced users only. Most users seeking to upgrade should instead <a href="/doc/templates/fedora/#installing">install a new Fedora TemplateVM</a>. Learn more about the two options <a href="/doc/templates/fedora/#upgrading">here</a>.
<b>Warning:</b> This page is intended for advanced users only. Most users seeking to upgrade should instead <a href="/doc/templates/fedora/#installing">install a new Fedora template</a>. Learn more about the two options <a href="/doc/templates/fedora/#upgrading">here</a>.
</div>
This page provides instructions for performing an in-place upgrade of an installed [Fedora TemplateVM](/doc/templates/fedora/).
If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading a template that is already installed in your system, please see the [Fedora TemplateVM](/doc/templates/fedora/) page instead. ([Learn more about the two options.](/doc/templates/fedora/#upgrading))
This page provides instructions for performing an in-place upgrade of an installed [Fedora Template](/doc/templates/fedora/).
If you wish to install a new, unmodified Fedora template instead of upgrading a template that is already installed in your system, please see the [Fedora Template](/doc/templates/fedora/) page instead. ([Learn more about the two options.](/doc/templates/fedora/#upgrading))
## Summary instructions for standard Fedora TemplateVMs
## Summary instructions for standard Fedora templates
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `fedora-<old>`, or `fedora-<new>`, where `<old>` is the Fedora version number *from* which you are upgrading, and `<new>` is the Fedora version number *to* which you are upgrading.
@ -52,10 +52,10 @@ If you wish to install a new, unmodified Fedora TemplateVM instead of upgrading
**Recommended:** [Switch everything that was set to the old template to the new template.](/doc/templates/#switching)
## Detailed instructions for standard Fedora TemplateVMs
## Detailed instructions for standard Fedora templates
These instructions will show you how to upgrade the standard Fedora TemplateVM.
The same general procedure may be used to upgrade any template based on the standard Fedora TemplateVM.
These instructions will show you how to upgrade the standard Fedora template.
The same general procedure may be used to upgrade any template based on the standard Fedora template.
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `fedora-<old>`, or `fedora-<new>`, where `<old>` is the Fedora version number *from* which you are upgrading, and `<new>` is the Fedora version number *to* which you are upgrading.
@ -123,7 +123,7 @@ The same general procedure may be used to upgrade any template based on the stan
At least X MB more space needed on the / filesystem.
`
In this case, one option is to [resize the TemplateVM's disk image](/doc/resize-disk-image/) before reattempting the upgrade process.
In this case, one option is to [resize the template's disk image](/doc/resize-disk-image/) before reattempting the upgrade process.
(See [Additional Information](#additional-information) below for other options.)
4. Check that you are on the correct (new) Fedora release. Do this check only after completing the upgrade process. This is *not* a troubleshooting procedure for fixing download issues from the repository. This check simply verifies that your clone has successfully been upgraded.
@ -143,7 +143,7 @@ The same general procedure may be used to upgrade any template based on the stan
[user@fedora-<new> ~]$ sudo fstrim -av
```
6. Shut down the new TemplateVM.
6. Shut down the new template.
```
[user@dom0 ~]$ qvm-shutdown fedora-<new>
@ -167,7 +167,7 @@ The same general procedure may be used to upgrade any template based on the stan
10. (Optional) [Uninstall the old template.](/doc/templates/#uninstalling)
Make sure that the template you're uninstalling is the old one, not the new one!
## Summary instructions for Fedora Minimal TemplateVMs
## Summary instructions for Fedora Minimal templates
**Note:** The prompt on each line indicates where each command should be entered: `dom0`, `fedora-<old>`, or `fedora-<new>`, where `<old>` is the Fedora version number *from* which you are upgrading, and `<new>` is the Fedora version number *to* which you are upgrading.
@ -179,18 +179,18 @@ The same general procedure may be used to upgrade any template based on the stan
[user@fedora-<new>-minimal ~]# fstrim -v /
```
(Shut down TemplateVM by any normal means.)
(Shut down template by any normal means.)
(If you encounter insufficient space issues, you may need to use the methods described for the standard template above.)
## StandaloneVMs
## Standalones
The procedure for upgrading a Fedora [StandaloneVM](/doc/standalone-and-hvm/) is the same as for a TemplateVM.
The procedure for upgrading a Fedora [standalone](/doc/standalone-and-hvm/) is the same as for a template.
## Release-specific notes
See the [news](/news/) announcement for each specific TemplateVM release for any important notices about that particular release.
See the [news](/news/) announcement for each specific template release for any important notices about that particular release.
### End-of-life (EOL) releases
@ -209,12 +209,12 @@ At least X MB more space needed on the / filesystem.
In this case, you have several options:
1. [Increase the TemplateVM's disk image size](/doc/resize-disk-image/).
1. [Increase the template's disk image size](/doc/resize-disk-image/).
This is the solution mentioned in the main instructions above.
2. Delete files in order to free up space. One way to do this is by uninstalling packages.
You may then reinstall them again after you finish the upgrade process, if desired).
However, you may end up having to increase the disk image size anyway (see previous option).
3. Do the upgrade in parts, e.g., by using package groups.
(First upgrade `@core` packages, then the rest.)
4. Do not perform an in-place upgrade, see [Upgrading Fedora TemplateVMs](/doc/templates/fedora/#upgrading).
4. Do not perform an in-place upgrade, see [Upgrading Fedora templates](/doc/templates/fedora/#upgrading).

18
user/templates/fedora/fedora.md
View File

@ -7,11 +7,11 @@ title: Fedora Templates
---
The Fedora [TemplateVM](/doc/templates/) is the default TemplateVM in Qubes OS. This page is about the standard (or "full") Fedora TemplateVM. For the minimal and Xfce versions, please see the [Minimal TemplateVMs](/doc/templates/minimal/) and [Xfce TemplateVMs](/doc/templates/xfce/) pages.
The Fedora [template](/doc/templates/) is the default template in Qubes OS. This page is about the standard (or "full") Fedora template. For the minimal and Xfce versions, please see the [Minimal templates](/doc/templates/minimal/) and [Xfce templates](/doc/templates/xfce/) pages.
## Installing
To [install](/doc/templates/#installing) a specific Fedora TemplateVM that is not currently installed in your system, use the following command in dom0:
To [install](/doc/templates/#installing) a specific Fedora template that is not currently installed in your system, use the following command in dom0:
```
$ sudo qubes-dom0-update qubes-template-fedora-XX
@ -19,25 +19,25 @@ $ sudo qubes-dom0-update qubes-template-fedora-XX
(Replace `XX` with the Fedora version number of the template you wish to install.)
To reinstall a Fedora TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
To reinstall a Fedora template that is already installed in your system, see [How to Reinstall a template](/doc/reinstall-template/).
## After Installing
After installing a fresh Fedora TemplateVM, we recommend performing the following steps:
After installing a fresh Fedora template, we recommend performing the following steps:
1. [Update the TemplateVM](/doc/software-update-vm/).
1. [Update the template](/doc/software-update-vm/).
2. [Switch any TemplateBasedVMs that are based on the old TemplateVM to the new one](/doc/templates/#switching).
2. [Switch any app qubes that are based on the old template to the new one](/doc/templates/#switching).
3. If desired, [uninstall the old TemplateVM](/doc/templates/#uninstalling).
3. If desired, [uninstall the old template](/doc/templates/#uninstalling).
## Updating
For routine daily updates within a given release, see [Updating software in TemplateVMs](/doc/how-to-install-software/#updating-software-in-templatevms).
For routine daily updates within a given release, see [Updating software in templates](/doc/how-to-install-software/#instructions).
## Upgrading
There are two ways to upgrade your TemplateVM to a new Fedora release:
There are two ways to upgrade your template to a new Fedora release:
- [Install a fresh template to replace the existing one.](#installing) **This option may be simpler for less experienced users.** After you install the new template, redo all desired template modifications and [switch everything that was set to the old template to the new template](/doc/templates/#switching). You may want to write down the modifications you make to your templates so that you remember what to redo on each fresh install. To see a log of package manager actions, open a terminal in the old Fedora template and use the `dnf history` command.

20
user/templates/how-to-reinstall-a-template.md
View File

@ -10,12 +10,12 @@ title: How to Reinstall a Template
---
If you suspect your [TemplateVM](/doc/templates/) is broken, misconfigured, or compromised, you can reinstall any TemplateVM that was installed from the Qubes repository.
If you suspect your [template](/doc/templates/) is broken, misconfigured, or compromised, you can reinstall any template that was installed from the Qubes repository.
Automatic Method
----------------
First, copy any files that you wish to keep from the TemplateVM's `/home` and `/rw` folders to a safe storage location.
First, copy any files that you wish to keep from the template's `/home` and `/rw` folders to a safe storage location.
Then, in a dom0 terminal, run:
```
@ -44,21 +44,21 @@ $ sudo qubes-dom0-update --enablerepo=qubes-templates-community --action=reinsta
Manual Method
-------------
In what follows, the term "target TemplateVM" refers to whichever TemplateVM you want to reinstall.
If you want to reinstall more than one TemplateVM, repeat these instructions for each one.
In what follows, the term "target template" refers to whichever template you want to reinstall.
If you want to reinstall more than one template, repeat these instructions for each one.
1. Clone the existing target TemplateVM.
1. Clone the existing target template.
This can be a good idea if you've customized the existing template and want to keep your customizations.
On the other hand, if you suspect that this template is broken, misconfigured, or compromised, be certain you do not start any VMs using it in the below procedure.
2. Temporarily change all VMs based on the target TemplateVM to the new clone template, or remove them.
2. Temporarily change all VMs based on the target template to the new clone template, or remove them.
This can be a good idea if you have user data in these VMs that you want to keep.
On the other hand, if you suspect that these VMs (or the templates on which they are based) are broken, misconfigured, or compromised, you may want to remove them instead.
You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the command `qvm-remove <vm-name>` in dom0.
3. Uninstall the target TemplateVM from dom0:
3. Uninstall the target template from dom0:
```
$ sudo dnf remove <template-package-name>
@ -70,7 +70,7 @@ If you want to reinstall more than one TemplateVM, repeat these instructions for
$ sudo dnf remove qubes-template-whonix-gw
```
4. Reinstall the target TemplateVM in dom0:
4. Reinstall the target template in dom0:
```shell_session
$ sudo qubes-dom0-update --enablerepo=<optional-additional-repo> \
@ -84,8 +84,8 @@ If you want to reinstall more than one TemplateVM, repeat these instructions for
qubes-template-whonix-gw
```
5. If you temporarily changed all VMs based on the target TemplateVM to the clone template in step 3, change them back to the new target TemplateVM now.
If you instead removed all VMs based on the old target TemplateVM, you can recreate your desired VMs from the newly reinstalled target TemplateVM now.
5. If you temporarily changed all VMs based on the target template to the clone template in step 3, change them back to the new target template now.
If you instead removed all VMs based on the old target template, you can recreate your desired VMs from the newly reinstalled target template now.
6. Delete the cloned template.
You can do this in Qubes Manager by right-clicking on the VM and clicking **Remove VM**, or you can use the

38
user/templates/minimal-templates.md
View File

@ -13,22 +13,22 @@ ref: 132
title: Minimal Templates
---
The Minimal [TemplateVMs](/doc/templates/) are lightweight versions of their standard TemplateVM counterparts.
The Minimal [templates](/doc/templates/) are lightweight versions of their standard template counterparts.
They have only the most vital packages installed, including a minimal X and xterm installation.
The sections below contain instructions for using the template and provide some examples for common use cases.
There are currently three Minimal TemplateVMs corresponding to the standard [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/) and [Gentoo](/doc/templates/gentoo/) TemplateVMs.
There are currently three Minimal templates corresponding to the standard [Fedora](/doc/templates/fedora/), [Debian](/doc/templates/debian/), [CentOS](/doc/templates/centos/) and [Gentoo](/doc/templates/gentoo/) templates.
## Important
1. The Minimal TemplateVMs are intended only for advanced users.
If you encounter problems with the Minimal TemplateVMs, we recommend that you use their standard TemplateVM counterparts instead.
1. The Minimal templates are intended only for advanced users.
If you encounter problems with the Minimal templates, we recommend that you use their standard template counterparts instead.
2. If something works with a standard TemplateVM but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
2. If something works with a standard template but not the minimal version, this is most likely due to user error (e.g., a missing package or misconfiguration) rather than a bug.
In such cases, please do *not* file a bug report.
Instead, please see [Help, Support, Mailing Lists, and Forum](/support/) for the appropriate place to ask for help.
Once you have learned how to solve your problem, please [contribute what you learned to the documentation](/doc/doc-guidelines/).
3. The Minimal TemplateVMs are intentionally *minimal*.
3. The Minimal templates are intentionally *minimal*.
[Do not ask for your favorite package to be added to the minimal template by default.](/faq/#could-you-please-make-my-preference-the-default)
4. In order to reduce unnecessary risk, unused repositories have been disabled by default.
@ -36,7 +36,7 @@ There are currently three Minimal TemplateVMs corresponding to the standard [Fed
## Installation
The Minimal TemplateVMs can be installed with the following command (where `X` is your desired distro and version number):
The Minimal templates can be installed with the following command (where `X` is your desired distro and version number):
```
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-minimal
@ -59,20 +59,20 @@ The download may take a while depending on your connection speed.
## Passwordless root
It is an intentional design choice for [Passwordless Root Access in VMs](/doc/vm-sudo/) to be optional in Minimal TemplateVMs.
Since the Minimal TemplateVMs are *minimal*, they are not configured for passwordless root by default.
It is an intentional design choice for [Passwordless Root Access in VMs](/doc/vm-sudo/) to be optional in Minimal templates.
Since the Minimal templates are *minimal*, they are not configured for passwordless root by default.
To update or install packages, execute the following command in dom0 (where `X` is your distro and version number):
```
[user@dom0 ~]$ qvm-run -u root X-minimal xterm
```
This opens a root terminal in the Minimal TemplateVM, from which you can use execute root commands without `sudo`.
This opens a root terminal in the Minimal template, from which you can use execute root commands without `sudo`.
You will have to do this every time if you choose not to enable passwordless root.
If you want to be able to use `sudo` inside a Minimal TemplateVM (or TemplateBasedVMs based on a Minimal TemplateVM), open a root terminal as just instructed, then install the `qubes-core-agent-passwordless-root` package.
If you want to be able to use `sudo` inside a Minimal template (or app qubes based on a Minimal template), open a root terminal as just instructed, then install the `qubes-core-agent-passwordless-root` package.
Optionally, verify that passwordless root now works by opening a normal (non-root) xterm window in the Minimal TemplateVM, then issue the command `sudo -l`.
Optionally, verify that passwordless root now works by opening a normal (non-root) xterm window in the Minimal template, then issue the command `sudo -l`.
This should give you output that includes the `NOPASSWD` keyword.
## Customization
@ -84,7 +84,7 @@ Customizing the template for specific use cases normally only requires installin
## Distro-specific notes
This following sections provide information that is specific to a particular Minimal TemplateVM distro.
This following sections provide information that is specific to a particular Minimal template distro.
### Fedora
@ -106,8 +106,8 @@ As usual, the required packages are to be installed in the running template with
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly.
These packages are:
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in thunar).
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable" will not be shown in thunar).
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template on which the qube responsible for 'dom0' updates (e.g. `sys-firewall`) is based must contain this package.
- `qubes-menus`: Defines menu layout.
- `qubes-desktop-linux-common`: Contains icons and scripts to improve desktop experience.
@ -158,8 +158,8 @@ As usual, the required packages are to be installed in the running template with
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly.
These packages are:
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in thunar).
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable" will not be shown in thunar).
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template on which the qube responsible for 'dom0' updates (e.g. `sys-firewall`) is based must contain this package.
- `qubes-menus`: Defines menu layout.
- `qubes-desktop-linux-common`: Contains icons and scripts to improve desktop experience.
@ -201,8 +201,8 @@ As usual, the required packages are to be installed in the running template with
In Qubes 4.0, additional packages from the `qubes-core-agent` suite may be needed to make the customized minimal template work properly.
These packages are:
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable VM" will not be shown in thunar).
- `qubes-core-agent-nautilus`: This package provides integration with the Nautilus file manager (without it, items like "copy to VM/open in disposable" will not be shown in Nautilus).
- `qubes-core-agent-thunar`: This package provides integration with the thunar file manager (without it, items like "copy to VM/open in disposable" will not be shown in thunar).
- `qubes-core-agent-dom0-updates`: Script required to handle `dom0` updates. Any template on which the qube responsible for 'dom0' updates (e.g. `sys-firewall`) is based must contain this package.
- `qubes-menus`: Defines menu layout.
- `qubes-desktop-linux-common`: Contains icons and scripts to improve desktop experience.

4
user/templates/xfce-templates.md
View File

@ -17,7 +17,7 @@ you can install one of the available Xfce templates for [Fedora](/doc/templates/
## Installation
The Fedora Xfce TemplateVMs can be installed with the following command (where `X` is your desired distro and version number):
The Fedora Xfce templates can be installed with the following command (where `X` is your desired distro and version number):
```
[user@dom0 ~]$ sudo qubes-dom0-update qubes-template-X-xfce
@ -45,5 +45,5 @@ You may wish to try again with the testing repository enabled:
The download may take a while depending on your connection speed.
To reinstall a Xfce TemplateVM that is already installed in your system, see [How to Reinstall a TemplateVM](/doc/reinstall-template/).
To reinstall a Xfce template that is already installed in your system, see [How to Reinstall a template](/doc/reinstall-template/).

24
user/troubleshooting/app-menu-shortcut-troubleshooting.md
View File

@ -11,8 +11,8 @@ ref: 202
title: App Menu Shortcut Troubleshooting
---
For ease of use Qubes aggregates shortcuts to applications that are installed in AppVMs and shows them in one application menu (aka "app menu" or "start menu") in dom0.
Clicking on such shortcut runs the assigned application in its AppVM.
For ease of use Qubes aggregates shortcuts to applications that are installed in app qubes and shows them in one application menu (aka "app menu" or "start menu") in dom0.
Clicking on such shortcut runs the assigned application in its app qube.
![dom0-menu.png"](/attachment/wiki/ManagingAppVmShortcuts/r4.0-dom0-menu.png)
@ -32,10 +32,10 @@ What if my application has not been automatically included in the list of availa
Some times applications may not have included a `.desktop` file and may not be detected by `qvm-sync-appmenus`.
Other times, you may want to make a web shortcut available from the Qubes start menu.
You can manually create new entries in the "available applications" list of shortcuts for all AppVMs based on a TemplateVM.
You can manually create new entries in the "available applications" list of shortcuts for all app qubes based on a template.
To do this:
1. Open a terminal window to the TemplateVM.
1. Open a terminal window to the template.
2. Create a custom `.desktop` file in `/usr/share/applications` (you may need to first create the subdirectory).
Look in `/usr/share/applications` for existing examples, or see the full [file specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html).
It will be something like:
@ -53,17 +53,17 @@ To do this:
Exec=vuescan
```
3. In dom0, run `qvm-sync-appmenus <TemplateVMName>`.
4. Go to VM Settings of the AppVM(s) to which you want to add the new shortcut, then the Applications tab.
3. In dom0, run `qvm-sync-appmenus <templateName>`.
4. Go to VM Settings of the app qube(s) to which you want to add the new shortcut, then the Applications tab.
Move the newly created shortcut to the right under selected.
If you only want to create a shortcut for a single AppVM, you can create a custom menu entry instead:
If you only want to create a shortcut for a single app qube, you can create a custom menu entry instead:
1. Open a terminal window to Dom0.
2. Create a custom `.desktop` file in `~/.local/share/applications`.
Look in the same directory for existing examples, or see the full [file specification](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html).
You may use `qvm-run` inside the `.desktop` file; see [Behind the scenes](/doc/app-menu-shortcut-troubleshooting/#behind-the-scenes) for more details.
3. Edit the `~/.config/menus/applications-merged/<vmname>-vm.menu` file for the AppVM.
3. Edit the `~/.config/menus/applications-merged/<vmname>-vm.menu` file for the app qube.
4. Add a custom menu entry referring to your newly created `.desktop` file.
~~~
@ -78,7 +78,7 @@ If you only want to create a shortcut for a single AppVM, you can create a custo
What about applications in DispVMs?
-----------------------------------
[See here](/doc/disposablevm-customization/).
[See here](/doc/disposable-customization/).
Fixing shortcuts
----------------
@ -102,16 +102,16 @@ Behind the scenes
-----------------
`qvm-sync-appmenus` works by invoking *GetAppMenus* [Qubes service](/doc/qrexec/) in the target domain.
This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the AppVM/TemplateVM directory.
This service enumerates installed applications and sends formatted info back to the dom0 script (`/usr/libexec/qubes-appmenus/qubes-receive-appmenus`) which creates .desktop files in the app qube/template directory.
For Linux VMs the service script is in `/etc/qubes-rpc/qubes.GetAppMenus`.
In Windows it's a PowerShell script located in `c:\Program Files\Invisible Things Lab\Qubes OS Windows Tools\qubes-rpc-services\get-appmenus.ps1` by default.
The list of installed applications for each AppVM is stored in dom0's `~/.local/share/qubes-appmenus/<vmname>/apps.templates`.
The list of installed applications for each app qube is stored in dom0's `~/.local/share/qubes-appmenus/<vmname>/apps.templates`.
Each menu entry is a file that follows the [.desktop file format](https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html) with some wildcards (*%VMNAME%*, *%VMDIR%*).
Applications selected to appear in the menu are stored in `~/.local/share/qubes-appmenus/<vmname>/apps`.
Actual command lines for the menu shortcuts involve `qvm-run` command which starts a process in another domain.
Examples: `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+7-Zip-7-Zip_File_Manager` or `qvm-run -q -a --service -- %VMNAME% qubes.StartApp+firefox`
Note that you can create a shortcut that points to a .desktop file in your AppVM with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`.
Note that you can create a shortcut that points to a .desktop file in your app qube with e.g. `qvm-run -q -a --service -- personal qubes.StartApp+firefox`.

2
user/troubleshooting/media-troubleshooting.md
View File

@ -11,7 +11,7 @@ title: Media Troubleshooting
If you’re having trouble playing a video file in a qube, you’re probably missing the required codecs.
The easiest way to resolve this is to install VLC Media Player and use that to play your video files.
You can do this in multiple different TemplateVM distros by following the instructions [here](/faq/#how-do-i-play-video-files).
You can do this in multiple different template distros by following the instructions [here](/faq/#how-do-i-play-video-files).
## Video lagging

4
user/troubleshooting/pci-troubleshooting.md
View File

@ -151,5 +151,5 @@ Look at the [FAQs](/faq/#i-assigned-a-pci-device-to-a-qube-then-unassigned-itshu
You may have an adapter (wired, wireless), that is not compatible with open-source drivers shipped by Qubes.
You may need to install a binary blob, which provides drivers, from the linux-firmware package.
Open a terminal and run `sudo dnf install linux-firmware` in the TemplateVM upon which your NetVM is based.
You have to restart the NetVM after the TemplateVM has been shut down.
Open a terminal and run `sudo dnf install linux-firmware` in the template upon which your NetVM is based.
You have to restart the NetVM after the template has been shut down.

10
user/troubleshooting/update-troubleshooting.md
View File

@ -22,11 +22,11 @@ Here are some examples of non-Qubes reports about this problem:
More examples can be found by searching for "Failed to synchronize cache for repo" (with quotation marks) on your preferred search engine.
## Lost internet access after a TemplateVM update
## Lost internet access after a template update
In earlier versions of Qubes, there were situations where qubes lost internet access after a TemplateVM update. The following fix should be applied in recent versions of Qubes.
In earlier versions of Qubes, there were situations where qubes lost internet access after a template update. The following fix should be applied in recent versions of Qubes.
Run `systemctl enable NetworkManager-dispatcher.service` in the TemplateVM upon which your NetVM is based.
Run `systemctl enable NetworkManager-dispatcher.service` in the template upon which your NetVM is based.
You may have to reboot afterward for the change to take effect.
(Note: This is an upstream problem. See [this Redhat ticket](https://bugzilla.redhat.com/show_bug.cgi?id=974811)).
For details, see the qubes-users mailing list threads [here](https://groups.google.com/d/topic/qubes-users/xPLGsAJiDW4/discussion) and [here](https://groups.google.com/d/topic/qubes-users/uN9G8hjKrGI/discussion).)
@ -37,12 +37,12 @@ This has nothing to do with Qubes.
It's a longstanding Windows bug.
More information about this issue and solutions can be found [here](https://superuser.com/questions/951960/windows-7-sp1-windows-update-stuck-checking-for-updates).
## Dom0 and/or TemplateVM update stalls when updating via the GUI tool
## Dom0 and/or template update stalls when updating via the GUI tool
This can usually be fixed by updating via the command line.
In dom0, open a terminal and run `sudo qubes-dom0-update`.
Depending on your operating system, open a terminal in the TemplateVMs and run:
Depending on your operating system, open a terminal in the templates and run:
* Fedora: `sudo dnf upgrade`
* Debian: `apt-get update && apt-get dist-upgrade`

2
user/troubleshooting/updating-debian-and-whonix.md
View File

@ -9,7 +9,7 @@ title: Updating Debian and Whonix
Despite Qubes shipping with [Debian Templates](/doc/templates/debian/), most of Qubes core components run on Fedora and thus our documentation has better coverage for Fedora. However, Qubes has been working closely with the [Whonix](https://whonix.org) project which is based on Debian.
This troubleshooting guide is collection of tips about updating Whonix that also pertain to updating the normal Debian package manager. If you plan to use Debian heavily, **we highly recommend you install the Whonix templates and use them to update your normal Debian TemplateVM.**
This troubleshooting guide is collection of tips about updating Whonix that also pertain to updating the normal Debian package manager. If you plan to use Debian heavily, **we highly recommend you install the Whonix templates and use them to update your normal Debian template.**
*Note: some of the links on this page go to documentation on Whonix's website*

2
user/troubleshooting/usb-troubleshooting.md
View File

@ -101,7 +101,7 @@ If your computer has a PS/2 port, you may instead use a PS/2 keyboard to enter t
When trying to [create and use a USB qube](/doc/how-to-use-usb-devices/#creating-and-using-a-usb-qube) with the `qubes-usb-proxy` package, you may receive this error: `ERROR: qubes-usb-proxy not installed in the VM`.
If you encounter this error, you can install the `qubes-usb-proxy` with the package manager in the VM you want to attach the USB device to.
Depending on your operating system, open a terminal in the TemplateVM and enter one of the following commands:
Depending on your operating system, open a terminal in the template and enter one of the following commands:
- Fedora: `sudo dnf install qubes-usb-proxy`
- Debian/Ubuntu: `sudo apt-get install qubes-usb-proxy`

2
user/troubleshooting/vm-troubleshooting.md
View File

@ -76,7 +76,7 @@ Common reasons that may be revealed are: too low memory, corrupted files or a VM
If the error occurs as a result of too little initial memory, increase the initial memory from 200MB to 400MB by navigating to VM settings » Advanced » Initial memory.
## "No match found" when trying to install a TemplateVM
## "No match found" when trying to install a template
For example: