Merge branch 'custom-dispvm-40'

customization/dispvm-customization.md

@@ -10,10 +10,65 @@ redirect_from:
 ---
 
 Disposable VM Customization
-====================
+============================
 
-Changing the DVM Template
+Qubes 4.0
--------------------------
+----------
+
+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
+
+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 ###
+
+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 DVM Template:
+
+    [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 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 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 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).
+
+
+### 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 +92,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:
 
@@ -50,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 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):
 
@@ -70,8 +124,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: