diff --git a/attachment/doc/r4.0-open-in-dispvm-1.png b/attachment/doc/r4.0-open-in-dispvm-1.png deleted file mode 100644 index 1c9f77c5..00000000 Binary files a/attachment/doc/r4.0-open-in-dispvm-1.png and /dev/null differ diff --git a/attachment/doc/r4.0-open-in-dispvm-2.png b/attachment/doc/r4.0-open-in-dispvm-2.png deleted file mode 100644 index 3b61fe0b..00000000 Binary files a/attachment/doc/r4.0-open-in-dispvm-2.png and /dev/null differ diff --git a/attachment/doc/r4.0-open-in-dispvm-3.png b/attachment/doc/r4.0-open-in-dispvm-3.png deleted file mode 100644 index 8a5123ac..00000000 Binary files a/attachment/doc/r4.0-open-in-dispvm-3.png and /dev/null differ diff --git a/attachment/doc/r4.3-disp-default-global.png b/attachment/doc/r4.3-disp-default-global.png new file mode 100644 index 00000000..ab75231a Binary files /dev/null and b/attachment/doc/r4.3-disp-default-global.png differ diff --git a/attachment/doc/r4.3-disp-default-local.png b/attachment/doc/r4.3-disp-default-local.png new file mode 100644 index 00000000..66097b8c Binary files /dev/null and b/attachment/doc/r4.3-disp-default-local.png differ diff --git a/attachment/doc/r4.3-disp-preload-global.png b/attachment/doc/r4.3-disp-preload-global.png new file mode 100644 index 00000000..837f8a28 Binary files /dev/null and b/attachment/doc/r4.3-disp-preload-global.png differ diff --git a/attachment/doc/r4.3-disp-preload-local.png b/attachment/doc/r4.3-disp-preload-local.png new file mode 100644 index 00000000..09618048 Binary files /dev/null and b/attachment/doc/r4.3-disp-preload-local.png differ diff --git a/attachment/doc/r4.3-dom0-menu-disp-firefox-open.png b/attachment/doc/r4.3-dom0-menu-disp-firefox-open.png new file mode 100644 index 00000000..2cc1be91 Binary files /dev/null and b/attachment/doc/r4.3-dom0-menu-disp-firefox-open.png differ diff --git a/attachment/doc/r4.3-dom0-menu-disp-firefox.png b/attachment/doc/r4.3-dom0-menu-disp-firefox.png new file mode 100644 index 00000000..eebd1f57 Binary files /dev/null and b/attachment/doc/r4.3-dom0-menu-disp-firefox.png differ diff --git a/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png new file mode 100644 index 00000000..e66f67b0 Binary files /dev/null and b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer-open.png differ diff --git a/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png new file mode 100644 index 00000000..8819e341 Binary files /dev/null and b/attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.png differ diff --git a/conf.py b/conf.py index 240d6286..131e7f3d 100644 --- a/conf.py +++ b/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 """ diff --git a/developer/services/disposablevm-implementation.rst b/developer/services/disposablevm-implementation.rst index 29babb56..d5d9bd71 100644 --- a/developer/services/disposablevm-implementation.rst +++ b/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 ` and :term:`unnamed disposables `. 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 ` property enabled, being a :py:class:`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 ` class and is based on a disposable template. Every disposable type has all of its volumes configured to disable :py:attr:`save_on_stop `, therefore no changes are saved on shutdown. Unnamed disposables enables the property :py:attr:`auto_cleanup ` by default, thus automatically removes the qube upon shutdown. Named disposables don't enable :py:attr:`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 - -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 +Unnamed disposables have their names in the format :samp:`disp{1234}`, where :samp:`{1234}` is derived from the :py:attr:`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. +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 ` 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 ` tag, which translates to creation of disposables out of the :py:attr:`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 `, 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 `. 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`` - -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. +Preloaded disposable's management +""""""""""""""""""""""""""""""""" +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 ` 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 ` 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 ` 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 ` by setting it to use its preferred memory value. In :doc:`qmemman terms `, 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 `__: + + - 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 ` 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` 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 ` 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 ` 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 ` 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 `__. + +**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 `__ 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. diff --git a/introduction/getting-started.rst b/introduction/getting-started.rst index 4ea0eb85..533532b5 100644 --- a/introduction/getting-started.rst +++ b/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) --> --> Settings --> Delete qube`, where :samp:`{}` is the qube you desire to delete. + +To list qubes, use the :ref:`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` diff --git a/introduction/screenshots.rst b/introduction/screenshots.rst index 1497e153..87b792fd 100644 --- a/introduction/screenshots.rst +++ b/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| - -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. +|r4.3-domU-filemanager-disp-pdfviewer.png| |r4.3-domU-filemanager-disp-pdfviewer-open.png| +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.0-open-in-dispvm-2.png| image:: /attachment/doc/r4.0-open-in-dispvm-2.png +.. |r4.3-domU-filemanager-disp-pdfviewer.png| image:: /attachment/doc/r4.3-domU-filemanager-disp-pdfviewer.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 diff --git a/user/advanced-topics/disposable-customization.rst b/user/advanced-topics/disposable-customization.rst index de7cb813..a2650ec6 100644 --- a/user/advanced-topics/disposable-customization.rst +++ b/user/advanced-topics/disposable-customization.rst @@ -10,132 +10,353 @@ Introduction ------------ -A :doc:`disposable ` can be based on any :term:`app qube`. You can also choose to use different :term:`disposable templates ` 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 ` 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 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 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 ` 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 `__. When it is essential to avoid leaving any trace, consider using `Tails `__ on bare-metal, as using Tails on a `qube cannot be relied on for amnesiac purposes `__. -.. code:: console - - [user@dom0 ~]$ qvm-create --template