Merge branch 'pr/1554'

conf.py

@@ -155,4 +155,8 @@ gettext_uuid = True
 rst_epilog = """
 .. |debian-codename| replace:: bookworm
 .. |debian-version| replace:: 12
+.. |qubes-logo-icon| image:: /attachment/icons/128x128/apps/qubes-logo-icon.png
+   :height: 1em
+   :class: no-scaled-link
+   :alt: Qubes logo icon
 """

developer/services/disposablevm-implementation.rst

@@ -2,73 +2,187 @@
 Disposable implementation
 =========================
 
+.. warning::
 
-**Note: The content below applies to Qubes R3.2.**
+      This page is intended for advanced users.
 
-DisposableVM image preparation
+Disposable behavior
-------------------------------
+-------------------
 
 
-DisposableVM is not started like other VMs, by executing equivalent of ``xl create`` - it would be too slow. Instead, DisposableVM are started by restore from a savefile.
+A :term:`disposable template` is not a disposable in itself, but a special template that can create different :term:`disposable` types, :term:`named disposable <named disposable>` and :term:`unnamed disposables <unnamed disposable>`. This intermediary template serves different functions, first to permit customization of the private volume of a disposable as well as well as a degree of inheritance that would not be possible with normal templates. It has the :py:attr:`template_for_dispvms <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin.template_for_dispvms>` property enabled, being a :py:class:`DVMTemplateMixin <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin>`.
 
-Preparing a savefile is done by ``/usr/lib/qubes/qubes_prepare_saved_domain.sh`` script. It takes two mandatory arguments, appvm name (APPVM) and the savefile name, and optional path to “prerun” script. The script executes the following steps:
+A :term:`disposable` is a qube with the :py:class:`DispVM <core-admin:qubes.vm.dispvm.DispVM>` class and is based on a disposable template. Every disposable type has all of its volumes configured to disable :py:attr:`save_on_stop <core-admin:qubes.storage.Volume.save_on_stop>`, therefore no changes are saved on shutdown. Unnamed disposables enables the property :py:attr:`auto_cleanup <core-admin:qubes.vm.dispvm.DispVM.auto_cleanup>` by default, thus automatically removes the qube upon shutdown. Named disposables don't enable :py:attr:`auto_cleanup <core-admin:qubes.vm.dispvm.DispVM.auto_cleanup>` by default, thus the qube skeleton is not removed upon shutdown, thus allowing to keep qube settings.
 
-1. APPVM is started by ``qvm-start``
+Named disposables are useful for service qubes, as referencing static names is easier when the qube name is mentioned on Qrexec policies (:file:`qubes.UpdatesProxy` target) or as a property of another qube, such as a disposable :term:`net qube` which is referenced by downstream clients in the ``netvm`` property.
 
-2. xenstore key ``/local/domain/appvm_domain_id/qubes_save_request`` is created
+Unnamed disposables have their names in the format :samp:`disp{1234}`, where :samp:`{1234}` is derived from the :py:attr:`dispid <core-admin:qubes.vm.dispvm.DispVM.dispid>` property, a random integer ranging from 0 to 9999 with a fail-safe mechanism to avoid reusing the same value in a short period.
-
-3. if prerun script was specified, copy it to ``qubes_save_script`` xenstore key
-
-4. wait for the ``qubes_used_mem`` key to appear
-
-5. (in APPVM) APPVM boots normally, up to the point in ``/etc/init.d/qubes_core`` script when the presence of ``qubes_save_request`` key is tested. If it exists, then
-
-   1. (in APPVM) if exists, prerun script is retrieved from the respective xenstore key and executed. This preloads filesystem cache with useful applications, so that they will start faster.
-
-   2. (in APPVM) the amount of used memory is stored to ``qubes_used_mem`` xenstore key
-
-   3. (in APPVM) busy-waiting for ``qubes_restore_complete`` xenstore key to appear
 
 
+Disposable's creation with Qrexec
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-6. when ``qubes_used_mem`` key appears, the domain memory is reduced to this amount, to make the savefile smaller.
+The system and every qube can have the :py:attr:`default_dispvm <core-admin:qubes.vm.dispvm.DispVM.default_dispvm>` property. This property can only have disposable template as value or an empty value. If the qube property is set to the default value, it will use the system's property. An exception to the rule is the property of disposables, which always default to their disposables templates to avoid data leaks such as using unintended network paths.
 
-7. APPVM private image is detached
+There are some Qrexec policy rules that have some services with allow resolution in case the target is the :doc:`@dispvm <core-qrexec:qrexec-policy>` tag, which translates to creation of disposables out of the :py:attr:`default_dispvm <core-admin:qubes.vm.dispvm.DispVM.default_dispvm>` property. It is most commonly used to open files and URLs, (:file:`qubes.OpenInVM` and :file:`qubes.OpenURL`, respectively).
 
-8. the domain is saved via ``xl save``
+It is also possible to write rules that would allow creating disposables out of different disposables templates by using as destination the disposable template name or a tag it has. The destination would be:
 
-9. the COW file volatile.img (cow for root fs and swap) is packed to ``saved_cows.tar`` archive
+- :samp:`@dispvm:{DISPOSABLE_TEMPLATE}`, where :samp:`{DISPOSABLE_TEMPLATE}` is the desired template;
+- :samp:`@dispvm:@tag:{CUSTOM_TAG}`, where :samp:`{CUSTOM_TAG}` is the tag of your choice.
+
+Preloaded disposables
+---------------------
 
 
+The user desires to circumvent any slow process, the creation of disposables fits into this category. Preloaded disposables enables fast retrieval of fresh disposables, so users don't have to get away from the computer or switch tasks when requesting disposables (or not requesting one at all because it was slow).
 
-The ``qubes_prepare_saved_domain.sh`` script is lowlevel. It is usually called by ``qvm-create-default-dvm`` script, that takes care of creating a special AppVM (named template_name-dvm) to be passed to ``qubes_prepare_saved_domain.sh``, as well as copying the savefile to /dev/shm (the latter action is not done if the ``/var/lib/qubes/dvmdata/dont_use_shm`` file exists).
+Preloaded disposables are :term:`unnamed disposables <unnamed disposable>`, it aims to solve the issue of disposable's long startup time by keeping running (powered on and paused) disposable qubes queued. In order to accomplish this, they are started in the background without user interaction, hidden from most graphical applications by being an :term:`internal <internal qube>`. They are unpaused (transparently) when a disposable qube is requested by the user, therefore the user must not worry about the managing the creation or deletion of them, just how many they'd like to have at maximum.
 
-Restoring a DisposableVM from the savefile
+Preloaded disposable's stages
-------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several stages a disposable goes through while preloading and being used. In short:
+
+1. **Preload**: The qube is created and marked as preloaded. Qube is not visible in GUI applications.
+
+  #. **Startup**: Begins qube startup, start basic services in it and attempt to pause.
+
+  #. **Request**: The qube is removed from the preload list. If startup has not yet reached pause, the latter is skipped.
+
+2. **Used**: The qube is marked as used and may be unpaused/resumed (if applicable). Only in this phase, GUI applications treat the qube as any other unnamed disposable and the qube object is returned to the caller if requested.
+
+Preloaded disposable's worry-free life-cycle
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-Normally, disposable VM is created when qubes rpc request with target *$dispvm* is received. Then, as a part of rpc connection setup, the ``qfile-daemon-dvm`` program is executed; it executes ``/usr/lib/qubes/qubes_restore`` program. It is crucial that this program executes quickly, to make DisposableVM creation overhead bearable for the user. Its main steps are:
+There are several events that may trigger the creation, deletion of preloaded disposables. If there is a gap between the current number of preloaded disposables and the maximum number allowed, it will be capped *event*\ ually (refill), if the qube is at an invalid state, it will be deleted or replaced (refresh) as soon as possible.
 
-1. modify the savefile so that the VM name, VM UUID, MAC address and IP address are unique
+We cannot prevent all gaps at the moment it occurs and users should not be responsible for filling them, the system must manage to fill gaps when possible.
 
