From e3dd623fb6036dd4a6e101cdf0325e27dd4270fb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Mon, 29 Jan 2018 15:21:34 +0100 Subject: [PATCH 1/4] Update DispVM customization guide for Qubes 4.0 --- customization/dispvm-customization.md | 66 ++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 7 deletions(-) diff --git a/customization/dispvm-customization.md b/customization/dispvm-customization.md index 8d4f8fed..a5435711 100644 --- a/customization/dispvm-customization.md +++ b/customization/dispvm-customization.md @@ -10,10 +10,64 @@ redirect_from: --- Disposable VM Customization -==================== +============================ -Changing the DVM Template -------------------------- +Qubes 4.0 +---------- + +Disposable VM in Qubes 4.0 can be based on any template-based AppVM. You can also choose to use different AppVMs for different Disposable VMs. To prepare AppVM to be a base for Disposable VM, you need to set `template_for_dispvms` property, for example: + + [user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True + +Additionally, if you want to have menu entries for starting applications in Disposable VM based on this AppVM (instead of in the AppVM itself), you can achieve it with `appmenus-dispvm` feature: + + [user@dom0 ~]$ qvm-features fedora-26-dvm appmenus-dispvm 1 + +### Creating new Disposable VM base AppVM ### + +You may want to use multiple AppVMs for different Disposable VMs. To create new one, lets say `custom-dvm`, based on `debian-9` template, use following commands: + + [user@dom0 ~]$ qvm-create --template debian-9 --label red custom-dvm + [user@dom0 ~]$ qvm-prefs custom-dvm template_for_dispvms True + [user@dom0 ~]$ qvm-features custom-dvm appmenus-dispvm 1 + +Additionally you may want to set it as default Disposable VM base: + + [user@dom0 ~]$ qubes-prefs default_dispvm custom-dvm + +The above default is used whenever a qube request starting a new Disposable VM 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/qrexec3/#extra-keywords-available-in-qubes-40-and-later) for details. + +If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization). + + +### Customization of Disposable VM ### + +It is possible to change the settings for each new Disposable VM (DispVM). This can be done by customizing the base AppVM: + +1. Start a terminal in the `fedora-26-dvm` qube (or another base for DispVM) by running the following command in a dom0 terminal. (If a qube have `appmenus-dispvm` feature set, there is no menu entry to start applications directly in it, instead of Disposable VM based on it). + + [user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal + +2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include: + - Changing Firefox's default startup settings and homepage. + - Changing Nautilus' default file preview settings. + - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVMs settings). This is useful if you sometimes wish to use a DispVM with a TorVM, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. + +4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal). + + +### Adding programs to Disposable VM Application Menu ### + +For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM. + +In order to do that, select "Qube settings" entry in selected base AppVM, go to "Applications" tab and select desired applications as for any other qube. + +Note that currently only applications whose main process keeps running until you close the application (i.e. do not start a background process instead) will work. One of known examples of incompatible applications is GNOME Terminal (shown on the list as "Terminal"). Choose different terminal emulator (like XTerm) instead. + +Qubes 3.2 +---------- + +### Changing the DVM Template ### You may want to use a non-default template the [DVM Template](/doc/glossary/#dvm-template). One example is to use a less-trusted template with some less trusted, third-party, often unsigned, applications installed, such as e.g. third-party printer drivers. @@ -37,8 +91,7 @@ One can easily verify if the new Disposable VM template is indeed based on a cus If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM Template" use case under [fedora-minimal customization](/doc/templates/fedora-minimal/#customization). -Customization of Disposable VM ------------------------------- +### Customization of Disposable VM ### It is possible to change the settings of each new Disposable VM (DispVM). This can be done by customizing the DispVM template: @@ -70,8 +123,7 @@ It is possible to change the settings of each new Disposable VM (DispVM). This c **Note:** All of the above requires at least qubes-core-vm \>= 2.1.2 installed in template. -Adding arbitrary programs to Disposable VM Application Menu ------------------------------------------------------------ +### Adding arbitrary programs to Disposable VM Application Menu ### For added convenience, arbitrary programs can be added to the Application Menu of the Disposable VM. In order to do that create (e.g.) `arbitrary.desktop` file in `/usr/local/share/applications` in Dom0. That file will point to the desired program. Use the following template for the file: From df53a71084c0a4ab3011a46c7846ab1f2814f312 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Mon, 5 Feb 2018 02:29:59 +0100 Subject: [PATCH 2/4] DispVM customization: clarifications Changes suggested by @andrewdavidwong --- customization/dispvm-customization.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/customization/dispvm-customization.md b/customization/dispvm-customization.md index a5435711..1f2f0cca 100644 --- a/customization/dispvm-customization.md +++ b/customization/dispvm-customization.md @@ -15,7 +15,7 @@ Disposable VM Customization Qubes 4.0 ---------- -Disposable VM in Qubes 4.0 can be based on any template-based AppVM. You can also choose to use different AppVMs for different Disposable VMs. To prepare AppVM to be a base for Disposable VM, you need to set `template_for_dispvms` property, for example: +Disposable VM in Qubes 4.0 can be based on any TemplateBasedVM. You can also choose to use different AppVMs for different Disposable VMs. To prepare AppVM to be a base for Disposable VM, you need to set `template_for_dispvms` property, for example: [user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True @@ -25,13 +25,14 @@ Additionally, if you want to have menu entries for starting applications in Disp ### Creating new Disposable VM base AppVM ### -You may want to use multiple AppVMs for different Disposable VMs. To create new one, lets say `custom-dvm`, based on `debian-9` template, use following commands: +In Qubes 4.0, you're no longer restricted to a single DVM Template. Instead, you can create as many as you want. Whenever you start a new Disposable VM, you can choose to base it on whichever DVM Template you like. +To create new DVM Template, lets say `custom-dvm`, based on `debian-9` template, use following commands: [user@dom0 ~]$ qvm-create --template debian-9 --label red custom-dvm [user@dom0 ~]$ qvm-prefs custom-dvm template_for_dispvms True [user@dom0 ~]$ qvm-features custom-dvm appmenus-dispvm 1 -Additionally you may want to set it as default Disposable VM base: +Additionally you may want to set it as default DVM Template: [user@dom0 ~]$ qubes-prefs default_dispvm custom-dvm @@ -51,7 +52,7 @@ It is possible to change the settings for each new Disposable VM (DispVM). This 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 Nautilus' default file preview settings. - - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVMs settings). This is useful if you sometimes wish to use a DispVM with a TorVM, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. + - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVMs settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. 4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal). @@ -103,7 +104,7 @@ It is possible to change the settings of each new Disposable VM (DispVM). This c 2. Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DispVM template, so any changes you make here will affect all DispVMs. Some examples of changes you may want to make include: - Changing Firefox's default startup settings and homepage. - Changing Nautilus' default file preview settings. - - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DispVM's settings). This is useful if you sometimes wish to use a DispVM with a TorVM, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. + - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVM's settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. 3. Create an empty `/home/user/.qubes-dispvm-customized` file in the VM (not in dom0): From f5a9711eadda60f83c34eba7a859552b7020d79d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Tue, 20 Feb 2018 21:16:53 +0100 Subject: [PATCH 3/4] DispVM customization: more clarifications --- customization/dispvm-customization.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/customization/dispvm-customization.md b/customization/dispvm-customization.md index 1f2f0cca..a6c3f220 100644 --- a/customization/dispvm-customization.md +++ b/customization/dispvm-customization.md @@ -15,7 +15,7 @@ Disposable VM Customization Qubes 4.0 ---------- -Disposable VM in Qubes 4.0 can be based on any TemplateBasedVM. You can also choose to use different AppVMs for different Disposable VMs. To prepare AppVM to be a base for Disposable VM, you need to set `template_for_dispvms` property, for example: +Disposable VM (DispVM) in Qubes 4.0 can be based on any TemplateBasedVM. You can also choose to use different AppVMs for different Disposable VMs. To prepare AppVM to be a base for Disposable VM, you need to set `template_for_dispvms` property, for example: [user@dom0 ~]$ qvm-prefs fedora-26-dvm template_for_dispvms True @@ -45,17 +45,17 @@ If you wish to use the `fedora-minimal` template as a DVM Template, see the "DVM It is possible to change the settings for each new Disposable VM (DispVM). This can be done by customizing the base AppVM: -1. Start a terminal in the `fedora-26-dvm` qube (or another base for DispVM) by running the following command in a dom0 terminal. (If a qube have `appmenus-dispvm` feature set, there is no menu entry to start applications directly in it, instead of Disposable VM based on it). +1. Start a terminal in the `fedora-26-dvm` qube (or another base for DispVM) 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 DispVM based on that VM (`fedora-26-dvm`). Not in that VM (`fedora-26-dvm`) itself). [user@dom0 ~]$ qvm-run -a fedora-26-dvm gnome-terminal 2. Change the qube's settings and/or applications, as desired. Some examples of changes you may want to make include: - Changing Firefox's default startup settings and homepage. - - Changing Nautilus' default file preview settings. + - Changing default editor, image viewer. - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVMs settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. 4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal). - + ### Adding programs to Disposable VM Application Menu ### From 1ddfd58a6d402a62c53ed1bc25b58ea41330f0b4 Mon Sep 17 00:00:00 2001 From: Andrew David Wong Date: Tue, 20 Feb 2018 23:42:38 -0600 Subject: [PATCH 4/4] Fix typos --- customization/dispvm-customization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/customization/dispvm-customization.md b/customization/dispvm-customization.md index a6c3f220..ee944ea7 100644 --- a/customization/dispvm-customization.md +++ b/customization/dispvm-customization.md @@ -52,7 +52,7 @@ It is possible to change the settings for each new Disposable VM (DispVM). This 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. - - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVMs settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. + - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DispVMs settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. 4. Shutdown the qube (either by `poweroff` from qube's terminal, or `qvm-shutdown` from dom0 terminal). @@ -104,7 +104,7 @@ It is possible to change the settings of each new Disposable VM (DispVM). This c 2. Change the VM's settings and/or applications, as desired. Note that currently Qubes supports exactly one DispVM template, so any changes you make here will affect all DispVMs. Some examples of changes you may want to make include: - Changing Firefox's default startup settings and homepage. - Changing Nautilus' default file preview settings. - - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DipsVM's settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. + - Changing the DispVM's default NetVM. For example, you may wish to set the NetVM to "none." Then, whenever you start a new DispVM, you can choose your desired ProxyVM manually (by changing the newly-started DispVM's settings). This is useful if you sometimes wish to use a DispVM with a Whonix Gateway, for example. It is also useful if you sometimes wish to open untrusted files in a network-disconnected DispVM. 3. Create an empty `/home/user/.qubes-dispvm-customized` file in the VM (not in dom0):