From 19cc43f286dbe38dfe377ce1bb6d56b460bfb887 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Fri, 1 Aug 2025 02:36:56 -0400 Subject: [PATCH] Migration: fix indented lists and raw html tables All raw directives have been removed or replaced by reStructuredText list-tables. --- developer/building/qubes-builder-v2.rst | 53 +- developer/code/code-signing.rst | 15 +- developer/code/source-code.rst | 1 + developer/general/usability-ux.rst | 72 +- developer/services/admin-api.rst | 33 +- developer/services/qrexec.rst | 5 +- developer/system/gui.rst | 1611 ++++------------------- user/templates/templates.rst | 55 +- 8 files changed, 299 insertions(+), 1546 deletions(-) diff --git a/developer/building/qubes-builder-v2.rst b/developer/building/qubes-builder-v2.rst index c9a23de7..7e297a0f 100644 --- a/developer/building/qubes-builder-v2.rst +++ b/developer/building/qubes-builder-v2.rst @@ -2,7 +2,6 @@ Qubes builder v2 ================ - This is a brief introduction to using Qubes Builder v2 to work with Qubes OS sources. It will walk you through installing and configuring Builder v2, and using it to fetch and build Qubes OS packages. For details and customization, use `Qubes OS v2 builder documentation `__. @@ -10,13 +9,11 @@ For details and customization, use `Qubes OS v2 builder documentation " - + Change (N)ame, (E)mail, or (O)kay/(Q)uit? O We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number generator a better chance to gain enough entropy. - + - + We need to generate a lot of random bytes. It is a good idea to perform some other action (type on the keyboard, move the mouse, utilize the disks) during the prime generation; this gives the random number @@ -48,7 +48,7 @@ Alex Cabal has written an excellent `guide @@ -111,6 +111,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign 3. (Optional) Create signed tags. Signed commits are totally sufficient to contribute to Qubes OS. However, if you have commits which are not signed and you do not want to change them, you can create a signed tag for the commit and push it before the check. + This is useful for example, if you have a commit back in the git history which you like to sign now without rewriting the history. .. code:: bash diff --git a/developer/code/source-code.rst b/developer/code/source-code.rst index 7765a2fc..ae3ec0ce 100644 --- a/developer/code/source-code.rst +++ b/developer/code/source-code.rst @@ -61,6 +61,7 @@ How to Send Patches If you want to :ref:`contribute code ` to the project, there are two ways. Whichever method you choose, you must :doc:`sign your code ` before it can be accepted. - **Preferred**: Use GitHub’s `fork & pull requests `__. + Opening a pull request on GitHub greatly eases the code review and tracking process. In addition, especially for bigger changes, it’s a good idea to send a message to the :ref:`qubes-devel mailing list ` in order to notify people who do not receive GitHub notifications. - Send a patch to the :ref:`qubes-devel mailing list ` (``git format-patch``). diff --git a/developer/general/usability-ux.rst b/developer/general/usability-ux.rst index da9baacf..acebc1d5 100644 --- a/developer/general/usability-ux.rst +++ b/developer/general/usability-ux.rst @@ -2,19 +2,15 @@ Usability & UX ============== - Software that is too complicated to use, is often unused. Because we want as many people as possible to benefit from its unique security properties, the usability and user experience of Qubes OS is an utmost priority! We ask anyone developing for Qubes OS to please read through this guide to better understand the user experience we strive to achieve. We also ask them to review `our visual style guide `__ for other design related information. - ---- - Easy To Use ----------- - An ideal user experience is friendly, and it beckons a new user to explore the interface. In this process, they can naturally discover how to use the software. Below are some guidelines that will help you design a user interface that accomplishes this goal. |redx| **Interfaces Should Not** @@ -27,8 +23,6 @@ An ideal user experience is friendly, and it beckons a new user to explore the i - Overwhelm the user with too much information and cognitive load - - Perhaps the most common cause of mistakes is complexity. If there is a configuration setting that will significantly affect the user’s experience, choose a safe and smart default then tuck this setting in an ``Advanced Settings`` panel. |checkmark| **Interfaces Should** @@ -41,18 +35,13 @@ Perhaps the most common cause of mistakes is complexity. If there is a configura - Choose intelligent defaults for settings - - In making software easy to use, it is crucial to be mindful of `cognitive load `__ which dictates that *“humans are generally able to hold only seven +/- two units of information in short-term memory.”* Making sure your interfaces don’t pass this short-term memory limit is perhaps the most important factor in helping a user feel comfortable instead of overwhelmed. - ---- - Easy to Understand ------------------ - There will always be the need to communicate things to users. In these cases, an interface should aim to make this information easy to understand. The following are simple guides to help achieve this - none of these are absolute maxims! |redx| **Avoid Acronyms** @@ -67,8 +56,6 @@ Acronyms are compact and make good names for command line tools. They do not mak - ``NetVM`` - Networking Virtual Machine - - Despite this rule, some acronyms like ``USB`` are widely used and understood due to being in common use for over a decade. It is good to use these acronyms when the full words like ``Universal Serial Bus`` are more likely to confuse users. |checkmark| **Use Simple Words** @@ -83,12 +70,8 @@ Use the minimum amount of words needed to be descriptive, but also informative. - Use ``Networking`` or ``Networking Qube`` instead of ``NetVM`` given context - - - ---- - |redx| **Avoid Technical Words** Technical words are usually more accurate, but they often *only* make sense to technical users and are confusing and unhelpful to non-technical users. Examples of technical words that might show up in Qubes OS are: @@ -99,8 +82,6 @@ Technical words are usually more accurate, but they often *only* make sense to t - ``qrexec-daemon`` - - These are all terms that have at some point showed up in users’ notification messages. Each term is very specific, but requires the user to understand virtualization to interpret. |checkmark| **Use Common Concepts** @@ -113,14 +94,10 @@ Large amounts of the global population have been using computers for one or two - Use ``Qubes`` instead of ``qrexec-daemon`` as it gives better context on what is happening - - These words are more abstract and user relevant- they help a user understand what is happening based on already known concepts (disk space) or start to form a mental model of something new (Qubes). - ---- - |redx| **Avoid Inconsistencies** It is easy to start abbreviating (or making acronyms) of long terms like ``Disposable Virtual Machine`` depending on where the term shows up in an interface. @@ -131,8 +108,6 @@ It is easy to start abbreviating (or making acronyms) of long terms like ``Dispo - ``DisposableVM`` - - This variation in terms can cause new users to question or second guess what the three different variations mean, which can lead to inaction or mistakes. |checkmark| **Make Things Consistent** @@ -141,14 +116,10 @@ Always strive to keep things consistent in the interfaces as well as documentati - Use ``Disposable Qube`` at all times as it meets other criteria as well. - - By using the same term throughout an interface, a user can create a mental model and relationship with that term allowing them to feel empowered. - ---- - |redx| **Avoid Duplicate Words** It is easy to add words like ``Domain`` before items in a list or menu in an attempt to be descriptive, such as: @@ -160,8 +131,6 @@ It is easy to add words like ``Domain`` before items in a list or menu in an att - Domain: banking - Domain: personal - - The repeated use of the word ``Domain`` requires a user to read it for each item in the list, which makes extra work for the eye in parsing out the relevant word like ``work, banking, or personal``. This also affects horizontal space on fixed width lines. |checkmark| **Create Groups & Categories** @@ -175,16 +144,11 @@ It is more efficient to group things under headings instead as this allows the e - Banking - Personal - - - ---- - Easy To Complete ---------------- - Lastly, expected (and unexpected) situations often require user actions or input. Make resolving these occurences as easy as possible to complete the action. |redx| **Don’t Leave Users Stranded** @@ -195,8 +159,6 @@ Consider the following notifications: - ``There was an error saving Qube "Personal"`` - - Instead of displaying solvable errors like these and neglecting to provide a fix: |checkmark| **Offer Actionable Solutions** @@ -207,14 +169,10 @@ Error messages and limits such as those in the previous example can be greatly i - Add a link to a documentation page called ``Troubleshoot saving data`` - - In adhering to these principles, you’ll make undesirable situations more manageable for users instead of feeling stranded. - ---- - |checkmark| **Minimize Repetitive Steps** There are many cases where a user wants to perform an action on more than one file or folder. However in order to do the action, the user must repeat certain steps such as: @@ -223,26 +181,18 @@ There are many cases where a user wants to perform an action on more than one fi 2. Navigate through file system + - Click Folder One + - Click Folder Two -- Click Folder One - -- Click Folder Two - -- Click Folder Three - -- Click Folder Four - + - Click Folder Three + - Click Folder Four 3. Select proper file 4. Complete task on file - - - - That subtle act of clicking through a file system can prove to be significant if a user needs to open more than a couple files in the same directory. We can alleviate some of the work by changing the process: 1. Click on ``Open File`` from a menu or button @@ -253,18 +203,13 @@ That subtle act of clicking through a file system can prove to be significant if 4. Complete task - - Clearly, cutting out something as simple as navigating through the file system can save a user quite a bit of time. Alternatively, adding a button or menu item like ``Open Multiple Files`` might be even better, because remembering and using relevant hotkeys is often something only power users know how to do! - ---- - GNOME, KDE, and Xfce -------------------- - The desktop GUIs that QubesOS versions 1 - 4.1 offer are `KDE `__ and `Xfce `__. We are currently migrating towards using `GNOME `__. We know some people prefer KDE, but we believe Gnome is easier to use for average non-technical users. Xfce will always be supported, and technical users will always have the choice to use KDE or other desktop environments. This change means you should use `GTK `__ rather than Qt for new GUIs. @@ -277,16 +222,11 @@ All three of these mentioned desktop environments have their own `human interfac - `Xfce UI Guidlines `__ - - - ---- - Further Learning & Inspiration ------------------------------ - Learning to make well designing intuitive interfaces and software is specialized skillset that can take years to cultivate, but if you are interested in furthering your understanding, we suggest the following resources: - `Learn Design Principles `__ by Melissa Mandelbaum @@ -301,7 +241,5 @@ Learning to make well designing intuitive interfaces and software is specialized - `Hack Design `__ - online learning program - - .. |checkmark| image:: /attachment/doc/checkmark.png -.. |redx| image:: /attachment/doc/red_x.png \ No newline at end of file +.. |redx| image:: /attachment/doc/red_x.png diff --git a/developer/services/admin-api.rst b/developer/services/admin-api.rst index 03964deb..7ebbadb0 100644 --- a/developer/services/admin-api.rst +++ b/developer/services/admin-api.rst @@ -75,7 +75,7 @@ it easy to set the policy using current mechanism. - `-` - `-` - ``\n`` - - + - * - ``admin.vm.List`` - ``dom0|`` - `-` @@ -130,7 +130,7 @@ it easy to set the policy using current mechanism. - `-` - ```` - - * - ``admin.label.Remove`` + * - ``admin.label.Remove`` - ``dom0`` - label - `-` @@ -187,10 +187,10 @@ it easy to set the policy using current mechanism. * - ``admin.vm.property.List`` - vm - `-` - - `-` + - `-` - ``\n`` - - * - ``admin.vm.property.Get`` + * - ``admin.vm.property.Get`` - vm - property - `-` @@ -223,7 +223,7 @@ it easy to set the policy using current mechanism. * - ``admin.vm.property.Reset`` - vm - property - - `-` + - `-` - `-` - * - ``admin.vm.property.Set`` @@ -262,7 +262,7 @@ it easy to set the policy using current mechanism. - `-` - value - - * - ``admin.vm.feature.CheckWithTemplateAndAdminVM`` + * - ``admin.vm.feature.CheckWithTemplateAndAdminVM`` - vm - feature - `-` @@ -297,7 +297,7 @@ it easy to set the policy using current mechanism. - `-` - `-` - ``\n`` - - + - * - ``admin.vm.tag.Get`` - vm - tag @@ -318,7 +318,7 @@ it easy to set the policy using current mechanism. - * - ``admin.vm.firewall.Get`` - vm - - `-` + - `-` - `-` - ``\n`` - rules syntax as in :doc:`firewall interface ` (Firewall Rules in 4x) with addition of ``expire=`` and ``comment=`` options; ``comment=`` (if present) must be the last option @@ -363,11 +363,11 @@ it easy to set the policy using current mechanism. - device - `-` - `-` - - ``device`` is in form ``+`` + - ``device`` is in form ``+`` * - ``admin.vm.device..Set.required`` - vm - device - - ``True|False`` + - ``True|False`` - `-` - ``device`` is in form ``+`` * - ``admin.vm.deviceclass.List`` @@ -430,7 +430,7 @@ it easy to set the policy using current mechanism. - `-` - `-` - - * - ``admin.pool.volume.List`` + * - ``admin.pool.volume.List`` - ``dom0`` - pool - `-` @@ -483,12 +483,12 @@ it easy to set the policy using current mechanism. - pool - vid - token, to be used in ``admin.pool.volume.CloneTo`` - - obtain a token to copy volume ``vid`` in ``pool``; the token is one time use only, it's invalidated by ``admin.pool.volume.CloneTo``, even if the operation fails + - obtain a token to copy volume ``vid`` in ``pool``; the token is one time use only, it's invalidated by ``admin.pool.volume.CloneTo``, even if the operation fails * - ``admin.pool.volume.CloneTo`` - ``dom0`` - pool - `` `` - - `-` + - `-` - copy volume pointed by a token to volume ``vid`` in ``pool`` * - ``admin.vm.volume.List`` - vm @@ -498,7 +498,7 @@ it easy to set the policy using current mechanism. - ```` is per-VM volume name (``root``, ``private``, etc), ```` is pool-unique volume id * - ``admin.vm.volume.Info`` - vm - - volume + - volume - `-` - ``=\n`` - @@ -608,7 +608,7 @@ it easy to set the policy using current mechanism. - ``dom0`` - config id - `-` - - backup info + - backup info - info what would be included in the backup * - ``admin.backup.Cancel`` - ``dom0`` @@ -921,6 +921,3 @@ TODO - maybe some generator for ``.desktop`` for appmenus, which would wrap calls in ``qrexec-client-vm`` -.. raw:: html - - diff --git a/developer/services/qrexec.rst b/developer/services/qrexec.rst index 0ae67f06..9edcdc2f 100644 --- a/developer/services/qrexec.rst +++ b/developer/services/qrexec.rst @@ -113,7 +113,10 @@ Answering an RPC call ^^^^^^^^^^^^^^^^^^^^^ -In other for a RPC call to be answered in the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself – in which case it must have executable permission set (``chmod +x``): - ``/etc/qubes-rpc/RPC_ACTION_NAME`` when you make it in the template qube; - ``/usr/local/etc/qubes-rpc/RPC_ACTION_NAME`` for making it only in an app qube. +In other for a RPC call to be answered in the target VM, a file in either of the following locations must exist, containing the file name of the program that will be invoked, or being that program itself – in which case it must have executable permission set (``chmod +x``): + +- ``/etc/qubes-rpc/RPC_ACTION_NAME`` when you make it in the template qube; +- ``/usr/local/etc/qubes-rpc/RPC_ACTION_NAME`` for making it only in an app qube. The source VM name can then be accessed in the server process via ``QREXEC_REMOTE_DOMAIN`` environment variable. (Note the source VM has *no* control over the name provided in this variable–the name of the VM is provided by dom0, and so is trusted.) diff --git a/developer/system/gui.rst b/developer/system/gui.rst index bf77db0c..2f67ddf9 100644 --- a/developer/system/gui.rst +++ b/developer/system/gui.rst @@ -58,8 +58,6 @@ Currently, using ``WINDOW_DUMP`` does come at a performance cost, because the Ap .. figure:: /attachment/doc/gui.png :alt: gui.png - - Security markers on dom0 windows -------------------------------- @@ -119,776 +117,172 @@ Each message starts with the following header: This header is followed by message-specific data: -.. raw:: html +.. list-table:: - + * - Message name + - Structure after header + - Action + + * - MSG_CLIPBOARD_DATA + - amorphic blob (in protocol before 1.2, length determined by the “window” field, in 1.2 and later - by untrusted_len in the header) + - Store the received clipboard content (not parsed in any way) + + * - MSG_CREATE + - .. code:: c + + struct msg_create { + uint32_t x; + uint32_t y; + uint32_t width; + uint32_t height; + uint32_t parent; + uint32_t override_redirect; + }; + - Create a window with given parameters + + * - MSG_DESTROY + - None + - Destroy a window -.. raw:: html + * - MSG_MAP + - .. code:: c + + struct msg_map_info { + uint32_t transient_for; + uint32_t override_redirect; + }; - + - Map a window with given parameters -.. raw:: html + * - MSG_UNMAP + - None + - Unmap a window - + struct shm_cmd { + uint32_t shmid; + uint32_t width; + uint32_t height; + uint32_t bpp; + uint32_t off; + uint32_t num_mfn; + uint32_t domid; + uint32_t mfns[0]; + }; -.. raw:: html + - Retrieve the array of mfns that constitute the composition buffer of a remote window. - + - Repaint the given window fragment -.. raw:: html + * - MSG_WMNAME + - .. code:: c - + * - MSG_WINDOW_HINTS + - .. code:: c -.. raw:: html + struct msg_window_hints { + uint32_t flags; + uint32_t min_width; + uint32_t min_height; + uint32_t max_width; + uint32_t max_height; + uint32_t width_inc; + uint32_t height_inc; + uint32_t base_width; + uint32_t base_height; + }; - + - Size hints for window manager -.. raw:: html + * - MSG_WINDOW_FLAGS + - .. code:: c - + struct msg_window_flags { + uint32_t flags_set; + uint32_t flags_unset; + }; -.. raw:: html + - Change window state request; fields contains bitmask which flags request to be set and which unset - + * - MSG_WMCLASS + - .. code:: c -.. raw:: html + struct msg_wmclass { + char res_class[64]; + char res_name[64]; + }; - + - Header for shared memory dump command of type hdr.type. Currently only ``WINDOW_DUMP_TYPE_GRANT_REFS`` (0) is supported. + * - WINDOW_DUMP_TYPE_GRANT_REFS + - .. code:: c -.. raw:: html + struct msg_window_dump_grant_refs { + uint32_t refs[0]; + }; - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - - .. raw:: html - - - - .. raw:: html - - - - .. raw:: html - - - - .. raw:: html - - - - .. raw:: html - - - - .. raw:: html - - - - .. raw:: html - - - - .. raw:: html - -
+ * - MSG_CONFIGURE + - .. code:: c -Message name + struct msg_configure { + uint32_t x; + uint32_t y; + uint32_t width; + uint32_t height; + uint32_t override_redirect; + }; + + - Change window position/size/type -.. raw:: html + * - MSG_MFNDUMP + - .. code:: c - + The “num_mfn” 32bit integers follow the shm_cmd structure; “off” is the offset of the composite buffer start in the first frame; “shmid” and “domid” parameters are just placeholders (to be filled by ``qubes-guid``), so that we can use the same structure when talking to ``shmoverride.so``. -Structure after header + * - MSG_SHMIMAGE + - .. code:: c -.. raw:: html + struct msg_shmimage { + uint32_t x; + uint32_t y; + uint32_t width; + uint32_t height; + }; - + struct msg_wmname { + char data[128]; + }; -Action + - Set the window name. Only printable characters are allowed, and by default non-ASCII characters are not allowed. -.. raw:: html + * - MSG_DOCK + - None + - Dock the window in the tray -
+ * - MSG_CURSOR + - .. code:: c -MSG_CLIPBOARD_DATA + struct msg_cursor { + uint32_t cursor; + }; -.. raw:: html + - Update cursor pointer for a window. Supported cursor IDs are default cursor (0) and `X Font cursors `__ (with 0x100 bit set). - + - Set the WM_CLASS property of a window. -amorphic blob (in protocol before 1.2, length determined by the “window” field, in 1.2 and later - by untrusted_len in the header) + * - MSG_WINDOW_DUMP + - .. code:: c -.. raw:: html + struct msg_window_dump_hdr { + uint32_t type; + uint32_t width; + uint32_t height; + uint32_t bpp; + }; - -Store the received clipboard content (not parsed in any way) + - Grant references that should be mapped into the compositing buffer. -.. raw:: html -
- -MSG_CREATE - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_create {
-     uint32_t x;
-     uint32_t y;
-     uint32_t width;
-     uint32_t height;
-     uint32_t parent;
-     uint32_t override_redirect;
-   };
-
- -.. raw:: html - - 		- -Create a window with given parameters - -.. raw:: html - -
- -MSG_DESTROY - -.. raw:: html - - - -None - -.. raw:: html - - - -Destroy a window - -.. raw:: html - -
- -MSG_MAP - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_map_info {
-     uint32_t transient_for;
-     uint32_t override_redirect;
-   };
-
- -.. raw:: html - - 		- -Map a window with given parameters - -.. raw:: html - -
- -MSG_UNMAP - -.. raw:: html - - - -None - -.. raw:: html - - - -Unmap a window - -.. raw:: html - -
- -MSG_CONFIGURE - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_configure {
-     uint32_t x;
-     uint32_t y;
-     uint32_t width;
-     uint32_t height;
-     uint32_t override_redirect;
-   };
-
- -.. raw:: html - - 		- -Change window position/size/type - -.. raw:: html - -
- -MSG_MFNDUMP - -.. raw:: html - - - -.. raw:: html - - 
-   struct shm_cmd {
-     uint32_t shmid;
-     uint32_t width;
-     uint32_t height;
-     uint32_t bpp;
-     uint32_t off;
-     uint32_t num_mfn;
-     uint32_t domid;
-     uint32_t mfns[0];
-   };
-
- -.. raw:: html - - 		- -Retrieve the array of mfns that constitute the composition buffer of a remote window. - -The “num_mfn” 32bit integers follow the shm_cmd structure; “off” is the offset of the composite buffer start in the first frame; “shmid” and “domid” parameters are just placeholders (to be filled by ``qubes-guid``), so that we can use the same structure when talking to ``shmoverride.so``. - -.. raw:: html - -
- -MSG_SHMIMAGE - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_shmimage {
-        uint32_t x;
-        uint32_t y;
-        uint32_t width;
-        uint32_t height;
-   };
-
- -.. raw:: html - - 		- -Repaint the given window fragment - -.. raw:: html - -
- -MSG_WMNAME - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_wmname {
-     char data[128];
-   };
-
- -.. raw:: html - - 		- -Set the window name. Only printable characters are allowed, and by default non-ASCII characters are not allowed. - -.. raw:: html - -
- -MSG_DOCK - -.. raw:: html - - - -None - -.. raw:: html - - - -Dock the window in the tray - -.. raw:: html - -
- -MSG_WINDOW_HINTS - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_window_hints {
-        uint32_t flags;
-        uint32_t min_width;
-        uint32_t min_height;
-        uint32_t max_width;
-        uint32_t max_height;
-        uint32_t width_inc;
-        uint32_t height_inc;
-        uint32_t base_width;
-        uint32_t base_height;
-   };
-
- -.. raw:: html - - 		- -Size hints for window manager - -.. raw:: html - -
- -MSG_WINDOW_FLAGS - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_window_flags {
-        uint32_t flags_set;
-        uint32_t flags_unset;
-   };
-
- -.. raw:: html - - 		- -Change window state request; fields contains bitmask which flags request to be set and which unset - -.. raw:: html - -
- -MSG_CURSOR - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_cursor {
-        uint32_t cursor;
-   };
-
- -.. raw:: html - - 		- -Update cursor pointer for a window. Supported cursor IDs are default cursor (0) and `X Font cursors `__ (with 0x100 bit set). - -.. raw:: html - -
- -MSG_WMCLASS - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_wmclass {
-       char res_class[64];
-       char res_name[64];
-   };
-
- -.. raw:: html - - 		- -Set the WM_CLASS property of a window. - -.. raw:: html - -
- -MSG_WINDOW_DUMP - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_window_dump_hdr {
-       uint32_t type;
-       uint32_t width;
-       uint32_t height;
-       uint32_t bpp;
-   };
-
- -.. raw:: html - - 		- -Header for shared memory dump command of type hdr.type. Currently only - -.. raw:: html - - 
WINDOW_DUMP_TYPE_GRANT_REFS
- -(0) is supported. - - .. raw:: html - -
- - WINDOW_DUMP_TYPE_GRANT_REFS - - .. raw:: html - - - - .. raw:: html - - 
-       struct msg_window_dump_grant_refs {
-           uint32_t refs[0];
-       };
-
- - .. raw:: html - - 		- - Grant references that should be mapped into the compositing buffer. - - .. raw:: html - -
GuiVM -> AppVM messages ----------------------- @@ -906,635 +300,126 @@ Each message starts with the following header The header is followed by message-specific data: -.. raw:: html +.. list-table:: + + * - Message name + - Structure after header + - Action + + * - MSG_KEYPRESS + - .. code:: c + + struct msg_keypress { + uint32_t type; + uint32_t x; + uint32_t y; + uint32_t state; + uint32_t keycode; + }; + + - Tell ``qubes_drv`` driver to generate a keypress + + * - MSG_BUTTON + - .. code:: c + struct msg_button { + uint32_t type; + uint32_t x; + uint32_t y; + uint32_t state; + uint32_t button; + }; + + - Tell ``qubes_drv`` driver to generate mouseclick + + * - MSG_MOTION + - .. code:: c + + struct msg_motion { + uint32_t x; + uint32_t y; + uint32_t state; + uint32_t is_hint; + }; + + - Tell ``qubes_drv`` driver to generate motion event + * - MSG_CONFIGURE + - .. code:: c + + struct msg_configure { + uint32_t x; + uint32_t y; + uint32_t width; + uint32_t height; + uint32_t override_redirect; + }; + + - Change window position/size/type + + * - MSG_MAP + - .. code:: c + + struct msg_map_info { + uint32_t transient_for; + uint32_t override_redirect; + }; + + - Map a window with given parameters + + * - MSG_CLOSE + - None + - send wmDeleteMessage to the window + + * - MSG_CROSSING + - .. code:: c + + struct msg_crossing { + uint32_t type; + uint32_t x; + uint32_t y; + uint32_t state; + uint32_t mode; + uint32_t detail; + uint32_t focus; + }; + + - Notify window about enter/leave event + + * - MSG_FOCUS + + - .. code:: c + + struct msg_focus { + uint32_t type; + uint32_t mode; + uint32_t detail; + }; + + - Raise a window, XSetInputFocus + + * - MSG_CLIPBOARD_REQ + - None + - Retrieve the local clipboard, pass contents to gui-daemon + + * - MSG_CLIPBOARD_DATA + - amorphic blob + - Insert the received data into local clipboard + + * - MSG_EXECUTE + - Obsolete + - Obsolete, unused + + * - MSG_KEYMAP_NOTIFY + - unsigned char remote_keys[32]; + - Synchronize the keyboard state (key pressed/released) with dom0 + + * - MSG_WINDOW_FLAGS + - .. code:: c - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - - - -.. raw:: html - -
- -Message name - -.. raw:: html - - - -Structure after header - -.. raw:: html - - - -Action - -.. raw:: html - -
- -MSG_KEYPRESS - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_keypress {
-     uint32_t type;
-     uint32_t x;
-     uint32_t y;
-     uint32_t state;
-     uint32_t keycode;
-   };
-
- -.. raw:: html - - 		- -Tell - -.. raw:: html - - 
qubes_drv
- -driver to generate a keypress - -.. raw:: html - -
- -MSG_BUTTON - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_button {
-     uint32_t type;
-     uint32_t x;
-     uint32_t y;
-     uint32_t state;
-     uint32_t button;
-   };
-
- -.. raw:: html - - 		- -Tell - -.. raw:: html - - 
qubes_drv
- -driver to generate mouseclick - -.. raw:: html - -
- -MSG_MOTION - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_motion {
-     uint32_t x;
-     uint32_t y;
-     uint32_t state;
-     uint32_t is_hint;
-   };
-
- -.. raw:: html - - 		- -Tell - -.. raw:: html - - 
qubes_drv
- -driver to generate motion event - -.. raw:: html - -
- -MSG_CONFIGURE - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_configure {
-     uint32_t x;
-     uint32_t y;
-     uint32_t width;
-     uint32_t height;
-     uint32_t override_redirect;
-   };
-
- -.. raw:: html - - 		- -Change window position/size/type - -.. raw:: html - -
- -MSG_MAP - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_map_info {
-     uint32_t transient_for;
-     uint32_t override_redirect;
-   };
-
- -.. raw:: html - - 		- -Map a window with given parameters - -.. raw:: html - -
- -MSG_CLOSE - -.. raw:: html - - - -None - -.. raw:: html - - - -send wmDeleteMessage to the window - -.. raw:: html - -
- -MSG_CROSSING - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_crossing {
-     uint32_t type;
-     uint32_t x;
-     uint32_t y;
-     uint32_t state;
-     uint32_t mode;
-     uint32_t detail;
-     uint32_t focus;
-   };
-
- -.. raw:: html - - 		- -Notify window about enter/leave event - -.. raw:: html - -
- -MSG_FOCUS - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_focus {
-     uint32_t type;
-     uint32_t mode;
-     uint32_t detail;
-   };
-
- -.. raw:: html - - 		- -Raise a window, XSetInputFocus - -.. raw:: html - -
- -MSG_CLIPBOARD_REQ - -.. raw:: html - - - -None - -.. raw:: html - - - -Retrieve the local clipboard, pass contents to gui-daemon - -.. raw:: html - -
- -MSG_CLIPBOARD_DATA - -.. raw:: html - - - -amorphic blob - -.. raw:: html - - - -Insert the received data into local clipboard - -.. raw:: html - -
- -MSG_EXECUTE - -.. raw:: html - - - -Obsolete - -.. raw:: html - - - -Obsolete, unused - -.. raw:: html - -
- -MSG_KEYMAP_NOTIFY - -.. raw:: html - - - -unsigned char remote_keys[32]; - -.. raw:: html - - - -Synchronize the keyboard state (key pressed/released) with dom0 - -.. raw:: html - -
- -MSG_WINDOW_FLAGS - -.. raw:: html - - - -.. raw:: html - - 
-   struct msg_window_flags {
-     uint32_t flags_set;
-     uint32_t flags_unset;
-   };
-
- -.. raw:: html - - 		- -Window state change confirmation - -.. raw:: html - -
+ struct msg_window_flags { + uint32_t flags_set; + uint32_t flags_unset; + }; + + - Window state change confirmation ``KEYPRESS``, ``BUTTON``, ``MOTION``, ``FOCUS`` messages pass information extracted from dom0 XEvent; see appropriate event documentation. diff --git a/user/templates/templates.rst b/user/templates/templates.rst index 941690d3..0cf9fccd 100644 --- a/user/templates/templates.rst +++ b/user/templates/templates.rst @@ -2,7 +2,6 @@ Templates ========= - In :doc:`Getting Started `, we covered the distinction in Qubes OS between where you *install* your software and where you *run* your software. Software that you use in most everyday tasks, is installed within :ref:`templates `. When using Qubes OS, you normally work in :ref:`app qubes `. App qubes are based on a *template* qube (or more simply, just *a template*). They inherit most of the `“root filesystem” `__, from the template. Changes you make to the root filesystem are not written back to the template: if you install an application in an app qube it will disappear when you shut down the qube. (You may be able to work round this by using Flatpak or snap packages, which install to the user’s home directory.) The user home directory *is* specific to the app qube, and changes there are kept. There is a full explanation of this `below <#inheritance-and-persistence>`__. If you use a :ref:`Standalone `, the **whole filesystem** is specific to the standalone, and every change you make will be kept after shutdown. @@ -17,8 +16,6 @@ The template system has significant benefits: - **Updates:** Updates are naturally centralized, since updating a template means that all qubes based on it will automatically use those updates after they’re restarted. - - An important side effect of this system is that any software installed in an app qube (rather than in the template on which it is based) will disappear when the app qube shuts down (see `Inheritance and Persistence <#inheritance-and-persistence>`__). For this reason, we recommend installing most of your software in templates, not app qubes. The default template in Qubes is based on Fedora, but there are additional templates based on other Linux distributions. There are also templates available with or without certain software preinstalled. You may find it useful to have multiple templates installed in order to provide: @@ -29,12 +26,9 @@ The default template in Qubes is based on Fedora, but there are additional templ - Different tools (e.g., office, media, development, hardware drivers) - - Official -------- - These are the official Qubes OS Project templates. We build and release updates for these templates. We guarantee that the binary updates are compiled from exactly the same source code as we publish. - :doc:`Fedora ` (default) @@ -49,14 +43,11 @@ These are the official Qubes OS Project templates. We build and release updates - :doc:`Debian Xfce ` - - You can see the current supported versions :ref:`here `. Community --------- - These templates are supported by the Qubes community. Some of them are available in ready-to-use binary package form (built by the Qubes developers), while others are available only in source code form. In all cases, the Qubes OS Project does not provide updates for these templates. However, such updates may be provided by the template maintainer. By installing these templates, you are trusting not only the Qubes developers and the distribution maintainers, but also the template maintainer. In addition, these templates may be somewhat less stable, since the Qubes developers do not test them. @@ -73,20 +64,16 @@ By installing these templates, you are trusting not only the Qubes developers an - :doc:`CentOS* ` - - \* *The CentOS version used by this template reached* `End-of-Life in June 2024 `__ *and is no longer receiving updates. Due to a lack of specific interest at this time a proposal to create a new CentOS 10 template was* `declined `__ *.* Windows ------- - Windows templates are constructed differently from Linux-based templates as Windows is a closed source system that can be modified only after installing. So it is not possible to provide preconfigured Windows templates for Qubes. The process of installing a Windows qube and connecting it to the Qubes environment via installing Qubes Windows Tools (QWT) is described in several chapters in :doc:`Windows qubes `. Installing ---------- - Certain templates come preinstalled with Qubes OS. However, there may be times when you wish to install a fresh template from the Qubes repositories, e.g.: - When a template version you’re using reaches :ref:`end-of-life `. @@ -97,8 +84,6 @@ Certain templates come preinstalled with Qubes OS. However, there may be times w - When you have made modifications to your template that you no longer want. - - You can manage your templates using the ``Qubes Template Manager``, a GUI tool available from the Qube menu. You can also use a command line tool in dom0 - ``qvm-template``. At the command line in dom0, ``qvm-template list --available`` will show available templates. To install a template, use: @@ -107,8 +92,6 @@ At the command line in dom0, ``qvm-template list --available`` will show availab $ qvm-template install - - You can also use ``qvm-template`` to upgrade or reinstall templates. Repository (repo) definitions are stored in dom0 in ``/etc/qubes/repo-templates`` and associated keys in ``/etc/qubes/repo-templates/keys``. There are additional repos for testing releases and community templates. To temporarily enable any of these repos, use the ``--enablerepo=`` option. E.g. : @@ -117,17 +100,14 @@ Repository (repo) definitions are stored in dom0 in ``/etc/qubes/repo-templates` $ qvm-template --enablerepo qubes-templates-community install - To permanently enable a repo, set the line ``enabled = 1`` in the repo definition in ``/etc/qubes/repo-templates``. To permanently disable, set the line to ``enabled = 0``. - If you wish to install a template that is in testing, please see :ref:`here `. After Installing ---------------- - After installing a fresh template, we recommend performing the following steps: 1. `Update the template <#updating>`__. @@ -136,30 +116,24 @@ After installing a fresh template, we recommend performing the following steps: 3. If desired, `uninstall the old template <#uninstalling>`__. - - Network access -------------- - For information about how templates access the network, please see :ref:`Why don’t templates have network access? ` and the :ref:`Updates proxy `. Updating -------- - Please see :doc:`How to Update `. Installing Software ------------------- - Please see :doc:`How to Install Software `. Uninstalling ------------ - To remove a template, the graphical ``Qube Manager`` (Qubes Menu > Qubes Tools > Qube Manager) may be used. Right-click the template to be uninstalled and click “Delete qube” to begin removal. If no issues are found, a dialog box will request the template’s name be typed as a final confirmation. Upon completion, the template will be deleted. Alternatively, to remove a template via the command line in dom0: @@ -168,16 +142,12 @@ Alternatively, to remove a template via the command line in dom0: $ qvm-template remove - - is the first column from the output of: .. code:: bash $ qvm-template list --installed - - In either case, issues with template removal may be raised. If an issue is raised, the template will remain installed and a list of concerns displayed. “Global property default_template” requires `switching <#switching>`__ the default_template property to another template. “Template for” can be resolved by `switching <#switching>`__ the dependent qubes’ template. Once the issues are addressed, attempt the removal again. If the template’s entry in the Qubes Menu is not removed with its uninstallation, consult the :ref:`troubleshooting page `. @@ -185,13 +155,11 @@ If the template’s entry in the Qubes Menu is not removed with its uninstallati Reinstalling ------------ - Please see :doc:`How to Reinstall a Template `. Switching --------- - When you install a new template or :ref:`upgrade ` a template, it is recommended that you switch everything that was using the old template to the new template: 1. **Make the new template the default template.** In the App Menu, go to Qubes Tools, then click on Qubes Global Settings. In the Qube Defaults section, next to Template, select the new template from the drop-down list. Press OK. @@ -201,45 +169,37 @@ When you install a new template or :ref:`upgrade `, or that USB qube is *not* a disposable, then shut down all disposables. In the App Menu, go to Qubes Tools, then click on Qube Manager. In the Qube Manager, find your disposable template(s). (By default, they end in ``-dvm``.) Right click, hover over Template, then click on the new template. Repeat for each disposable template. - If your only keyboard or mouse *are* connected through a USB qube, and that USB qube *is* a disposable, then you will have to enter a special command that shuts down all of your qubes, switches the USB qube’s disposable template to the new template, then starts the USB qube again. In order to avoid being locked out of your system, you must be very careful to enter this command without typos and with the correct substitutions. + In the App Menu, click on Terminal Emulator. Type the command below, substituting ```` with the name of the disposable template on which ``sys-usb`` is based, ```` with the name of the new template, and ```` with the name of your USB qube. Other than these substitutions, make sure to enter the command exactly as written. .. code:: bash qvm-shutdown --wait --all; qvm-prefs template ; qvm-start - With substitutions, your command should look similar to this example. (**Warning:** This is just an example. Do not attempt to use it.) .. code:: bash qvm-shutdown --wait --all; qvm-prefs fedora-01-dvm template fedora-02; qvm-start sys-usb - - - - 3. **Base your app qubes on the new template.** In the Qube Manager, click on the Template heading to sort by template. Select all the qubes based on the old template by clicking on the first one, holding shift, then clicking on the last one. With multiple qubes selected, right-click on any of them, hover your cursor over Template, then click on the new template. Or in the ``System`` menu select ``Manage templates for qubes``, select any qubes using the old template and update them to the new template using the drop down menu. 4. **Change the template for the default-mgmt-dvm** If the old template was used for management qubes, then you should change the template. This is an *internal* qube which does not appear by default in the Qube manager. In the ``System`` menu select ``Manage templates for qubes``, and you will see the *default-mgmt-dvm* qube. Change the template used for this disposable template to the new template. - - Advanced -------- - The following sections cover advanced topics pertaining to templates. Inheritance and persistence ^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Whenever an app qube is created, the contents of the ``/home`` directory of its parent template are *not* copied to the child app qube’s ``/home``. The child app qube’s ``/home`` is always independent from its parent template’s ``/home``, which means that any subsequent changes to the parent template’s ``/home`` will not affect the child app qube’s ``/home``. Once an app qube has been created, any changes in its ``/home``, ``/usr/local``, or ``/rw/config`` directories will be persistent across reboots, which means that any files stored there will still be available after restarting the app qube. No changes in any other directories in app qubes persist in this manner. If you would like to make changes in other directories which *do* persist in this manner, you must make those changes in the parent template. -.. list-table:: - :widths: 44 44 44 +.. list-table:: + :widths: 44 44 44 :align: center :header-rows: 1 @@ -255,17 +215,15 @@ Once an app qube has been created, any changes in its ``/home``, ``/usr/local``, * - :ref:`disposable ` - ``/rw`` (includes ``/home``, ``/usr/local``, and ``bind-dirs``) - nothing - + | :superscript:`1` Upon creation | :superscript:`2` Following shutdown | :superscript:`3` Includes :ref:`disposable templates ` - Trusting your templates ^^^^^^^^^^^^^^^^^^^^^^^ - As the template is used for creating filesystems for other app qubes where you actually do the work, it means that the template is as trusted as the most trusted app qube based on this template. In other words, if your template gets compromised, e.g. because you installed an application, whose *installer’s scripts* were malicious, then *all* your app qubes (based on this template) will inherit this compromise. There are several ways to deal with this problem: @@ -276,8 +234,6 @@ There are several ways to deal with this problem: - Use multiple templates (see below) for different classes of domains, e.g. a less trusted template, used for creation of less trusted app qubes, would get various packages from less trusted vendors, while the template used for more trusted app qubes will only get packages from the standard Fedora repos. - - Some popular questions: So, why should we actually trust Fedora repos – it also contains large amount of third-party software that might be buggy, right? @@ -295,7 +251,6 @@ Not quite. Dom0 compromise is absolutely fatal, and it leads to Game Over :super Note on treating app qubes' root filesystem non-persistence as a security feature ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - Any app qube that is based on a template has its root filesystem non-persistent across qube reboots. In other words, whatever changes the qube makes (or the malware running in this qube makes) to its root filesystem, are automatically discarded whenever one restarts the qube. This might seem like an excellent anti-malware mechanism to be used inside the qube. However, one should be careful with treating this property as a reliable way to keep the qube malware-free. This is because the non-persistence, in the case of normal qubes, applies only to the root filesystem and not to the user filesystem (on which the ``/home``, ``/rw``, and ``/usr/local`` are stored) for obvious reasons. It is possible that malware, especially malware that could be specifically written to target Qubes, could install its hooks inside the user home directory files only. Examples of obvious places for such hooks could be: ``.bashrc``, the Firefox profile directory which contains the extensions, or some PDF or DOC documents that are expected to be opened by the user frequently (assuming the malware found an exploitable bug in the PDF or DOC reader), and surely many others places, all in the user’s home directory. @@ -307,11 +262,9 @@ Also note that disposable qubes do not have persistent user filesystem, and so t Important Notes ^^^^^^^^^^^^^^^ - - ``qvm-trim-template`` is no longer necessary or available in Qubes 4.0 and higher. All qubes are created in a thin pool and trimming is handled automatically. No user action is required. See `Disk Trim `__ for more information. - RPM-installed templates are “system managed” and therefore cannot be backed up using Qubes’ built-in backup function. In order to ensure the preservation of your custom settings and the availability of a “known-good” backup template, you may wish to clone the default system template and use your clone as the default template for your app qubes. - Some templates are available in ready-to-use binary form, but some of them are available only as source code, which can be built using the `Qubes Builder `__. In particular, some template “flavors” are available in source code form only. For the technical details of the template system, please see :doc:`Template Implementation `. Take a look at the :doc:`Qubes Builder ` documentation for instructions on how to compile them. -