-2. restore the COW files from the ``saved_cows.tar``
+Preloaded disposable's management
-
+"""""""""""""""""""""""""""""""""
-3. create the ``/var/run/qubes/fast_block_attach`` file, whose presence tells the ``/etc/xen/scripts/block`` script to bypass some redundant checks and execute as fast as possible.
-
-4. execute ``xl restore`` in order to restore a domain.
-
-5. create the same xenstore keys as normally created when AppVM boots (e.g. ``qubes_ip``)
-
-6. create the ``qubes_restore_complete`` xenstore key. This allows the boot process in DisposableVM to continue.
 
 
+These are common events that trigger changes in preloaded disposables quantity:
 
-The actual passing of files between AppVM and a DisposableVM is implemented via qubes rpc.
+- Setting or deleting the ``preload-dispvm-max`` feature will refill or remove;
+- (Re)starting :file:`qubes-preload-dispvm.service` will refresh;
+- Using a preloaded disposable will refill;
+- Requesting a disposable will refill;
+- Updating the volumes of a template or disposable template will refresh;
+- Changing system's :py:attr:`default_dispvm <core-admin:qubes.vm.dispvm.DispVM.default_dispvm>` while system's feature is set to a different value than the disposable template setting will refill or remove; and
+- Qubesd was interrupted mid preload creation, on the next service restart, :py:meth:`domain-load <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin.on_domain_loaded>` of the disposable template will refresh the incomplete disposables.
 
-Validating the DisposableVM savefile
+Preloaded disposable's temporary gaps
-------------------------------------
+"""""""""""""""""""""""""""""""""""""
 
 
-DisposableVM savefile contains references to template rootfs and to COW files. The COW files are restored before each DisposableVM start, so they cannot change. On the other hand, if templateVM is started, the template rootfs will change, and it may not be coherent with the COW files.
+Some rarer events that may cause a gap in preloaded disposables temporarily:
 
-Therefore, the check for template rootfs modification time being older than DisposableVM savefile modification time is required. It is done in ``qfilexchgd`` daemon, just before restoring DisposableVM. If necessary, an attempt is made to recreate the DisposableVM savefile, using the last template used (or default template, if run for the first time) and the default prerun script, residing at ``/var/lib/qubes/vm-templates/templatename/dispvm_prerun.sh``. Unfortunately, the prerun script takes a lot of time to execute - therefore, after template rootfs modification, the next DisposableVM creation can be longer by about 2.5 minutes.
+- There is not enough memory to preload at the moment, won't create the qube; and
+- Service to check if the system is fully operational has failed and will remove the qube. Should not attempt refill as it most likely would lead to the same outcome to infinity.
+
+Preloaded disposable's bootstrap
+""""""""""""""""""""""""""""""""
+
+
+To bootstrap the creation of preloaded disposables after boot, the service :file:`qubes-preload-dispvm.service` is used instead of :py:meth:`domain-load <core-admin:qubes.vm.mix.dvmtemplate.DVMTemplateMixin.on_domain_loaded>` of the disposable template because it relies on systemd to:
+
+- Order this action after the autostart or standard qubes, they must precede in order to have a functional system;
+- Skip preloading if kernel command line prevents autostart.
+
+Preloaded disposable's memory management
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+At the end of preloading, it attempts to manage memory of the qube right before pause, because it is not possible to negotiate memory with the domain after pause. It attempts to retrieve memory from the qube on :py:meth:`domain-pre-paused <core-admin:qubes.vm.dispvm.DispVM.on_domain_pre_paused>` by setting it to use its preferred memory value. In :doc:`qmemman terms </developer/services/qmemman>`, preferred memory is just enough to have the qube running.
+
+This process can take a bit of time because it depends on how fast the qube can free up memory. In ``qubes.qmemman.systemstate``, there is a timeout (``CHECK_PERIOD``) and a threshold in transfer speed (``CHECK_MB_S``) when attempting to balloon, then, when both of these conditions are met, the memory management seizes and the preloaded disposable is paused.
+
+Although it takes some time, increasing the preload creation stage, we do not worry much about it because it economizes memory on the long run, the biggest problems is that qmemman is synchronous, so only one request can be made at a time, anything that takes too much time on qmemman could prevent ballooning/balancing of other qubes on the system.
+
+Preloaded disposable's pause
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Preloaded disposables are paused for various reasons:
+
+- Detection if the qube was used without being requested with :py:meth:`core-admin:qubes.vm.dispvm.DispVM.from_appvm`. Not every communication with a qube goes through :program:`qubesd`, it may go via Qrexec or GUI daemon;
+- CPU scheduling economy, domain is not eligible; and
+- Cronjob, timers and other things that don't block the init system and service manager completion won't run, they could possibly alter a clean state.
+
+But this comes at a cost:
+
+- Can only connect to the GUI after the qube is requested (longer run time), else, if `early GUI connection was made before the qube is paused <https://github.com/qubesos/qubes-issues/issues/9940>`__:
+
+  - Events such as screen resize by plugging or removing external monitors can't work;
+  - No easy way to hide autostarted applications, depends on qube collaboration;
+  - Can only preload after GUI login to be able to establish a connection;
+  - Can't survive GUI login and logout as the connection might change;
+
+- Memory management before pause may take some seconds, that is not prejudicial to the time to use the qube but it is prejudicial to the system as :doc:`qmemman </developer/services/qmemman>` can not balloon/balance other qubes in the mean time due to its design.
+
+Preloaded disposable's security
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+As preloaded disposables are started before being used, methods to prevent accidental tampering have been put in place as well as guarantees to prevent reuse:
+
+- The qube has the ``internal`` feature enabled, Qubes GUI applications were patched to hide and show :term:`internal qubes<internal qube>` by handling events for ``domain-feature-((pre-)?set|delete):internal``;
+- When requesting an unnamed disposable, the qube object is only returned to the user once it has finished preloading;
+- The qube is paused as the last stage of preloading, this permits receiving :py:meth:`domain-unpaused <core-admin:qubes.vm.dispvm.DispVM.on_domain_unpaused>` event and be notified that the qube was used, marked as such and removed from the preload list to avoid reuse, even without the qube being requested with :py:meth:`core-admin:qubes.vm.dispvm.DispVM.from_appvm`;
+- The GUID only connects to the GUI agent on the qube after the preloaded disposable is marked as used, this prevents that an autostarted application such as a terminal appears on the screen before preloading has finished. Enabling a GUI is is controlled by the :py:attr:`is_preload <core-admin:qubes.vm.dispvm.DispVM.is_preload>` property, that when disabled, allows the GUI connection to initiate. This method delays GUI calls considerably as establishing the connection can take ~2 seconds, research is being done to prevent this delay.
+
+Another point of security is reliability:
+
+- The ``preload-dispvm-threshold`` feature controls how much free memory must be present on the system before attempting to create a new preloaded disposable. Used to ensure preloaded disposables do not consume all available memory, which would prevent starting other qubes.
+
+Alternatives considered
+^^^^^^^^^^^^^^^^^^^^^^^
+
+
+For an alternative to be considered for implementation, it must meet the following requirements:
+
+- No memory or ``vcpus`` restrictions such as limiting to a few number of ``vcpus`` or assigns memory on request (can be slow).
+- Performant as much as a normal disposable even on long running sessions;
+- Caller transparency, no change necessary for callers, the request must be transparent and the server must find the fastest option. This is to avoid transition burden (API breakage).
+
+From the evaluated options, only :ref:`preload queue <developer/services/disposablevm-implementation:preload queue>` meets all requirements.
+
+
+Restoration from savefile
+"""""""""""""""""""""""""
+
+
+**Description**: Disposable template booted, its image was dumped (suspend to disk), newly disposables would restore this image to become their own.
+
+**Evaluation**:
+
+- Used in R3.2, worked at that time, when there was only one disposable template available, see next points of why it can't be used anymore.
+- Incompatible with multiple ``vcpus``.
+- Some memory issues.
+- Savefile creation takes a long time. The disposable qube savefile contains references to template rootfs and :abbr:`CoW (Copy-on-Write)` files, if there is a modification on the template or disposable template, it took longer than 2.5 minutes to generate the next disposable.
+
+Xen domain fork
+"""""""""""""""
+
+
+**Description**: domain forking is the process of creating a domain with an empty memory space and a parent domain specified from which to populate the memory when necessary. For the new domain to be functional the domain state is copied over as part of the fork operation (HVM params, heap allocation etc). This description was sourced from `[Xen-devel] [RFC PATCH for-next 17/18] xen/mem_sharing: VM forking, Tamas K Lengyel <https://lists.xenproject.org/archives/html/xen-devel/2019-09/msg02497.html>`__.
+
+**Evaluation**:
+
+- Shares too much information from the trunk to the forks. This appears to have improved if not totally fixed on Linux 6.14, as mentioned by Andrew Cooper on Qubes OS Summit 2025;
+- Requires changing properties after the fork is done, this includes, but not limited to, ``xid`` of connected qubes, network uplink;
+- Not designed for long running sessions, the initial intention was fuzzing. As fast as the creation can be, the usage may be slower as memory is mapped on request. Xen doesn't have a poper :abbr:`CoW (Copy-on-Write)` support for domain memory, so making a full copy of a domain on fork also has some overhead;
+- Tamas K Lengyiel `VM Forking & Hypervisor-Based Fuzzing with Xen <https://www.youtube.com/watch?v=3MYo8ctD_aU>`__ presentation during the Open Source Summit Europe in 2022, showed impressive results on CPU i5-8350U, an average of time of 0.745 ms per fork (created 1300 VM/s). These fast results were later explained that was due to not initializing the whole VM memory on the fork unless it was requested, as explained on the point above. Still impressive results but current usage is limited to fuzzing.
+
+Preload queue
+"""""""""""""
+
+
+**Description**: Start disposables and queue them in a disposable template feature, unnamed disposables requested will prefer to retrieve disposables from this list.
+
+**Evaluation**:
+
+- Because the qube is running prior to being requested, multiple components have to be patched to support it to various levels off difficulty. Excluding from backups to allowing removal of disposable templates that only have preloaded disposables to even stranger issues such as deferring net qube change from a preloaded disposable where the old net qube has already been purged from the system.
+- The biggest difference between the queue and the other alternatives is that this solution works, is reliable and fulfills all requirements. A proper solution would be patching upstream Xen to implement :abbr:`CoW (Copy-on-Write)`, but that would involve a lot more work than what the Qubes Team can provide with current resources.

introduction/getting-started.rst

@@ -73,7 +73,7 @@ Qube Manager
 
 To see all of your qubes at the same time, you can use the **Qube Manager**. It displays the states of all the qubes in your system, even the ones that aren’t running.
 
-To access Qube Manager go to: Qubes Icon (App Menu) → Settings Icon → Qubes Tools → **Qube Manager**
+To access Qube Manager go to |qubes-logo-icon|:menuselection:`App Menu (Q icon) --> Settings (icon) --> Qubes Tools --> Qube Manager`
 
 |r4.1-qubes-manager.png|
 
@@ -81,9 +81,9 @@ Command-line interface
 ^^^^^^^^^^^^^^^^^^^^^^
 
 
-All aspects of Qubes OS can be controlled using command-line tools such as the terminal emulator. The default terminal emulator in Qubes is Xfce Terminal. Opening a terminal emulator in dom0 can be done in several ways:
+All aspects of Qubes OS can be controlled using command-line tools such as the terminal emulator. The default terminal emulator in Qubes is Xfce Terminal. Opening a terminal emulator in :term:`dom0` can be done in several ways:
 
