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

Mass replace "DisposableVM" with "disposable"

Browse Source 
QubesOS/qubes-issues#1015
This commit is contained in:
Andrew David Wong 2021-06-18 02:04:39 -07:00
parent aea595397f
commit c07ee61ed8
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
9 changed files with 278 additions and 277 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

127
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 [app qube](/doc/glossary/#app-qube).
You can also choose to use different [DisposableVM Templates](/doc/glossary/#disposablevm-template) for different DisposableVMs.
To prepare an app qube 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 app qube (instead of in the app qube 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 TemplateVM 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 TemplateVM](/doc/templates/minimal/) as a disposable template, please see the [Minimal TemplateVM](/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,13 +77,13 @@ 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 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.
@ -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 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:
@ -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
```

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

@ -244,7 +244,7 @@ optional arguments:
--targets TARGETS Coma separated list of VMs to target
--templates Target all templates
--app Target all app qubes
--all Target all non-disposable VMs (TemplateVMs and app qubes)
--all Target all non-disposables (TemplateVMs and app qubes)
```
To apply a state to all templates, call `qubesctl --templates state.highstate`.
@ -260,7 +260,7 @@ 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. App qubes inherit this property from their
parent TemplateVMs. If the value is not set explicitly, the default
@ -268,10 +268,10 @@ Beginning with Qubes 4.0 and after [QSB #45](/news/2018/12/03/qsb-45/), we imple
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
`management_dispvm`. Keep in mind that this disposable template has full control
over the VMs it's used to manage.
## Writing Your Own Configurations
@ -467,7 +467,7 @@ Vault app qube with no NetVM enabled.
#### `qvm.default-dispvm`
Default DisposableVM template - fedora-26-dvm app qube
Default disposable template - fedora-26-dvm app qube
#### `qvm.anon-whonix`
@ -475,7 +475,7 @@ Whonix workstation app qube.
#### `qvm.whonix-ws-dvm`
Whonix workstation app qube for Whonix DisposableVMs.
Whonix workstation app qube for Whonix disposables.
#### `qvm.updates-via-whonix`

2
user/advanced-topics/standalone-and-hvm.md
View File

@ -143,7 +143,7 @@ Set memory as appropriate, and install the OS into this template in the same way
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.

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

@ -91,20 +91,20 @@ Restore from your backup
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)
-----------------------------------------

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 TemplateVM.
### 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 [TemplateVM](/doc/glossary/#templatevm), 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 TemplateVM).
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 app qube, 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 app qubes.
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 app qubes 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 app qube 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 app qube 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 app qube that has also been configured as a DisposableVM Template to use itself, so DisposableVMs launched from within the app qube/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 app qube from which they were launched.
Therefore, launching a DisposableVM from an app qube will result in it using the network/firewall settings of the DisposableVM Template on which it is based.
For example, if an app qube uses sys-net as its NetVM, but the default system DisposableVM uses sys-whonix, any DisposableVM 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 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 app qube'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 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 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 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 DisposableVM.
## Starting an arbitrary program in a DisposableVM from an app qube
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 app qube 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/).

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

@ -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.

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

@ -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.

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

@ -78,7 +78,7 @@ If you only want to create a shortcut for a single app qube, you can create a cu
What about applications in DispVMs?
-----------------------------------
[See here](/doc/disposablevm-customization/).
[See here](/doc/disposable-customization/).
Fixing shortcuts
----------------