-- Go to the App Menu, click on the Settings icon, choose Other from the drop-down menu, and select **Xfce Terminal Emulator** at the bottom.
+- Using the application menu: |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> Settings (icon) --> Other --> Xfce Terminal`.
 
 - Press ``Alt`` + ``F3`` and search for ``xfce terminal``.
 
@@ -117,17 +117,19 @@ Adding, removing, and listing qubes
 
 To create a new qube or remove one, use **Create Qubes VM** option in the App Menu.
 
-Creating a New Qube: Qubes Icon → Settings → Qubes Tools → Qube Manager → Create Qubes VM → **New Qube**
+Creating a new qube, |qubes-logo-icon|:menuselection:`App Menu (Q icon) --> Settings (icon) --> Qubes Tools --> Create New Qube`.
 
-Removing a qube: To remove a qube, use the **Delete qube button** as the final step instead.
+To remove a qube, |qubes-logo-icon|:menuselection:`App Menu (Q icon) --> <QUBE> --> Settings --> Delete qube`, where :samp:`{<QUBE>}` is the qube you desire to delete.
+
+To list qubes, use the :ref:`Qube Manager <introduction/getting-started:qube manager>`.
 
 You can also add, remove, and list qubes from the command line using the following tools:
 
-- ``qvm-create``
+- :program:`qvm-create`
 
-- ``qvm-remove``
+- :program:`qvm-remove`
 
-- ``qvm-ls``
+- :program:`qvm-ls`
 
 
 

introduction/screenshots.rst

@@ -53,7 +53,7 @@ Here we see Xfce4.14 Window Manager running in Dom0 (instead of KDE as on previo
 
 |r4.0-password-prompt.png|
 
-It is always clearly visible to which domain a given window belongs. Here it’s immediately clear that the passphrase-prompting window belongs to some domain with the “blue” label. When we look at the titlebar, we see “[qubes]”, which is the name of the actual domain. Theoretically, the untrusted application (here, the red Tor Browser running in a DisposableVM) beneath the prompt window could draw a similar looking window within its contents. In practice, this would be very hard, because it doesn’t know, e.g., the exact decoration style that is in use. However, if this is a concern, the user can simply try to move the more trusted window onto some empty space on the desktop such that no other window is present beneath it. Or, better yet, use the Expose-like effect (available via a hot-key). A malicious application from an untrusted domain cannot spoof the whole desktop because the trusted Window Manager will never let any domain “own” the whole screen. Its titlebar will always be visible.
+It is always clearly visible to which domain a given window belongs. Here it’s immediately clear that the passphrase-prompting window belongs to some domain with the “blue” label. When we look at the titlebar, we see “[qubes]”, which is the name of the actual domain. Theoretically, the untrusted application (here, the red Tor Browser running in a :term:`disposable`) beneath the prompt window could draw a similar looking window within its contents. In practice, this would be very hard, because it doesn’t know, e.g., the exact decoration style that is in use. However, if this is a concern, the user can simply try to move the more trusted window onto some empty space on the desktop such that no other window is present beneath it. Or, better yet, use the Expose-like effect (available via a hot-key). A malicious application from an untrusted domain cannot spoof the whole desktop because the trusted Window Manager will never let any domain “own” the whole screen. Its titlebar will always be visible.
 
 
 ----
@@ -91,7 +91,7 @@ Qubes supports secure copy-and-paste operations between AppVMs. Only the user ca
 ----
 
 
-|“r4.0-copy-to-other-appvm-1.png| |r4.0-copy-to-other-appvm-3.png|
+|r4.0-copy-to-other-appvm-1.png| |r4.0-copy-to-other-appvm-3.png|
 
 Qubes also supports secure file copying between AppVMs.
 
@@ -99,10 +99,9 @@ Qubes also supports secure file copying between AppVMs.
 ----
 
 
-|r4.0-open-in-dispvm-1.png| |r4.0-open-in-dispvm-2.png|
+|r4.3-domU-filemanager-disp-pdfviewer.png| |r4.3-domU-filemanager-disp-pdfviewer-open.png|
-
-Qubes’ unique DisposableVMs (DispVMs) allow the user to open any file in a disposable VM in a matter of seconds! A file can be edited in a disposable VM, and any changes are projected back onto the original file. Currently, there is no way to mark files to be automatically opened in a disposable VM (one needs to right-click on the file and choose the “View in DisposableVM” or “Edit in DisposableVM” option), but this is planned for the R2 Beta 3 release.
 
+Qubes' unique :term:`disposable` qubes allow the user to open any file in a disposable VM in a matter of seconds! A file can be edited in a disposable qube, and any changes are projected back onto the original file.
 
 ----
 
@@ -140,10 +139,10 @@ And some more screenshots:
 .. |r4.0-manager-and-sysnet-network-prompt.png| image:: /attachment/doc/r4.0-manager-and-sysnet-network-prompt.png
 .. |r4.0-software-update.png| image:: /attachment/doc/r4.0-software-update.png
 .. |r4.0-copy-paste.png| image:: /attachment/doc/r4.0-copy-paste.png
-.. |“r4.0-copy-to-other-appvm-1.png| image:: /attachment/doc/r4.0-copy-to-other-appvm-1.png
+.. |r4.0-copy-to-other-appvm-1.png| image:: /attachment/doc/r4.0-copy-to-other-appvm-1.png
 .. |r4.0-copy-to-other-appvm-3.png| image:: /attachment/doc/r4.0-copy-to-other-appvm-2.png
-.. |r4.0-open-in-dispvm-1.png| image:: /attachment/doc/r4.0-open-in-dispvm-1.png
+.. |r4.3-domU-filemanager-disp-pdfviewer.png| image:: /attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png
-.. |r4.0-open-in-dispvm-2.png| image:: /attachment/doc/r4.0-open-in-dispvm-2.png
+.. |r4.3-domU-filemanager-disp-pdfviewer-open.png| image:: /attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png
 .. |r4.0-convert-to-trusted-pdf-1.png| image:: /attachment/doc/r4.0-convert-to-trusted-pdf-1.png
 .. |r4.1-converting-pdf.png| image:: /attachment/doc/r4.1-converting-pdf.png
 .. |r4.0-manager-firewall.png| image:: /attachment/doc/r4.0-manager-firewall.png

user/advanced-topics/disposable-customization.rst

@@ -10,132 +10,353 @@ Introduction
 ------------
 
 
-A :doc:`disposable </user/how-to-guides/how-to-use-disposables>` can be based on any :term:`app qube`. You can also choose to use different :term:`disposable templates <disposable template>` for different disposables. To prepare an app qube to be a disposable template, you need to set the ``template_for_dispvms`` property:
+A :doc:`disposable </user/how-to-guides/how-to-use-disposables>` can be based on any :term:`disposable template`. You can have as many disposables or disposable templates as you'd like. This page contains information on advanced methods to use disposables, how to customize them, how to deal with multiple disposable templates and how to delete them.
 
-.. code:: console
-
-      [user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
-
-
-Additionally, if you want to have menu entries for starting applications in disposables based on this app qube (instead of in the app qube itself), you can achieve that with the ``appmenus-dispvm`` feature:
-
-.. code:: console
-
-      [user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
-
-
-**Note:** Application shortcuts that existed before setting this feature will not be updated automatically. Please go the “Applications” tab in the qube’s “Settings” dialog and unselect all existing shortcuts by clicking “«”, then click “OK” and close the dialog. Give it a few seconds time and then reopen and re-select all the shortcuts you want to see in the menu. See :doc:`this page </user/troubleshooting/app-menu-shortcut-troubleshooting>` for background information.
 
 Security
 --------
 
 
-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 disposable template on a trusted template and refrain from making any risky customizations to it.
+If a disposable template becomes compromised, then any disposable based on that disposable template could be compromised. Therefore, you should not make any risky customization (e.g., installing untrusted browser plugins) in important disposable templates. In particular, the *default* disposable template is important because it is used by most app qubes. This means that a compromised disposable template, could be used to derive disposables that will have access to everything that you choose to open in a disposable. For this reason, it is strongly recommended that you base the default disposable template on a trusted template and refrain from making any risky customization to it.
 
-Creating a new disposable template
+Disposables and local forensics
-----------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-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 a new disposable template:
+At this time, disposables should not be relied upon to circumvent local forensics, as they `do not run entirely in RAM <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.net>`__ on bare-metal, as using Tails on a `qube cannot be relied on for amnesiac purposes <https://tails.net/doc/advanced_topics/virtualization/index.en.html#index2h1>`__.
 
-.. code:: console
+Disposables settings inheritance
-
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-      [user@dom0 ~]$ qvm-create --template <TEMPLATE> --label red <DISPOSABLE_TEMPLATE>
-      [user@dom0 ~]$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
-      [user@dom0 ~]$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
 
 
-Optionally, set it as the default disposable template:
+Similarly to how app qubes are based on their underlying :term:`template`, disposables are based on their underlying :term:`disposable template`.
 
-.. code:: console
+By default, a disposable will inherit the network and firewall settings of the disposable template on which it is based. 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 net qube, but the default system disposable uses ``sys-whonix``, any disposable launched from this app qube will have ``sys-whonix`` as its net qube.
 
-      [user@dom0 ~]$ qubes-prefs default_dispvm <DISPOSABLE_TEMPLATE>
+.. warning:: Changing the net qube setting for the system's default disposable template *does* affect the net qube of its new disposables. Different disposable templates with individual net qube settings can be added to the app menu.
 
+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. This is recommended to avoid sharing too much information about your system, as inhering the same configuration means it helps prevent network leaks. For example, ``anon-whonix`` has its ``default_dispvm`` a Whonix-Workstation qube such as :samp:`whonix-workstation-{12}-dvm` (where :samp:`{12}` is the template's release number), instead of the system default. This ensures that all traffic goes through the intended network chain.
 
-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 :ref:`qrexec documentation <developer/services/qrexec:specifying vms: tags, types, targets, etc.>` for details.
+.. warning:: The opposite is also true. If you have changed ``anon-whonix``'s ``default_dispvm`` to use the system default, and the system default disposable template uses ``sys-net``, launching a disposable from inside ``anon-whonix`` will result in the disposable using ``sys-net``.
 
-If you wish to use a :doc:`minimal template </user/templates/minimal-templates>` as a disposable template, please see the :doc:`minimal template </user/templates/minimal-templates>` page.
+Advanced disposable's usage
-
-Customization of disposable
 ---------------------------
 
 
-**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>`__ *.*
+Open an program in a disposable via command line (from app qube)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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 ``<DISPOSABLE_TEMPLATE>`` 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 (``<DISPOSABLE_TEMPLATE>``) will be “Disposable: ” (instead of “Domain: ”) and entries there will start new disposable based on that VM (``<DISPOSABLE_TEMPLATE>``). Not in that VM (``<DISPOSABLE_TEMPLATE>``) itself).
+Sometimes it can be useful to start an arbitrary program in a disposable. This can be done from an app qube with :program:`qvm-run-vm`:
+
+.. code:: console
+
+      [user@work ~]$ qvm-run-vm -- '@dispvm' qubes-run-terminal
+
+The ``work`` qube default disposable template derives a disposable to execute the program.
+
+Open a link in a disposable based on a non-default disposable template via command line (from app qube)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Suppose that you have a qube named ``email`` and its default disposable template ``email-dvm`` 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, such as ``net-dvm``
+
+Open the :doc:`user policy </user/how-to-guides/how-to-edit-a-policy>` and insert the following rule:
+
+.. code:: text
+
+      # SERVICE      ARGUMENT  FROM   TO               ACTION
+      qubes.OpenURL  *         email  @dispvm:net-dvm  allow
+
+The line above means:
+
+- SERVICE: ``Open URL`` request from ``Qubes`` vendor.
+
+- ARGUMENT: Any argument is allowed.
+
+- FROM: ``email`` qube.
+
+- TO: A disposable based on the disposable template ``net-dvm``.
+
+- ACTION: Allow action to proceed.
+
+In other words, the ``email`` qube will be allowed to create a new disposable based on ``net-dvm`` and open a URL inside of that disposable. For more information about Qrexec usage, checkout :ref:`the policy directives <developer/services/qrexec:specifying vms: tags, types, targets, etc.>`.
+
+To check if everything is working as expected, from the ``email`` qube with :program:`qvm-open-in-vm`:
+
+.. code:: console
+
+      [user@email ~] $ qvm-open-in-vm -- '@dispvm:net-dvm' 'https://www.qubes-os.org'
+
+The ``email`` qube requests to open an URL in a non default disposable template ``net-dvm``, which will derive a disposable and navigate to the link.
+
+Make a particular application open everything in a disposable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+You can enable a :ref:`qube service <user/how-to-guides/how-to-enable-a-service:how to enable a qube service>` to cause an application in a qube to open files and URLs in a disposable. In order to accomplish this, enable a service named :samp:`app-dispvm.{X}` in that qube, where :samp:`{X}` is the application ID, which is the application name minus the :file:`.desktop` extension.
+
+For instance, to have Mozilla Thunderbird application open all attachments in a disposable, find its application name with |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> TEMPLATES --> <DISPOSABLE_TEMPLATE> --> Settings --> Applications`, hover your mouse over the application to see the ``.desktop filename``. Or use the command line equivalent:
+
+.. code:: console
+
+      qvm-appmenus --get-available --i-understand-format-is-unstable <QUBE> | grep -i thunderbird
+
+In the current case, we identified the application ID to be ``net.thunderbird.Thunderbird`` (in your case it may as well be ``thunderbird``). Finally, enable the ``app-dispvm.net.thunderbird.Thunderbird`` service via the :ref:`qube settings <user/how-to-guides/how-to-enable-a-service:how to enable a service in the settings>`.
+
+.. warning:: This feature is currently somewhat experimental, and only works for Linux qubes. It is known to work with Thunderbird and Wire, but it may fail to work with some applications that do not honor all XDG environment variables. If the feature does not work for you, please file a bug report.
+
+Open a particular file type in a disposable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+You can set :file:`qvm-open-in-dvm.desktop` as the handler for a given MIME type (such as :mimetype:`application/pdf`). This will cause all files of that type to open in a disposable. This works in disposable templates too, but be careful: if your disposable template is set to use :file:`qvm-open-in-dvm.desktop` to open a certain kind of file, every disposable based on it will be as well.
+
+.. warning:: If the disposable template is its own default disposable template (as is often the case), this will result in a loop: :program:`qvm-open-in-dvm` will attempt to execute :program:`qubes.OpenURL` in a new disposable, but that will in turn execute :program:`qvm-open-in-dvm`. A question dialog will appear to confirm if this is the intended behavior or not.
+
+This will *not* override the internal handling of PDF documents in Web browsers. This is typically okay, though, in-browser PDF viewers have a fairly good security record, especially when compared to non-browser PDF viewers. In particular, the attack surface of PDF viewing in Firefox is usually less than that of viewing an ordinary Web page.
+
+Set the default disposable template
+-----------------------------------
+
+
+Set the system's default disposable template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+The system's default disposable template can be configured in |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> Settings (icon) --> Qubes Tools --> Qubes Global Config --> General --> Default disposable template`, choose to your liking and click :guilabel:`Apply Changes and Close`.
+
+.. image:: /attachment/doc/r4.3-disp-default-global.png
+   :alt: Global config window with system's default disposable template item emphasized.
+
+
+This can also be changed from the command line with with :program:`qubes-prefs`:
+
+.. code:: console
+
+      user@dom0:~$ qubes-prefs default_dispvm <DISPOSABLE_TEMPLATE>
+
+The above setting is used whenever a qube has the property ``default_dispvm`` set to default, request starting a new disposable and do not specify which one, for example, via file manager context menu :guilabel:`Edit/View in disposable qube` or :program:`qvm-open-in-dvm` tool), also with :guilabel:`Convert in disposable qube` (:program:`qvm-convert-img`, :program:`qvm-convert-pdf`).
+
+Set the qube's default disposable template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+The per qube default disposable template can be configured in the app menu, for example, to change the setting for the ``work`` qube, in |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> work --> Settings --> Advanced --> Default disposable template`, select your preference and click :guilabel:`&OK` to apply the changes and close the window.
+
+.. image:: /attachment/doc/r4.3-disp-default-local.png
+   :alt: Qube settings of ``work`` with qube's default disposable template item emphasized.
+
+This can also be changed from the command line with :program:`qvm-prefs`:
+
+.. code:: console
+
+      user@dom0:~$ qvm-prefs work default_dispvm <DISPOSABLE_TEMPLATE>
+
+A qube can be allowed to use :ref:`multiple disposable templates <user/advanced-topics/disposable-customization:open a link in a disposable based on a non-default disposable template via command line (from app qube)>` if you choose so and have configured the :ref:`policy to allow <developer/services/qrexec:specifying vms: tags, types, targets, etc.>`.
+
+Customize a disposable
+----------------------
+
+
+.. warning:: 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>`__ instead.
+
+Change qube settings
+^^^^^^^^^^^^^^^^^^^^
+
+
+It is possible to change the disposable settings just like any other qube. You might, for example, want to disable all networking for the specific disposable template by default, which can be done by setting the net qube to ``none``. Then, whenever you start a new disposable, you can choose your desired net qube manually by changing the newly-started disposable's settings.
+
+Add programs to the app menu
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+For added convenience, arbitrary programs can be added to the app menu of the disposable template :ref:`just like for any other qube <user/troubleshooting/app-menu-shortcut-troubleshooting:How-to add a shortcut>`.
+
+In order to do that, go to |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> TEMPLATES --> <DISPOSABLE_TEMPLATE> --> Settings --> Applications` and select desired applications as for any other qube.
+
+Only applications whose :ref:`main process keeps running until you close the application <user/how-to-guides/how-to-use-disposables:call to the application succeeds but disposable exits too soon>` will work.
+
+Change application settings manually
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+It is also possible to change application settings of a disposable by customizing the disposable template:
+
+1. Start a terminal (or your chosen application) in the :samp:`{<DISPOSABLE_TEMPLATE>}` qube with |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> TEMPLATES --> <DISPOSABLE_TEMPLATE> --> Run Terminal` or by running the following command in a :term:`GUI domain`:
 
    .. code:: console
 
-         [user@dom0 ~]$ qvm-run -a <DISPOSABLE_TEMPLATE> gnome-terminal
+         user@dom0:~$ qvm-run --service -- <DISPOSABLE_TEMPLATE> qubes.StartApp+qubes-run-terminal
+
+2. Change the applications settings, as desired. Some examples of changes you may want to make include:
+
+   - Firefox's default startup settings and homepage.
+
+   - Default editor, image viewer. In Debian derivatives, this can be done with the :program:`mimeopen` command.
+
+3. Shutdown the qube, either with Qubes Domains widget, |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> TEMPLATES --> <DISPOSABLE_TEMPLATE> --> Shutdown`, :program:`qvm-shutdown` from the :term:`GUI domain` terminal or with :program:`poweroff` from qube's terminal.
+
+Change application settings dynamically
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-2. Change the qube’s settings and/or applications, as desired. Some examples of changes you may want to make include:
+It is possible to specify data from the :term:`GUI domain` to be read inside the qube using :doc:`vm-config.* features <core-admin-client:manpages/qvm-features>`. This is useful to pass secrets to a single qube instead of writing to the disposable template, which would be shared with all descendants of it.
 
-   - Changing Firefox’s default startup settings and homepage.
+Let's take for example ``sys-net``, which could be a disposable if you enabled that option during installation. In that case, it's template is ``default-dvm``, but that is also the template of unnamed disposables that launch applications which you don't trust. It would be improper to write the Wi-Fi password to ``default-dvm``, as it would expose it to numerous qubes. Instead, write the data as a qube feature using the :samp:`vm-config.{X}` syntax, where :samp:`{X}` is any valid identification string you'd like.
 
-   - Changing default editor, image viewer. In Debian-based templates this can be done with the ``mimeopen`` command.
+.. note:: It is up to each qube to handle these entries. In this case, :program:`nmcli` command should be called from somewhere during qube startup to configure the network, it is up to the user to manage it.
 
-   - 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.
+From the :term:`GUI domain`:
+
+.. code:: console
+
+      user@dom0:~$ qvm-features sys-net vm-config.wifi-ssid <SSID>
+      user@dom0:~$ qvm-features sys-net vm-config.wifi-pass <PASSWORD>
+
+From the configured qube, ``sys-net``:
+
+.. code:: console
+
+      [user@sys-net ~] $ qubesdb-read /vm-config/wifi-ssid
+      [user@sys-net ~] $ qubesdb-read /vm-config/wifi-pass
+
+Create a new disposable template
+--------------------------------
 
 
+You can create as many disposable templates as you want. First, you need to :ref:`create an app qube <introduction/getting-started:adding, removing, and listing qubes>`.
 
-3. Shutdown the qube (either by ``poweroff`` from qube’s terminal, or ``qvm-shutdown`` from dom0 terminal).
+Next, go to |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> <DISPOSABLE_TEMPLATE> --> Settings --> Advanced --> Disposable template` and enable it, at last, click on :guilabel:`&OK` to accept the changes and close the window. To modify settings of the disposable template itself or how programs are run on it, use the :guilabel:`TEMPLATES` tab.
+
+You can also use the command line equivalent:
+
+.. code:: console
+
+      user@dom0:~$ qvm-create --template <TEMPLATE> --label red <DISPOSABLE_TEMPLATE>
+      user@dom0:~$ qvm-prefs <DISPOSABLE_TEMPLATE> template_for_dispvms True
+      user@dom0:~$ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
+
+The ``appmenus-dispvm`` feature is only necessary if you intend to launch unnamed disposables derived from this disposable template via graphical applications. When enabled, new entries will be available for each application in |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> <DISPOSABLE_TEMPLATE> --> <APPLICATION> --> New disposable qube from <DISPOSABLE_TEMPLATE>` while disposable qube desktop entries will have ``(dvm)`` string inserted. Clicking on this entry will launch the application in a new unnamed disposable based on the disposable template (not in the disposable template itself).
+
+.. important:: Application shortcuts that existed before setting this feature will not be updated automatically. Please go to |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> <DISPOSABLE_TEMPLATE> --> Settings`, in the :guilabel:`Applications` tab, unselect all existing shortcuts by clicking :guilabel:`<<`, then click :guilabel:`&OK` and close the dialog. Give it a few seconds and then reopen and re-select all the shortcuts you want to see in the menu. See :doc:`app menu shortcut troubleshooting </user/troubleshooting/app-menu-shortcut-troubleshooting>` for background information.
+
+Creating named disposables for service qubes
+--------------------------------------------
 
 
+You can use a :term:`named disposable` for a :term:`service qube` (such as those with the ``sys-*`` naming scheme) as long as they are 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 qube to qube communication and have manually edited :program:`nftables` or other items directly inside the firewall app qube.
 
-Using named disposables for service qubes
+Named disposable for service qubes without PCI devices via GUI
------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
-You can use a :term:`named disposable` for service qubes (such as those with the ``sys-*`` naming scheme) as long as they are 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.
+To create one that has no PCI devices attached, such as for ``sys-firewall``, create a :ref:`named disposable <user/how-to-guides/how-to-use-disposables:how to create named disposables>`. Write a name, choose a label and select :guilabel:`Launch Qube Settings after creation`. Click :guilabel:`Create new qube` to complete creation. When the :guilabel:`Qube Settings` opens:
+
+- :menuselection:`Basic --> Start qube automatically on boot`
+- :menuselection:`Basic --> Net qube --> sys-net`
+- :menuselection:`Advanced --> Provides network`
+
+Click :guilabel:`&OK` to save changes and close the window.
+
+On the :term:`GUI domain` terminal, disable disposable's appmenus:
+
+.. code:: console
+
+      user@dom0:~$ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
+
+Next, set the old service qube's autostart to false, and update any references to the old one to instead point to the new in the Qube Settings of each qube as well as Global Config. For example, ``qvm-prefs work netvm <SERVICE_QUBE>`` and ``qubes-prefs default_netvm <SERVICE_QUBE``.
+
+Named disposable for service qubes without PCI devices via command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 
 To create one that has no PCI devices attached, such as for ``sys-firewall``:
 
 .. code:: console
 
-      $ qvm-create -C DispVM -l green <SERVICE_QUBE>
+      user@dom0:~$ qvm-create -C DispVM -l green <SERVICE_QUBE>
-      $ qvm-prefs <SERVICE_QUBE> autostart true
+      user@dom0:~$ qvm-prefs <SERVICE_QUBE> autostart true
-      $ qvm-prefs <SERVICE_QUBE> netvm <NET_QUBE>
+      user@dom0:~$ qvm-prefs <SERVICE_QUBE> netvm <NET_QUBE>
-      $ qvm-prefs <SERVICE_QUBE> provides_network true
+      user@dom0:~$ qvm-prefs <SERVICE_QUBE> provides_network true
-      $ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
+      user@dom0:~$ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
 
+Next, set the old service qube's ``autostart`` to false, and update any references to the old one to instead point to the new in the Qube Settings of each qube as well as Global Config. Also make sure to update any :doc:`RPC policies </user/advanced-topics/rpc-policy>`, if needed.
 
-
+Here is an example of a complete ``sys-firewall`` replacement:
-Next, set the old ``sys-firewall`` autostart to false, and update any references to the old one to instead point to the new, for example, with ``qvm-prefs work netvm sys-firewall2``.
-
-To create one with a PCI device attached such as for ``sys-net`` or ``sys-usb``, use the additional commands as follows.
-
-**Note:** You can use ``qvm-pci`` to :ref:`determine <user/how-to-guides/how-to-use-pci-devices:\`\`qvm-pci\`\` usage>` the ``<BDF>``. Also, you will often need to include the ``-o no-strict-reset=True`` :ref:`option <user/how-to-guides/how-to-use-pci-devices:no-strict-reset>` with USB controllers.
 
 .. code:: console
 
-      $ qvm-create -C DispVM -l red <SERVICE_QUBE>
+      user@dom0:~$ qvm-create -C DispVM -l green sys-net2
-      $ qvm-prefs <SERVICE_QUBE> virt_mode hvm
+      user@dom0:~$ qvm-prefs sys-net2 autostart true
-      $ qvm-service <SERVICE_QUBE> meminfo-writer off
+      user@dom0:~$ qvm-prefs sys-net2 netvm <NET_QUBE>
-      $ qvm-pci attach --persistent <SERVICE_QUBE> dom0:<BDF>
+      user@dom0:~$ qvm-prefs sys-net2 provides_network true
-      $ qvm-prefs <SERVICE_QUBE> autostart true
+      user@dom0:~$ qvm-features sys-net2 appmenus-dispvm ''
-      $ qvm-prefs <SERVICE_QUBE> netvm ''
+      user@dom0:~$ qubes-prefs default_netvm sys-net2
-      $ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
+      user@dom0:~$ qubes-prefs updatevm sys-net2
+      user@dom0:~$ qvm-prefs sys-firewall netvm sys-net2
+
+Named disposable for service qubes with PCI devices via GUI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
+To create one with a PCI device attached, such as for ``sys-net`` or ``sys-usb``, create a :ref:`named disposable <user/how-to-guides/how-to-use-disposables:how to create named disposables>`. Write a name, choose a label and select :guilabel:`Launch Qube Settings after creation`. Click :guilabel:`Create new qube` to complete creation. When the :guilabel:`Qube Settings` opens:
+
+- :menuselection:`Basic --> Start qube automatically on boot`
+- :menuselection:`Basic --> Net qube --> (none)`
+- :menuselection:`Advanced --> Virtualization --> Mode --> HVM`
+- :menuselection:`Devices --> Available devices --> <DEVICE> --> >`
+- :menuselection:`Services --> Select a service --> meminfo-writer --> Add`
+
+Optionally, if this disposable will also provide network access to other qubes:
+
+- :menuselection:`Advanced --> Provides network`
+
+Click :guilabel:`&OK` to save changes and close the window.
+
+On the :term:`GUI domain` terminal, disable disposable's appmenus:
+
+.. code:: console
+
+      user@dom0:~$ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
+
+Next, set the old service qube's autostart to false, and update any references to the old one, e.g.:
+
+.. code:: console
+
+      user@dom0:~$ qvm-prefs sys-firewall netvm <SERVICE_QUBE>
+
+Also make sure to update any :doc:`RPC policies </user/advanced-topics/rpc-policy>`, if needed.
+
+
+Named disposable for service qubes with PCI devices via command line
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To create one with a PCI device attached, such as for ``sys-net`` or ``sys-usb``:
+
+.. important:: You can use ``qvm-pci`` to :ref:`determine <user/how-to-guides/how-to-use-pci-devices:\`\`qvm-pci\`\` usage>` the ``<BDF>``. Also, you will often need to include the ``-o no-strict-reset=True`` :ref:`option <user/how-to-guides/how-to-use-pci-devices:no-strict-reset>` with USB controllers.
+
+.. code:: console
+
+      user@dom0:~$ qvm-create -C DispVM -l red <SERVICE_QUBE>
+      user@dom0:~$ qvm-prefs <SERVICE_QUBE> virt_mode hvm
+      user@dom0:~$ qvm-service <SERVICE_QUBE> meminfo-writer off
+      user@dom0:~$ qvm-pci attach --persistent <SERVICE_QUBE> dom0:<BDF>
+      user@dom0:~$ qvm-prefs <SERVICE_QUBE> autostart true
+      user@dom0:~$ qvm-prefs <SERVICE_QUBE> netvm ''
+      user@dom0:~$ qvm-features <SERVICE_QUBE> appmenus-dispvm ''
 
 Optionally, if this disposable will also provide network access to other qubes:
 
 .. code:: console
 
-      $ qvm-prefs <SERVICE_QUBE> provides_network true
+      user@dom0:~$ qvm-prefs <SERVICE_QUBE> provides_network true
 
-
+Next, set the old service qube's autostart to false, and update any references to the old one, e.g.:
-
-Next, set the old service qube’s autostart to false, and update any references to the old one, e.g.:
 
 .. code:: console
 
-      $ qvm-prefs sys-firewall netvm <SERVICE_QUBE>
+      user@dom0:~$ qvm-prefs sys-firewall netvm <SERVICE_QUBE>
-
-
 
 Also make sure to update any :doc:`RPC policies </user/advanced-topics/rpc-policy>`, if needed.
 
@@ -143,61 +364,74 @@ Here is an example of a complete ``sys-net`` replacement:
 
 .. code:: console
 
-      $ qvm-create -C DispVM -l red sys-net2
+      user@dom0:~$ qvm-create -C DispVM -l red sys-net2
-      $ qvm-prefs sys-net2 virt_mode hvm
+      user@dom0:~$ qvm-prefs sys-net2 virt_mode hvm
-      $ qvm-service sys-net2 meminfo-writer off
+      user@dom0:~$ qvm-service sys-net2 meminfo-writer off
-      $ qvm-pci attach --persistent sys-net2 dom0:00_1a.0
+      user@dom0:~$ qvm-pci attach --persistent sys-net2 dom0:00_1a.0
-      $ qvm-prefs sys-net2 autostart true
+      user@dom0:~$ qvm-prefs sys-net2 autostart true
-      $ qvm-prefs sys-net2 netvm ''
+      user@dom0:~$ qvm-prefs sys-net2 netvm ''
-      $ qvm-features sys-net2 appmenus-dispvm ''
+      user@dom0:~$ qvm-features sys-net2 appmenus-dispvm ''
-      $ qvm-prefs sys-net2 provides_network true
+      user@dom0:~$ qvm-prefs sys-net2 provides_network true
-      $ qvm-prefs sys-net autostart false
+      user@dom0:~$ qvm-prefs sys-net autostart false
-      $ qvm-prefs sys-firewall netvm sys-net2
+      user@dom0:~$ qvm-prefs sys-firewall netvm sys-net2
-      $ qubes-prefs clockvm sys-net2
+      user@dom0:~$ qubes-prefs clockvm sys-net2
+
+Deleting disposable templates
+-----------------------------
 
 
+It is only possible to delete a disposable template if certain state is met:
 
-Adding programs to the app menu
+- No disposables based on it (preloaded disposables can be ignored).
--------------------------------
+- No system or qube property links to it (such as ``template`` or ``default_dispvm``).
 
+Let's delete a disposable template with |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> TEMPLATES --> <DISPOSABLE_TEMPLATE> --> Settings --> Basic --> Delete qube`.
 
-For added convenience, arbitrary programs can be added to the app menu of the disposable.
+Or with the command line equivalent:
-
-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.
-
-Deleting disposables
---------------------
-
-
-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 qubes:
 
 .. code:: console
 
-      [user@dom0 ~]$ qvm-prefs <QUBE> | grep default_dispvm
+      user@dom0:~$ qvm-remove <DISPOSABLE_TEMPLATE>
-      default_dispvm        -  <DISPOSABLE_TEMPLATE>
-
-
-This will prevent the deletion of the disposable template. In order to fix this, you need to unset the ``default_dispvm`` property:
-
-.. code:: console
-
-      [user@dom0 ~]$ qvm-prefs <QUBE> default_dispvm ""
-
-
-You can then delete the disposable template:
-
-.. code:: console
-
-      [user@dom0 ~]$ qvm-remove <DISPOSABLE_TEMPLATE>
       This will completely remove the selected VM(s)
         <DISPOSABLE_TEMPLATE>
+      Are you sure? [y/N]
+
+The deletion may fail if the qube is still referenced, in that case, proceed to the next sections.
+
+Retire the qube from being the system's default disposable template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+The system's default disposable template may reference the :samp:`{<DISPOSABLE_TEMPLATE>}`. Let's check if it is being used with |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> Settings (icon) --> Qubes Tools --> Qubes Global Config --> General --> Default disposable template`. Or the command line equivalent.
+
+.. code:: console
+
+      user@dom0:~$ qubes-prefs default_dispvm
+      <DISPOSABLE_TEMPLATE>
+
+If the :samp:`{<DISPOSABLE_TEMPLATE>}` is referenced, set an alternative, and if no alternative is available, set it to an empty value.
+
+Retire the qube from being a qube's default disposable template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Now let's check the per qube ``default_dispvm`` property for any qube, in this case, the ``work`` qube, in |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> work --> Settings --> Advanced --> Default disposable template`. Or use the command line equivalent:
+
+.. code:: console
+
+      user@dom0:~$ qvm-prefs <QUBE> | grep default_dispvm
+      default_dispvm        -  <DISPOSABLE_TEMPLATE>
+
+If the :samp:`{<DISPOSABLE_TEMPLATE>}` is referenced, set an alternative, and if no alternative is available, set it to an empty value.
+
+This process must be repeated for every qube that references the :samp:`{<DISPOSABLE_TEMPLATE>}`.
+
+Disposable template deletion troubleshooting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 
 If you still encounter a problem, you may have forgotten to clean an entry. Looking at the system logs will help you:
 
 .. code:: console
 
-      [user@dom0 ~]$ journalctl | tail
+      user@dom0:~$ journalctl -S 60s
-

user/how-to-guides/how-to-use-disposables.rst

@@ -2,199 +2,218 @@
 How to use disposables
 ======================
 
-A :term:`disposable` is a lightweight :term:`qube` that can be created quickly and will self-destruct when closed. Disposables are usually created in order to host a single application, like a viewer, editor, or web browser.
+A :term:`disposable` is a stateless :term:`qube`, it does not save data for the next boot. These qubes can serve various uses cases that require a pristine environment:
 
-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 qube. This means that you can safely work with untrusted files without risk of compromising your other qubes. Disposables can be launched either directly from dom0’s app menu or terminal window, or from within app qubes. Disposables are generated with names like ``disp####``, where ``####`` is random number.
+- View untrusted files without other trusted files on the same system;
+- Visit untrusted websites in a web browser without authentication cookies from previous session;
+- Sanitize untrusted PDFs or images and retrieve a safe-to-view image;
+- Connect untrusted devices without other trusted devices or files on the same system;
+- Fresh environment for build systems (for technical users).
+
+Disposables can be launched either directly from :term:`GUI domain`'s app menu or terminal window, or from within app qubes. Disposables are generated with names like :samp:`disp{1234}`, where :samp:`{1234}` is a random number. Below is an example of disposable workflow benefits:
 
 .. figure:: /attachment/doc/disposablevm-example.png
    :alt:
 
    Example of how disposables can be used to safely open untrusted links and attachments in disposables
 
-   In a *work-email* qube, the user clicks on a link. This link is opened in a new disposable through qrexec protocol (``qubes.OpenURL``). The link appears to be some kind of malware that infects the disposable qube but it is harmless as this qube is then destroyed.
+   In the ``work-email`` qube, the user clicks on a link. This link is opened in a new disposable through the qrexec protocol (:program:`qubes.OpenURL`). The link contains some kind of malware that infects the disposable qube, but it is harmless for the ``work-email`` qube, as the links was opened in a separate environment from the mail client, the mail box is safe. The disposable is later destroyed.
 
-   In that same *work-email* qube, the user now opens a PDF attachment. Using the qrexec protocol (``qubes.OpenInVM``), the PDF is opened as a legitimate file in a new disposable qube. The disposable is destroyed at the end of the process.
+   In that same *work-email* qube, the user now opens a PDF attachment. Using the qrexec protocol (:program:`qubes.OpenInVM`), the PDF is opened as in a new disposable qube, this time, the file looks clean, but as we can never be sure, the user prefers to default to open files in disposables. The disposable is later destroyed.
 
-   See `this article <https://blog.invisiblethings.org/2010/06/01/disposable-vms.html>`__ for more on why one would want to use a disposable.
+This diagram provides a general example of how disposables can be used to safely open untrusted links and attachments in disposables. You may find more on why one would want to use a disposable on the `first disposable qube article <https://blog.invisiblethings.org/2010/06/01/disposable-vms.html>`__. Please note that the blog post is dated and some of the information it presents are not accurate anymore.
 
-Named disposables and disposable templates
+Disposable types
-------------------------------------------
+----------------
 
-There is a difference between :term:`named disposable qubes <named disposable>` and :term:`disposable templates <disposable template>`.
 
-In a default QubesOS Installation, you would probably use the ‘whonix-ws-16-dvm’ disposable template to, for example, browse the Tor network with an disposable qube. Every time you start an application using this disposable template, a new disposable qube - named :samp:`disp{1234}` (where :samp:`{1234}` is a random number) starts. If you close the application window, the :samp:`disp{1234}` qube shuts down and vanishes from your system. That is how disposable templates are used.
+Disposable template
+^^^^^^^^^^^^^^^^^^^
 
-Named disposables are also built upon disposable templates, but they have a fixed name. The named disposable seems to behave like an ordinary app qube - every application you open will start in the same qube, and you need to manually shutdown the qube. But when you shutdown *any changes you made in the named disposable will be lost*. Except for this non-persistance, they feel like usual app qubes.
 
-How to create disposable templates
+:term:`Disposable template <disposable template>` is not a disposable in itself, but a special template that can create different disposable types, :term:`named disposable <named disposable>` and :term:`unnamed disposables <unnamed disposable>`. When there is need to customize the files of a disposable, it must be done on the disposable template or the template itself to be reflected in every new disposable based on that template. By default, Qubes OS creates the ``default-dvm`` disposable template, we will use it as an example on this page, but you can create as many disposable templates as you'd prefer. :doc:`Disposable customization </user/advanced-topics/disposable-customization>` is outside of the scope of this page.
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-First, you need to create an app qube. You can run it normally, set up any necessary settings (like browser settings) you wish to be applied to every disposable qube ran from this template. Next, go to ‘Qube Settings’ of the app qube, set it as a *Disposable template* in the *Advanced* section and apply the change.
+Named disposable
+^^^^^^^^^^^^^^^^
 
-In Qubes 4.1, the entry in the Application menu is split into ‘Disposable’ and ‘Template (disp)’. The settings for the disposable can be changed under :menuselection:`Application Menu --> Template (disp) --> Template: Qubes Settings`
 
-In Qubes 4.2, the qube will now appear in the menu as a disposable template (in the Apps section), from which you can launch new disposable qubes. To change the settings of the template itself or run programs in it, use the menu item for the disposable template located in the Templates section.
+:term:`Named disposables<named disposable>` are built upon disposable templates, but they have a fixed name. The named disposable seems to behave like an ordinary app qube, it doesn't shutdown when you close the initial application, every application you open will start in the same qube, and you need to manually shut it down. However, when it is shutdown, *any changes you made in the named disposable will be lost*.
+
+If you have selected during installation to use disposable :term:`service qubes<service qube>`, your ``sys-net``, ``sys-usb`` and ``sys-firewall`` are examples of named disposables based on the ``default-dvm`` disposable template.
+
+
+Unnamed disposable
+^^^^^^^^^^^^^^^^^^
+
+
+:term:`Unnamed disposables<unnamed disposable>` are built upon disposable templates, they don't have a fixed name and are deleted from the system after the termination of initial application opened in them. Therefore, *any changes you made in the unnamed disposable will be lost*. The Qubes Devices widget doesn't connect to an initial application when creating a disposable, therefore it must be manually turned off.
+
+You would probably use the ``default-dvm`` disposable template to, for example, create an unnamed disposable qube to browse the internet. Every time you launch an application using this disposable template as base, a new disposable qube named :samp:`disp{1234}` (where :samp:`{1234}` is a random number) starts and launches the chosen application. If you close the application window, the :samp:`disp{1234}` qube shuts down and vanishes from your system.
+
+
+How to create disposables
+-------------------------
+
 
 How to create named disposables
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In Qubes 4.1: named disposables can be created under :menuselection:`Application Menu --> Create Qubes VM`, set the qube type to be *DisposableVM*.
 
-In Qubes 4.2: named disposables can be created by :menuselection:`Application Menu --> Settings --> Qubes Settings --> Create New Qube`. Set the qube type to **Named disposable**.
+Named disposables can be created with |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> Settings (icon) --> Qubes Tools --> Create New Qube --> Named disposable`, choose a name, configure according to your needs and click on :guilabel:`Create`.
 
-Security
+If you create the qube with the name ``test-disp``, you can open applications on it using |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> test-disp` and selecting the application you wish to open in the named disposable.
---------
 
-If a :term:`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.
+How to create unnamed disposables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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>`__.
+Unnamed disposables can be created with |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> default-dvm`, select the application you wish to launch in a new unnamed disposable and one will created for you. Notice that the application was not opened in the disposable template ``default-dvm``, instead, it opens in a :samp:`disp{1234}` qube. This is because applications from a disposable template listed in the :guilabel:`APPS` tab will open in a new unnamed disposable.
 
-When it is essential to avoid leaving any trace, consider using `Tails <https://tails.net>`__.
+After the qube is created, you can access it via other tools using its :samp:`disp{1234}` name, :ref:`Qubes Domains widget <introduction/getting-started:user interface>`, :ref:`Qubes Manager <introduction/getting-started:qube manager>`, |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> disp1234`, :guilabel:`qvm-copy`, :program:`qvm-ls` etc.
 
-Disposables and Networking
+In action
---------------------------
+---------
 
-Similarly to how app qubes are based on their underlying :term:`template`, disposables are based on their underlying :term:`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-X-dvm`` or ``debian-X-dvm`` (where ``X`` is a release number). If you have included the Whonix option in your install, there will also be a ``whonix-ws-dvm`` disposable template available for your use.
+Open an application in a disposable (from GUI domain)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-You can set any app qube to have the ability to act as a disposable template with:
+
+Sometimes it is desirable to open an instance of Firefox in a new fresh disposable. This can be done easily using the app menu: just go to |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> APPS --> default-dvm --> Firefox`. Wait a few seconds until the web browser starts.
+
+.. image:: /attachment/doc/r4.3-dom0-menu-disp-firefox.png
+   :alt: Application menu being used to open an Firefox from the ``default-dvm`` in a disposable qube.
+
+.. image:: /attachment/doc/r4.3-dom0-menu-disp-firefox-open.png
+   :alt: Firefox opened in a disposable qube in the default page.
+
+It is possible to do the same as above using the command line:
 
 .. code:: console
 
-      [user@dom0] $ qvm-prefs <APP_QUBE> template_for_dispvms True
+      user@dom0:~$ qvm-run --dispvm=default-dvm --service -- qubes.StartApp+firefox
 
-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.
+The browser is opened from a disposable based on the ``default-dvm`` qube.
 
-You can change this behavior for individual qubes: in the Application Menu, open Qube Settings for the qube 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 qube. This can also be changed from the command line with:
+Open a file in a disposable (from app qube)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+In an app qube's file manager, right click on the file you wish to open in a disposable, then choose :guilabel:`Edit/View in disposable qube`. 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 qube, a disposable created for the purpose of viewing or editing this very file. 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.
+
+.. image:: /attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png
+   :alt: App qube file manager context menu being used to edit a PDF in a disposable qube.
+
+.. image:: /attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png
+   :alt: PDF viewer opened in a disposable qube with the PDF the user selected to edit.
+
+
+It is also possible to do the same from the command line using :program:`qvm-open-in-dvm`:
 
 .. code:: console
 
-      [user@dom0] $ qvm-prefs <QUBE> default_dispvm <DISPOSABLE_TEMPLATE>
+      [user@work ~]$ qvm-open-in-dvm -- 'apple-sandbox.pdf'
+      [user@work ~]$ qvm-open-in-dvm --view-only -- 'apple-sandbox.pdf'
 
-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.
+The PDF viewer is opened in a disposable based on the ``work`` qube default disposable template.
 
-Network and firewall settings for disposable templates can be set as they can for a normal qube. By default a disposable will inherit the network and firewall settings of the disposable template on which it is based. This is a change in behavior 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 net qube, but the default system disposable uses sys-whonix, any disposable launched from this app qube will have sys-whonix as its net qube.
+Sanitize a file in a disposable (from app qube)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. 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 app menu inherits the net qube and firewall settings of the disposable template on which it is based. Note that changing the net qube setting for the system default disposable template *does* affect the net qube of disposables launched from the app menu. Different disposable templates with individual net qube settings can be added to the app menu.
+There is a nice security property in the system that allows transforming untrusted files into trusted files, this process is called sanitization. A sanitized file, presumably, leaves no room to malicious code, therefore, you can safely open the sanitized file in the qube itself (doesn't need to view in disposable anymore), in a viewer outside of :term:`Qubes OS`, or send the sanitized file to someone that doesn't use :term:`Qubes OS` and can't make the conversion themselves without compromising them..
 
-.. important:: 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:
+Only supported file types for conversions are images and PDFs. The untrusted files will be converted to :abbr:`RGBA bitmap (A raster image where pixels are stored in Red, Green, Blue and Alpha)`. On conversion, the original untrusted files will be moved to :file:`~/QubesUntrustedPDFs` or :file:`image.png-untrusted` (location depends on the file type) while the sanitized file will be created with the same location and name by reconstructing the received data. As the output is an image, the sanitized files are a bit bigger, searching strings without :abbr:`OCR (Optical Character Recognition)` will not be possible anymore.
 
-   .. code:: console
+If you'd like to sanitize a file, in an app qube's file manager, right click on the file (image or PDF) you wish to sanitize in a disposable, then choose :guilabel:`Convert in disposable qube`. Wait a few seconds for the conversion. This conversion runs on its own dedicated qube, a disposable created for the sole purpose of sanitizing this very file.
 
-      [user@dom0] $ qvm-features <DISPOSABLE_TEMPLATE> appmenus-dispvm 1
+It is also possible to do the same on the command line using :program:`qvm-convert-img` and :program:`qvm-convert-pdf`.
 
-To launch a disposable template from the command line, execute the following command in dom0:
+Connect a device to an unnamed disposable (from GUI domain)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Sometimes you have a device which you don't trust, therefore you decide to leverage disposables for the task. To attach a device to a disposable, go to :menuselection:`Qubes Devices widget --> <DEVICE> --> Attach to new disposable qube --> default-dvm`.
+
+.. note:: No application will launch by default and the disposable will continue running, that is expected, no application request was made. Also notice that opening and closing the first (or any other) application opened in the disposable will not turn it off, this is also expected, you must shutdown disposables created by the Qubes Devices widget manually.
+
+
+The same can be done from the command line, although more difficult:
+
+..
+   Python Admin API was preferred because each shell has a different way to read null bytes (qubesd-query).
+   The escaped backslash is used to have indented blocks for readability.
 
 .. code:: console
 
-      [user@dom0] $ qvm-run --dispvm=<DISPOSABLE_TEMPLATE> --service qubes.StartApp+<APPLICATION>
+      user@dom0:~$ disp_template="default-dvm"
+      user@dom0:~$ disp="$(python3 -c "import qubesadmin; \
+          app = qubesadmin.Qubes(); \
+          appvm = app.domains['$disp_template']; \
+          disp = qubesadmin.vm.DispVM.from_appvm(qubesadmin.Qubes(), appvm); \
+          disp.start(); \
+          print(disp.name)
+      ")"
+      user@dom0:~$ qvm-device <DEVICE_CLASS> attach <ATTACH_OPTIONS> -- "$disp" <BACKEND:DEVICE_ID>
+      user@dom0:~$ # Do your tasks.
+      user@dom0:~$ qvm-device <DEVICE_CLASS> dettach <ATTACH_OPTIONS> -- "$disp"
+      user@dom0:~$ qvm-kill -- "$disp"
 
-Opening a file in a disposable via GUI
+Retrieve unnamed disposables faster (preloaded disposables)
---------------------------------------
+-----------------------------------------------------------
 
-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 qube – 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.
 
-.. image:: /attachment/doc/r4.0-open-in-dispvm-1.png
+Disposable qubes can take some time to boot. It is possible to queue several unnamed disposables, guaranteeing a faster workflow.
-   :alt:
 
-.. image:: /attachment/doc/r4.0-open-in-dispvm-2.png
+Preloaded disposables are a type of :term:`unnamed disposables <unnamed disposable>` started in the background and queued. It is hidden from most graphical applications by using the :term:`internal` flag. You can use preloaded disposables by attempting to create a new disposable out of a disposable template, instead, the preloaded disposable will be provided to your while another disposable will be preloaded in the background to continue the cycle.
-   :alt:
 
-Opening a fresh web browser instance in a new disposable
+The use of preloaded disposables is indistinguishable from the use of ref:`using unnamed <user/how-to-guides/how-to-use-disposables.html:how to create unnamed disposables>`. Requesting a disposable respects the template inheritance, if the disposable template has preloaded disposables, it will use those, when it doesn't have any, it will generate new ones.
---------------------------------------------------------
 
-Sometimes it is desirable to open an instance of Firefox within a new fresh disposable. This can be done easily using the app menu: just go to :menuselection:`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.
+It is possible to preload from any disposable template as long as it supports :doc:`Qrexec </developer/services/qrexec>`, except :term:`Qubes Windows Tools (QWT)` which isn't feature complete yet.
 
-.. image:: /attachment/doc/r4.0-open-in-dispvm-3.png
+Preload disposables from the system's default disposable template
-   :alt:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-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:
+Configuring system's default disposable template setting is very useful when you use this disposable template a lot. The system setting applies to whichever disposable template currently is the system's one, so if you change it, the preloaded disposables will be updated accordingly.
+
+Preloading from the system's default disposable is possible with the |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> Settings (icon) --> Qubes Tools --> Qubes Global Config --> General --> Preload disposable qubes` and choose a small number such as ``2`` for testing, end with :guilabel:`Apply Changes and Close`.
+
+.. image:: /attachment/doc/r4.3-disp-preload-global.png
+   :alt: Global config window with preloaded disposables items emphasized and preload disposable setting configured to ``2``.
+
+This can also be changed from the command line from the :term:`GUI domain`, with :program:`qvm-features` targeting ``dom0``:
 
 .. code:: console
 
-      [user@work-pub ~]$ qvm-open-in-dvm Downloads/apple-sandbox.pdf
+      user@dom0:~$ qvm-features dom0 preload-dispvm-max 2
 
-Note that the ``qvm-open-in-dvm`` process will not exit until you close the application in the disposable.
+Preload disposables from a specific disposable template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Making a particular application open everything in a disposable
----------------------------------------------------------------
 
-You can use the ``qvm-service`` command or the services GUI to cause an application in a qube to open files and URLs in a disposable. To do this, enable a service named ``app-dispvm.X`` in that qube, where ``X`` is the application ID. For instance, to have Thunderbird open all attachments in a disposable, enable the ``app-dispvm.thunderbird`` service.
+Configuring per disposable template setting is very useful when the disposable template is intended for specific workflows:
 
-This feature is currently somewhat experimental, and only works for Linux qubes. It is known to work with Thunderbird and Wire, but it may fail to work with some applications that do not honor all XDG environment variables. If the feature does not work for you, please file a bug report.
+- ``default-mgmt-dvm``: :term:`management qube`, used for :doc:`Salt </user/advanced-topics/salt>`, Ansible and Debug Console.
+- ``qubes-builder-dvm``: :doc:`Qubes Builder V2 Executor qube </developer/building/qubes-builder-v2>`
 
-Opening particular types of files in a disposable
+To configure, for example, the ``default-mgmt-dvm`` qube using the app menu and qube manager, as it is an :term:`internal qube`, first we need to make it visible, in the  |qubes-logo-icon|:menuselection:`Qubes App Menu (Q icon) --> Settings (icon) --> Qubes Tools --> Qube Manager --> View --> Show internal qubes`. After this step is completed, :menuselection:`Qube Manager --> default-mgmt-dvm --> Settings (icon) --> Advanced --> Preload disposables`, choose a number such as ``2`` and click :guilabel:`&OK` to apply and save changes.
--------------------------------------------------
 
-You can set ``qvm-open-in-dvm.desktop`` as the handler for a given MIME type. This will cause all files of that type to open in a disposable. This works in disposable templates too, but be careful: if your disposable template is set to use ``qvm-open-in-dvm.desktop`` to open a certain kind of file, every disposable based on it will be as well. If the disposable template is its own default disposable template (as is often the case), this will result in a loop: ``qvm-open-in-dvm`` will execute ``qubes.OpenURL`` in a new disposable, but that will in turn execute ``qvm-open-in-dvm``. The cycle will repeat until no new disposables can be created, most likely because your system has run out of memory.
+.. note:: You may deselect :guilabel:`Show internal qubes` to hide them again after making the changes.
 
-This will *not* override the internal handling of PDF documents in Web browsers. This is typically okay, though: in-browser PDF viewers have a fairly good security record, especially when compared to non-browser PDF viewers. In particular, the attack surface of PDF viewing in Firefox is usually less than that of viewing an ordinary Web page.
+.. image:: /attachment/doc/r4.3-disp-preload-local.png
+   :alt: Qube settings of ``default-mgmt-dvm`` with preloaded disposable setting configured to ``2``.
 
-Starting an arbitrary program in a disposable from an app qube
+This can also be changed from the command line from the :term:`GUI domain`, with :program:`qvm-features` targeting ``default-mgmt-dvm``:
+
+.. code:: console
+
+      [user@dom0 ~]$ qvm-features default-mgmt-dvm preload-dispvm-max 2
+
+Call to the application succeeds but disposable exits too soon
 --------------------------------------------------------------
 
-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 in `issue #2581 <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__). Starting an arbitrary program can be done from an app qube by running
 
-.. code:: console
+When the main process of an application exits, the unnamed disposable is removed. Some applications, such as GNOME Terminal (show on the app menu as :guilabel:`Terminal`, `do not wait for the application to close before the main process exits <https://github.com/QubesOS/qubes-issues/issues/2581#issuecomment-272664009>`__.
-
-      [user@vault] $ qvm-run-vm '@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:
-
-.. code:: console
-
-      [user@dom0] $ 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):
-
-.. code:: console
-
-      [user@email] $ 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``
-
-.. code:: text
-
-      @anyvm @dispvm:<ONLINE_DISPOSABLE_TEMPLATE> allow
-
-This line means:
-
-- FROM: Any qube
-
-- TO: A disposable based on ``<ONLINE_DISPOSABLE_TEMPLATE>``
-
-- WHAT: Allow sending an “Open URL” request
-
-In other words, any qube 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 in :ref:`developer/services/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 in :doc:`/user/advanced-topics/disposable-customization`.
 
+These cases requires wrappers to keep the application running. Qubes provides a wrapper for this particular case, :program:`qubes-run-gnome-terminal`, which will be used automatically by :program:`qubes-run-terminal` or application :guilabel:`Run Terminal` if GNOME Terminal happens to be the preferred terminal for the disposable template.

user/reference/glossary.rst

@@ -2,6 +2,43 @@
 Glossary
 ========
 
+
+Primary
+-------
+
+
+.. glossary::
+
+   Qubes OS
+      A security-oriented operating system (OS). The main principle of Qubes OS is security by compartmentalization (or isolation), in which activities are compartmentalized (or isolated) in separate :term:`qube`.
+
+      - **Important:** The official name is "Qubes OS" (note the capitalization and the space between "Qubes" and "OS"). In casual conversation, this is often shortened to "Qubes". Only in technical contexts where spaces are not permitted (e.g., in usernames) may the space be omitted, as in ``@QubesOS``.
+
+Compartment nomenclature
+------------------------
+
+
+.. glossary::
+
+   qube
+      A secure compartment in Qubes OS. Currently, qubes are implemented as Xen :term:`domain`, but Qubes OS is independent of its underlying compartmentalization technology. :term:`VM`\ s could be replaced with a different technology, and qubes would still be called "qubes". Therefore, always opt for the term ``qube`` over the other terms unless explicitly guided otherwise.
+
+      - **Important:** The term "qube" is a common noun and should follow the capitalization rules of common nouns. For example, "I have three qubes" is correct, while "I have three Qubes" is incorrect. Note that starting a sentence with the plural of "qube" (i.e., "Qubes ...") can be ambiguous, since it may not be clear whether the referent is a plurality of qubes or :term:`Qubes OS`.
+
+      - Example usage: Bank in your ``banking`` qube and web surf in your ``untrusted`` qube. That way, if your ``untrusted`` qube is compromised, your banking activities remains secure.
+
+      - Historical note: The term "qube" was originally invented as an alternative to "VM" intended to make it easier for less technical users to understand Qubes OS and learn how to use it.
+
+   domain
+      In Xen, a synonym for :term:`vm`. See `"domain" on the Xen Wiki <https://wiki.xenproject.org/wiki/Domain>`__. This term has no official meaning in Qubes OS.
+
+   VM
+      An abbreviation for "virtual machine". A software implementation of a computer that provides the functionality of a physical machine.
+
+Qube's types
+------------
+
+
 .. glossary::
 
    admin qube
@@ -9,25 +46,44 @@ Glossary
 
       - Currently, the only admin qube is :term:`dom0`.
 
-
-
    app qube
       Any :term:`qube` that does not have a root filesystem of its own. Every app qube is based on a :term:`template` from which it borrows the root filesystem.
 
       - Previously known as: ``AppVM``, ``TemplateBasedVM``.
 
-      - Historical note: This term originally meant “a qube intended for running user software applications” (hence the name “app”).
+      - Historical note: This term originally meant "a qube intended for running user software applications" (hence the name "app").
-
-
 
    disposable
-      A type of temporary :term:`app qube` that self-destructs when its originating window closes. Each disposable is based on a :term:`disposable template`.
+      A :term:`disposable` is a stateless :term:`qube`, it does not save data for the next boot. These qubes can serve various uses cases that require a pristine environment. See :doc:`/user/how-to-guides/how-to-use-disposables`.
-
-      See :doc:`/user/how-to-guides/how-to-use-disposables`.
 
       - Previously known as: ``DisposableVM``, ``DispVM``.
 
+   standalone
+      Any :term:`qube` that has its own root filesystem and does not share it with another qube. Distinct from both :term:`template` and :term:`app qube`.
 
+      See :doc:`/user/advanced-topics/standalones-and-hvms`.
+
+      - Previously known as: ``StandaloneVM``.
+
+   template
+      Any :term:`qube` that shares its root filesystem with another qube. A qube that is borrowing a template's root filesystem is known as an :term:`app qube` and is said to be "based on" the template. Templates are intended for installing and updating software applications, but not for running them.
+
+      See :doc:`/user/templates/templates`.
+
+      - No template is an :term:`app qube`.
+
+      - A template cannot be based on another template.
+
+      - Regular templates cannot function as :term:`disposable template`. (Disposable templates must be app qubes).
+
+      - Previously known as: ``TemplateVM``.
+
+
+Qube's types variations
+-----------------------
+
+
+.. glossary::
 
    disposable template
       Any :term:`app qube` on which :term:`disposable` are based. A disposable template shares its user directories (and, indirectly, the root filesystem of the regular :term:`template` on which it is based) with all :term:`disposable` based on it.
@@ -40,124 +96,74 @@ Glossary
 
       - Unlike :term:`disposable`, disposable templates have the persistence properties of normal :term:`app qube`.
 
-      - Previously known as: ``DisposableVM Template``, ``DVM Template``, ``DVM``.
+      - Previously known as: ``DisposableVM Template``, ``DVM Template``, ``DVM``. It is advised against the use of the ``DVM`` terms as it can be interpreted by some users as an abbreviation of ``DispVM``, which a ``DVM`` is not.
+
+   named disposable
+      A type of :term:`disposable` given a permanent name that continues to exist even after it is shut down and can be restarted again.
+
+      - Only one instance of a named disposable can run at a time.
+
+      - Technical note: Named disposables are useful for certain :term:`service qube`\ s, where the combination of persistent device assignment and ephemeral qube state is desirable.
+
+   unnamed disposable
+      A type of :term:`disposable` with a temporary name that ceases to exist after the qube is shut down. Closing the first application that was opened in the disposable will trigger the qube to shut down. Thus, if there is not initial application, such is the case with Qubes Devices widget, the qube has to be manually turned off.
+
+      - Multiple instances of a unnamed disposable can run at a time.
+
+      - Technical note: Unnamed disposables are useful for certain converting, viewing and editing untrusted files, where the combination of opening multiple files in disposable qubes that you don't need to remember their name for long is desirable.
+
+   management qube
+      A :term:`qube` used for automated management of a Qubes OS installation via :doc:`/user/advanced-topics/salt`.
+
+   net qube
+      Internally known as :term:`qube` that specifies from which qube, if any, it receives network access. Despite the name, "net qube" (or :term:`app qube` to be the :term:`service qube` ``sys-firewall``, which in turn uses ``sys-net`` as its net qube.
+
+      - If a qube does not have a net qube (i.e., its ``netvm`` is set to ``None``), then that qube is offline. It is disconnected from all networking.
+
+      - The name :term:`service qube` called a "NetVM". The name of the ``netvm`` property is a holdover from that era.
+
+   service qube
+      Any :term:`app qube` with the primary purpose of which is to provide services to other qubes. ``sys-net`` and ``sys-firewall`` are examples of service qubes.
+
+   internal qube
+      A qube which has the ``internal`` feature set. Used for the :term:`management qube` and preloaded disposables. These qubes are hidden from most Qubes OS graphical applications, as they are not intended to be used directly.
+
+   GUI domain
+      The GUI domain handles all the display-related tasks and some system management. There can be multiple GUI domains present on the system. Every GUI domain can have its own set of privileges, permissions, managed qubes etc. By default, :term:`dom0` is the only GUI domain.
+
+Miscellaneous
+-------------
 
 
+.. glossary::
 
    dom0
       :term:`domain` zero. A type of :term:`admin qube`. Also known as the **host** domain, dom0 is the initial qube started by the Xen hypervisor on boot. Dom0 runs the Xen management toolstack and has special privileges relative to other domains, such as direct access to most hardware.
 
-      - The term “dom0” is a common noun and should follow the capitalization rules of common nouns.
+      - The term "dom0" is a common noun and should follow the capitalization rules of common nouns.
-
-
-
-   domain
-      In Xen, a synonym for :term:`vm`.
-
-      See `“domain” on the Xen Wiki <https://wiki.xenproject.org/wiki/Domain>`__.
-
-      - This term has no official meaning in Qubes OS.
-
-
 
    domU
       Unprivileged :term:`domain`. Also known as **guest** domains, domUs are the counterparts to dom0. In Xen, all VMs except dom0 are domUs. By default, most domUs lack direct hardware access.
 
-      - The term “domU” is a common noun and should follow the capitalization rules of common nouns.
+      - The term "domU" is a common noun and should follow the capitalization rules of common nouns.
 
       - Sometimes the term :term:`vm` is used as a synonym for domU. This is technically inaccurate, as :term:`dom0` is also a VM in Xen.
 
-
-
-   firmware
-      Software that runs outside the control of the operating system. Some firmware executes on the same CPU cores as Qubes OS does, but all computers have many additional processors that the operating system does not run on, and these computers also run firmware.
-
    HVM
       Hardware-assisted Virtual Machine. Any fully virtualized, or hardware-assisted, :term:`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.
 
       See :doc:`/user/advanced-topics/standalones-and-hvms`.
 
-   management qube
+   firmware
-      A :term:`qube` used for automated management of a Qubes OS installation via :doc:`/user/advanced-topics/salt`.
+      Software that runs outside the control of the operating system. Some firmware executes on the same CPU cores as Qubes OS does, but all computers have many additional processors that the operating system does not run on, and these computers also run firmware.
-
-   named disposable
-      A type of :term:`disposable` given a permanent name that continues to exist even after it is shut down and can be restarted again. Like a regular :term:`disposable`, a named disposable has no persistent state: Any changes made are lost when it is shut down.
-
-      - Only one instance of a named disposable can run at a time.
-
-      - Like a regular :term:`disposable`, a named disposable always has the same state when it starts, namely that of the :term:`disposable template` on which it is based.
-
-      - Technical note: Named disposables are useful for certain :term:`service qube`, where the combination of persistent device assignment and ephemeral qube state is desirable.
-
-
-
-   net qube
-      Internally known as :term:`qube` that specifies from which qube, if any, it receives network access. Despite the name, “net qube” (or :term:`app qube` to be the :term:`service qube` ``sys-firewall``, which in turn uses ``sys-net`` as its net qube.
-
-      - If a qube does not have a net qube (i.e., its ``netvm`` is set to ``None``), then that qube is offline. It is disconnected from all networking.
-
-      - The name :term:`service qube` called a “NetVM.” The name of the ``netvm`` property is a holdover from that era.
-
-
 
    policies
-      In Qubes OS, “policies” govern interactions between qubes, powered by :doc:`Qubes’ qrexec system </developer/services/qrexec>`. A single policy is a rule applied to a qube or set of qubes, that governs how and when information or assets may be shared with other qubes.
+      In Qubes OS, "policies" govern interactions between qubes, powered by :doc:`Qubes' qrexec system </developer/services/qrexec>`. A single policy is a rule applied to a qube or set of qubes, that governs how and when information or assets may be shared with other qubes.
       An example is the rules governing how files can be copied between qubes.
       Policy rules are grouped together in files under ``/etc/qubes/policy.d``
       Policies are an important part of what makes Qubes OS special.
 
-
-   qube
-      A secure compartment in Qubes OS. Currently, qubes are implemented as Xen :term:`vm`, but Qubes OS is independent of its underlying compartmentalization technology. VMs could be replaced with a different technology, and qubes would still be called “qubes.”
-
-      - **Important:** The term “qube” is a common noun and should follow the capitalization rules of common nouns. For example, “I have three qubes” is correct, while “I have three Qubes” is incorrect.
-
-      - Note that starting a sentence with the plural of “qube” (i.e., “Qubes…”) can be ambiguous, since it may not be clear whether the referent is a plurality of qubes or :term:`Qubes OS`.
-
-      - Example usage: “In Qubes OS, you do your banking in your ‘banking’ qube and your web surfing in your ‘untrusted’ qube. That way, if your ‘untrusted’ qube is compromised, your banking activities will remain secure.”
-
-      - Historical note: The term “qube” was originally invented as an alternative to “VM” intended to make it easier for less technical users to understand Qubes OS and learn how to use it.
-
-
-
-   Qubes OS
-      A security-oriented operating system (OS). The main principle of Qubes OS is security by compartmentalization (or isolation), in which activities are compartmentalized (or isolated) in separate :term:`qube`.
-
-      - **Important:** The official name is “Qubes OS” (note the capitalization and the space between “Qubes” and “OS”). In casual conversation, this is often shortened to “Qubes.” Only in technical contexts where spaces are not permitted (e.g., in usernames) may the space be omitted, as in ``@QubesOS``.
-
-
-
    Qubes Windows Tools (QWT)
       A set of programs and drivers that provide integration of Windows qubes with the rest of the Qubes OS system.
 
       See :doc:`/user/templates/windows/qubes-windows-tools` and :doc:`/user/templates/windows/qubes-windows`.
-
-   service qube
-      Any :term:`app qube` the primary purpose of which is to provide services to other qubes. ``sys-net`` and ``sys-firewall`` are examples of service qubes.
-
-   standalone
-      Any :term:`qube` that has its own root filesystem and does not share it with another qube. Distinct from both :term:`template` and :term:`app qube`.
-
-      See :doc:`/user/advanced-topics/standalones-and-hvms`.
-
-      - Previously known as: ``StandaloneVM``.
-
-
-
-   template
-      Any :term:`qube` that shares its root filesystem with another qube. A qube that is borrowing a template’s root filesystem is known as an :term:`app qube` and is said to be “based on” the template. Templates are intended for installing and updating software applications, but not for running them.
-
-      See :doc:`/user/templates/templates`.
-
-      - No template is an :term:`app qube`.
-
-      - A template cannot be based on another template.
-
-      - Regular templates cannot function as :term:`disposable template`. (Disposable templates must be app qubes.)
-
-      - Previously known as: ``TemplateVM``.
-
-
-
-   VM
-      An abbreviation for “virtual machine.” A software implementation of a computer that provides the functionality of a physical machine.

user/troubleshooting/app-menu-shortcut-troubleshooting.rst

@@ -148,7 +148,7 @@ What about applications in disposables?
 ---------------------------------------
 
 
-See :ref:`Adding programs to the app menu in Disposable customization <user/advanced-topics/disposable-customization:adding programs to the app menu>`.
+See :ref:`Add programs to the app menu in Disposable customization <user/advanced-topics/disposable-customization:add programs to the app menu>`.
 
 What if a removed application is still in the app menu?
 -------------------------------------------------------