From 8489fcc4fa09b8b849331a4855315d4d7c0024d6 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 01/24] 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. - From db47feb2393a11566a375af4ddb977bbad45050e Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Fri, 1 Aug 2025 16:36:32 -0400 Subject: [PATCH 02/24] Fix some missing code blocks inside lists --- user/templates/windows/windows-qubes-4-0.rst | 7 +- user/troubleshooting/uefi-troubleshooting.rst | 71 ++++++++++--------- 2 files changed, 44 insertions(+), 34 deletions(-) diff --git a/user/templates/windows/windows-qubes-4-0.rst b/user/templates/windows/windows-qubes-4-0.rst index 489a8c11..b54f1199 100644 --- a/user/templates/windows/windows-qubes-4-0.rst +++ b/user/templates/windows/windows-qubes-4-0.rst @@ -99,9 +99,12 @@ Installation procedure: - Install on first disk. - - Windows license may be read from flash via root in dom0: - ``strings < /sys/firmware/acpi/tables/MSDM`` + - Windows license may be read from flash via root in dom0:: + + strings < /sys/firmware/acpi/tables/MSDM + Alternatively, you can also try a Windows 7 license key (as of 2018/11 they are still accepted for a free upgrade). + I first installed Windows and all updates, then entered the license key. diff --git a/user/troubleshooting/uefi-troubleshooting.rst b/user/troubleshooting/uefi-troubleshooting.rst index 05a05d7a..04204fb9 100644 --- a/user/troubleshooting/uefi-troubleshooting.rst +++ b/user/troubleshooting/uefi-troubleshooting.rst @@ -2,11 +2,9 @@ UEFI troubleshooting ==================== - Successfully installed in legacy mode, but had to change some xen parameters ---------------------------------------------------------------------------- - **Note**: If you make changes, you must boot from “Partition 1” explicitly from UEFI boot menu. **Change the xen configuration on a USB media** @@ -19,14 +17,10 @@ Successfully installed in legacy mode, but had to change some xen parameters vi EFI/BOOT/grub.cfg - - 3. Change the ``multiboot2 /images/pxeboot/xen.gz`` line to add your xen parameters on the boot entry of your choice 4. Install using your modified boot entry - - **Change xen configuration directly in an iso image** 1. Set up a loop device (replacing ``X`` with your ISO’s version name): ``losetup -P /dev/loop0 Qubes-RX-x86_64.iso`` @@ -37,24 +31,19 @@ Successfully installed in legacy mode, but had to change some xen parameters 4. Save your changes, unmount and dd to usb device - - Installation freezes before displaying installer ------------------------------------------------ - If you have an Nvidia card, see also `Nvidia Troubleshooting `__. Installation from USB stick hangs on black screen ------------------------------------------------- - Some laptops cannot read from an external boot device larger than 8GB. If you encounter a black screen when performing an installation from a USB stick, ensure you are using a USB drive less than 8GB, or a partition on that USB lesser than 8GB and of format FAT32. Installation completes successfully but then system crash/restarts on next boot ------------------------------------------------------------------------------- - Some Dell systems and probably others have `another bug in UEFI firmware `__. These systems need ``efi=attr=uc`` enabled at all times. Although this is enabled by default in the installer, it is disabled after the first stage of a successful install. You can re-enable it either as part of the install process: 1. Perform installation normally, but don’t reboot the system at the end yet. @@ -67,21 +56,36 @@ Some Dell systems and probably others have `another bug in UEFI firmware ` 2. Press ‘3’ to go to the shell -3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk name. If unsure, use the ``lsblk`` command to display a list of disks): ``fdisk -l /dev/sda | grep EFI`` The output should look like this: ``/dev/sda1 2048 1230847 1228800 600M EFI System`` Then mount it: ``mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi`` +3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk + name. If unsure, use the ``lsblk`` command to display a list of disks): + + .. code:: console + + fdisk -l /dev/sda | grep EFI + + The output should look like this: + + .. code:: output + + /dev/sda1 2048 1230847 1228800 600M EFI System + + Then mount it: + + .. code:: console + + mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi + + 4. Execute: @@ -89,25 +93,38 @@ Or if you have already rebooted after the first stage install and have encounter sed -i -e 's/ucode=scan/\0 efi=attr=uc/' /mnt/sysimage/boot/efi/EFI/qubes/grub.cfg - - 5. Type ``reboot``. 6. Continue with setting up default templates and logging in to Qubes. - - Boot device not recognized after installing ------------------------------------------- - Some firmware will not recognize the default Qubes EFI configuration. As such, it will have to be manually edited to be bootable. 1. Boot Qubes OS install media into :ref:`rescue mode ` 2. Press ‘3’ to go to the shell -3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk name. If unsure, use the ``lsblk`` command to display a list of disks): ``fdisk -l /dev/sda | grep EFI`` The output should look like this: ``/dev/sda1 2048 1230847 1228800 600M EFI System`` Then mount it: ``mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi`` +3. Find and mount the EFI system partition. (replace ``/dev/sda`` with your disk name. If unsure, use the ``lsblk`` command to display a list of disks): + + .. code:: console + + fdisk -l /dev/sda | grep EFI + + The output should look like this: + + .. code:: output + + /dev/sda1 2048 1230847 1228800 600M EFI System + + Then mount it: + + .. code:: console + + mkdir -p /mnt/sysimage/boot/efi mount /dev/sda1 /mnt/sysimage/boot/efi + + 4. Copy ``grubx64.efi`` to the fallback path: @@ -115,16 +132,11 @@ Some firmware will not recognize the default Qubes EFI configuration. As such, i cp /mnt/sysimage/boot/efi/EFI/qubes/grubx64.efi /mnt/sysimage/boot/efi/EFI/BOOT/bootx64.efi - - 5. Type ``reboot`` - - "Qubes" boot option is missing after removing / attaching a disk or updating the BIOS ------------------------------------------------------------------------------------- - 1. Boot Qubes OS install media into :ref:`rescue mode ` 2. Press ‘3’ to go to the shell @@ -135,12 +147,7 @@ Some firmware will not recognize the default Qubes EFI configuration. As such, i efibootmgr -v -c -u -L Qubes -l /EFI/qubes/grubx64.efi -d /dev/sda -p 1 - - - - Accessing installer Rescue mode on UEFI --------------------------------------- - Choose “Rescue a Qubes OS system” from grub2 boot menu. From c5a053d12e8131ded2b5dfc8381811bb30659188 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sat, 9 Aug 2025 17:43:10 -0400 Subject: [PATCH 03/24] Fix missing cell in table --- developer/system/gui.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/developer/system/gui.rst b/developer/system/gui.rst index 2f67ddf9..42831de6 100644 --- a/developer/system/gui.rst +++ b/developer/system/gui.rst @@ -321,6 +321,7 @@ The header is followed by message-specific data: * - MSG_BUTTON - .. code:: c + struct msg_button { uint32_t type; uint32_t x; From 9e5fa7a38709b0cc723173d814bfc725e27e7174 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 8 Aug 2025 22:51:05 +0200 Subject: [PATCH 04/24] ci: remove gitlab ci RTD provides own CI service --- .gitlab-ci.yml | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 .gitlab-ci.yml diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml deleted file mode 100644 index 094c57d5..00000000 --- a/.gitlab-ci.yml +++ /dev/null @@ -1,6 +0,0 @@ -include: - - project: 'QubesOS/qubes-continuous-integration' - file: '/gitlab-website.yml' - -build:doc: - extends: .website From 4fa0d293bd131d2d54699e5b88ea0badc3793536 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Thu, 31 Jul 2025 02:35:23 -0400 Subject: [PATCH 05/24] Remove duplicate captions and wrong alt formatting of images --- developer/services/qrexec.rst | 2 -- user/advanced-topics/standalones-and-hvms.rst | 4 ---- user/how-to-guides/how-to-install-software.rst | 4 ++-- 3 files changed, 2 insertions(+), 8 deletions(-) diff --git a/developer/services/qrexec.rst b/developer/services/qrexec.rst index 9edcdc2f..61ca9c90 100644 --- a/developer/services/qrexec.rst +++ b/developer/services/qrexec.rst @@ -16,8 +16,6 @@ Qrexec is built on top of *vchan*, a Xen library providing data links between VM .. figure:: /attachment/doc/qrexec3-basics.png :alt: qrexec basics diagram - qrexec basics diagram - The ``qrexec-client`` command is used to make connections to VMs from dom0. For example, the following command creates an empty file called ``hello-world.txt`` in the home folder of ``someVM``: .. code:: bash diff --git a/user/advanced-topics/standalones-and-hvms.rst b/user/advanced-topics/standalones-and-hvms.rst index e79c7578..6afacbf9 100644 --- a/user/advanced-topics/standalones-and-hvms.rst +++ b/user/advanced-topics/standalones-and-hvms.rst @@ -172,8 +172,6 @@ Every guest operating system has its own way of handling networking, and the use .. figure:: /attachment/doc/EndeavourOS_Network.png :alt: Image of Qube Settings - Image of Qube Settings - In this example, Network Manager on KDE, the network had the following values: 1. IPv4 networking @@ -191,8 +189,6 @@ In this example, Network Manager on KDE, the network had the following values: .. figure:: /attachment/doc/Network_Manager.png :alt: Image of Network Manager, annotated by numbers for reference below - Image of Network Manager, annotated by numbers for reference below - The network was set up by entering Network Manager, selecting the Wi-Fi & Networking tab, clicking on the Wired Ethernet item, and selecting tab IPv4 (1). The Manual method was selected (2), which revealed areas for data entry. The DNS Servers section takes a comma-separated list, here 10.139.1.1,10.1.139.2 (3). At the bottom of the tab (4), the ‘+ Add’ button was selected, and the IP address of 10.137.0.17 entered in the ‘Address’ column, the Netmask of 255.255.255.0 entered in the ‘Netmask’ column, and the Gateway of 10.138.24.248 under ‘Gateway’. Selecting the “Apply” button stored these changes Using template-based HVMs diff --git a/user/how-to-guides/how-to-install-software.rst b/user/how-to-guides/how-to-install-software.rst index cb41b3e0..c35d6104 100644 --- a/user/how-to-guides/how-to-install-software.rst +++ b/user/how-to-guides/how-to-install-software.rst @@ -34,7 +34,7 @@ Installing software from default repositories .. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png - :alt: `The Applications tab in Qube Settings `__ + :alt: The Applications tab in Qube Settings @@ -89,7 +89,7 @@ This method assumes that you are trying to follow instructions to install some p .. figure:: /attachment/doc/r4.1-dom0-appmenu-select.png - :alt: `The Applications tab in Qube Settings `__ + :alt: The Applications tab in Qube Settings From 1f331a4f002c13a22afc746dacb64dda148038f4 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sun, 27 Jul 2025 03:48:05 -0400 Subject: [PATCH 06/24] Introduction: correct an image position --- introduction/intro.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/introduction/intro.rst b/introduction/intro.rst index adbf4f26..fcb6beb6 100644 --- a/introduction/intro.rst +++ b/introduction/intro.rst @@ -10,7 +10,7 @@ single-user desktop computing. Qubes OS `leverages Xen-based virtualization `, have specific: - + - **Purposes:** with a predefined set of one or many isolated applications, for personal or professional projects, to manage the :doc:`network stack `, :doc:`the firewall `, or to fulfill other @@ -20,7 +20,7 @@ These qubes, which are implemented as :ref:`virtual machines (VMs)` virtual machines based on popular operating systems, such as :doc:`Fedora `, :doc:`Debian `, and `Windows `__. - + - **Levels of trust:** from complete to non-existent. All windows are displayed in a unified desktop environment with :doc:`unforgeable colored window borders ` so that different security levels are easily identifiable. @@ -47,7 +47,7 @@ Features - **Multiple operating systems** Use multiple operating systems at the same time, including :doc:`Fedora `, :doc:`Debian `, and `Windows `__ - + - **Disposables** Create :doc:`disposables ` on the fly that self-destruct when shut down. - **Whonix integration** Run `Tor `__ securely system-wide using `Whonix with Qubes `__. @@ -98,10 +98,6 @@ and data across these compartments. Qubes allows you to compartmentalize your digital life ------------------------------------------------------ -.. figure:: /attachment/site/qubes-partition-data-flows.jpg - :alt: Compartmentalization example - - Many of us are initially surprised to learn that our devices do not support the kind of secure compartmentalization that our lives demand, and we're disappointed that software vendors rely on generic defenses that @@ -125,6 +121,8 @@ physical computer without having to worry about a single successful cyberattack taking down your entire digital life in one fell swoop. In fact, Qubes has `distinct advantages over physical air gaps `__. +.. figure:: /attachment/site/qubes-partition-data-flows.jpg + :alt: Compartmentalization example Made to support vulnerable users and power users alike ------------------------------------------------------ @@ -139,7 +137,7 @@ plug in devices, and install software free from worry. It's a place where **you** have control over your software, not the other way around. (See some :doc:`examples of how different types of users organize their qubes `.) -Qubes is also powerful. Organizations like the `Freedom of the Press Foundation `__, +Qubes is also powerful. Organizations like the `Freedom of the Press Foundation `__, `Mullvad `__, and `Let's Encrypt `__ rely on Qubes as they build and maintain critical privacy and From acc9a5f27de973d29020a97ed24425be8d6eba96 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sat, 2 Aug 2025 07:54:58 -0400 Subject: [PATCH 07/24] Fix Xen link on intro.rst --- introduction/intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/introduction/intro.rst b/introduction/intro.rst index fcb6beb6..02c58b60 100644 --- a/introduction/intro.rst +++ b/introduction/intro.rst @@ -6,7 +6,7 @@ What is Qubes OS? ----------------- Qubes OS is a free and open-source, security-oriented operating system for -single-user desktop computing. Qubes OS `leverages Xen-based virtualization `__ to allow for the creation and management of isolated compartments called :ref:`qubes `. +single-user desktop computing. Qubes OS leverages `Xen-based virtualization `__ to allow for the creation and management of isolated compartments called :ref:`qubes `. These qubes, which are implemented as :ref:`virtual machines (VMs)`, have specific: From 4ebc721ef82f074aac8e4cf70ced9bc0a1cc9700 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Fri, 1 Aug 2025 11:06:15 -0400 Subject: [PATCH 08/24] Cleanup sphinx and readthedocs configurations * Use dirhtml as default builder for readthedocs (clean URLs) * The configuration variables are now sorted with respect to the Sphinx documentation * Remove useless comments in conf.py * Add new comments for each section, following Sphinx documentation order * The code corresponding to videos have been moved from config to a dedicated extension. * Use proper HTML theme options * Exclude all files starting with `.`, `_` (sphinx convention) * Use OpenSearch --- .readthedocs.yaml | 2 +- _ext/__init__.py | 0 _ext/videos.py | 68 ++++++++++++++++++++ conf.py | 159 +++++++++++++++++++--------------------------- 4 files changed, 134 insertions(+), 95 deletions(-) create mode 100644 _ext/__init__.py create mode 100644 _ext/videos.py diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9a52b135..9d7570ed 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,7 +10,7 @@ submodules: recursive: true sphinx: - builder: html + builder: dirhtml configuration: conf.py fail_on_warning: false diff --git a/_ext/__init__.py b/_ext/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/_ext/videos.py b/_ext/videos.py new file mode 100644 index 00000000..033727c5 --- /dev/null +++ b/_ext/videos.py @@ -0,0 +1,68 @@ +""" + ReST directive for embedding Youtube and Vimeo videos. + + There are two directives added: ``youtube`` and ``vimeo``. The only + argument is the video id of the video to include. + Both directives have three optional arguments: ``height``, ``width`` + and ``align``. Default height is 281 and default width is 500. + + Example:: + + .. youtube:: anwy2MPT5RE + :height: 315 + :width: 560 + :align: left + + :copyright: (c) 2012 by Danilo Bargen. + :license: BSD 3-clause + + From https://gist.github.com/ehles/bed012d78aad5d3cd6c35a49bef32f9f +""" +from __future__ import absolute_import +from docutils import nodes +from docutils.parsers.rst import Directive, directives + +def align(argument): + """Conversion function for the "align" option.""" + return directives.choice(argument, ('left', 'center', 'right')) + + +class IframeVideo(Directive): + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'height': directives.nonnegative_int, + 'width': directives.nonnegative_int, + 'align': align, + } + default_width = 500 + default_height = 281 + + def run(self): + self.options['video_id'] = directives.uri(self.arguments[0]) + if not self.options.get('width'): + self.options['width'] = self.default_width + if not self.options.get('height'): + self.options['height'] = self.default_height + if not self.options.get('align'): + self.options['align'] = 'left' + return [nodes.raw('', self.html % self.options, format='html')] + + +class GeneralVid(IframeVideo): + html = '' + + +class Youtube(IframeVideo): + html = '' + + +def setup(builder): + directives.register_directive('youtube', Youtube) + directives.register_directive('generalvid', GeneralVid) + diff --git a/conf.py b/conf.py index 85f31d1e..450a1629 100644 --- a/conf.py +++ b/conf.py @@ -1,133 +1,104 @@ -""" - ReST directive for embedding Youtube and Vimeo videos. - There are two directives added: ``youtube`` and ``vimeo``. The only - argument is the video id of the video to include. - Both directives have three optional arguments: ``height``, ``width`` - and ``align``. Default height is 281 and default width is 500. - Example:: - .. youtube:: anwy2MPT5RE - :height: 315 - :width: 560 - :align: left - :copyright: (c) 2012 by Danilo Bargen. - :license: BSD 3-clause -""" -from __future__ import absolute_import -from docutils import nodes -from docutils.parsers.rst import Directive, directives +"""qubes-doc configuration file""" + +import os +import sys +from pathlib import Path + +sys.path.append(str(Path('_ext').resolve())) + +# For the full list of options, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + # -- Project information ----------------------------------------------------- project = 'Qubes OS' -copyright = '2025, Qubes OS Project' author = 'Qubes OS Project' +copyright = f'%Y, {author}' -title = "Qubes Docs" -html_title = "Qubes Docs" +# Warning: Sphinx's version and release differ from Qubes OS ! + +# The major project version, used as the replacement for the |version| default +# substitution. i.e. '4.3' +version = '4.2' # The full version, including alpha/beta/rc tags -release = '4.3' +release = '4.2.4' + # -- General configuration --------------------------------------------------- -html_static_path = ['attachment/doc'] extensions = [ 'sphinx.ext.autosectionlabel', 'sphinxnotes.strike', - 'sphinx_reredirects' + 'sphinx_reredirects', + 'videos', ] redirects = { - "user/hardware/hcl": "https://www.qubes-os.org/hcl/", - "user/downloading-installing-upgrading/downloads:mirrors":"https://www.qubes-os.org/downloads/mirrors/", - "developer/general/visual-style-guide": "https://www.qubes-os.org/doc/visual-style-guide/", - "developer/general/website-style-guide":"https://www.qubes-os.org/doc/website-style-guide/", - "user/downloading-installing-upgrading/downloads":"https://www.qubes-os.org/downloads/", - "developer/general/how-to-edit-the-documentation":"https://www.qubes-os.org/doc/how-to-edit-the-documentation/" + "user/hardware/hcl": + "https://www.qubes-os.org/hcl/", + "user/downloading-installing-upgrading/downloads:mirrors": + "https://www.qubes-os.org/downloads/mirrors/", + "developer/general/visual-style-guide": + "https://www.qubes-os.org/doc/visual-style-guide/", + "developer/general/website-style-guide": + "https://www.qubes-os.org/doc/website-style-guide/", + "user/downloading-installing-upgrading/downloads": + "https://www.qubes-os.org/downloads/", + "developer/general/how-to-edit-the-documentation": + "https://www.qubes-os.org/doc/how-to-edit-the-documentation/", } -autosectionlabel_prefix_document = True -source_suffix = { - '.rst': 'restructuredtext', -} -templates_path = ['_templates'] +# -- -- Options for highlighting --------------------------------------------- + +highlight_language = 'none' + + +# -- -- Options for source files --------------------------------------------- -root_doc = "index" exclude_patterns = [ - '_dev/*', - 'attachment/*', + '_*', + '**/.*', '**/*.txt' + 'attachment', ] + +# -- Builder options --------------------------------------------------------- + +# -- -- Options for HTML output ---------------------------------------------- + html_theme = 'sphinx_rtd_theme' -# html_theme = 'default' -# html_theme = 'classic' + +html_title = f'{project} {release} Documentation' html_theme_options = { - 'externalrefs': True, - 'bgcolor': 'white', - 'linkcolor': '#99bfff', - 'textcolor': '#000000', - 'visitedlinkcolor': '#7b7b7b', - 'bodyfont': '"Open Sans", Arial, sans-serif', - 'codebgcolor': '$color-qube-light', - 'codebgcolor': 'grey', + 'style_external_links': True, 'body_min_width': '50%', 'body_max_width': '90%', 'collapse_navigation': True, } -gettext_uuid = True -gettext_compact = False +html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/") -# epub_show_urls = 'footnote' -# latex_show_urls ='footnote' +html_static_path = ['attachment/doc'] +html_use_opensearch = "https://doc.qubes-os.org" + + +# -- Extensions configuration ------------------------------------------------ + +autosectionlabel_prefix_document = True + + +# -- HTML configuration ------------------------------------------------------ + +# -- -- Options for internationalisation ------------------------------------- locale_dirs = ['_translated'] -# from https://gist.github.com/ehles/bed012d78aad5d3cd6c35a49bef32f9f -def align(argument): - """Conversion function for the "align" option.""" - return directives.choice(argument, ('left', 'center', 'right')) +gettext_compact = False - -class IframeVideo(Directive): - has_content = False - required_arguments = 1 - optional_arguments = 0 - final_argument_whitespace = False - option_spec = { - 'height': directives.nonnegative_int, - 'width': directives.nonnegative_int, - 'align': align, - } - default_width = 500 - default_height = 281 - - def run(self): - self.options['video_id'] = directives.uri(self.arguments[0]) - if not self.options.get('width'): - self.options['width'] = self.default_width - if not self.options.get('height'): - self.options['height'] = self.default_height - if not self.options.get('align'): - self.options['align'] = 'left' - return [nodes.raw('', self.html % self.options, format='html')] - - -class GeneralVid(IframeVideo): - html = '' - - -class Youtube(IframeVideo): - html = '' - - -def setup(builder): - directives.register_directive('youtube', Youtube) - directives.register_directive('generalvid', GeneralVid) +gettext_uuid = True From 2531253dce4694e16d894efc1d48ebae680c7395 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Mon, 4 Aug 2025 16:02:36 -0400 Subject: [PATCH 09/24] Add minimal configuration for linkcheck builder * Avoid checking .onion domains. * Do not download links to check anchors --- conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/conf.py b/conf.py index 450a1629..7688c666 100644 --- a/conf.py +++ b/conf.py @@ -87,6 +87,10 @@ html_static_path = ['attachment/doc'] html_use_opensearch = "https://doc.qubes-os.org" +# -- -- Options for the linkcheck builder ------------------------------------ + +linkcheck_anchors = False +linkcheck_ignore = [r'^https?://[^/\s]+\.onion'] # -- Extensions configuration ------------------------------------------------ From f5a660954d0b2d67acf89cf93bf5ec49effc49b5 Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Mon, 4 Aug 2025 16:14:43 -0400 Subject: [PATCH 10/24] Ignore the _build directory --- .gitignore | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +_build From d5418827332a40309b052503c6d3fdc9601be79c Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Tue, 12 Aug 2025 09:25:54 -0400 Subject: [PATCH 11/24] Revert some configuration options * reuse html builder * rename videos extension to youtube_frame * remove HTML body max/min parameters * remove reference to release number in HTML title --- .readthedocs.yaml | 2 +- _ext/__init__.py | 0 _ext/{videos.py => youtube_frame.py} | 0 conf.py | 6 ++---- 4 files changed, 3 insertions(+), 5 deletions(-) delete mode 100644 _ext/__init__.py rename _ext/{videos.py => youtube_frame.py} (100%) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 9d7570ed..9a52b135 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,7 +10,7 @@ submodules: recursive: true sphinx: - builder: dirhtml + builder: html configuration: conf.py fail_on_warning: false diff --git a/_ext/__init__.py b/_ext/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/_ext/videos.py b/_ext/youtube_frame.py similarity index 100% rename from _ext/videos.py rename to _ext/youtube_frame.py diff --git a/conf.py b/conf.py index 7688c666..d61ea863 100644 --- a/conf.py +++ b/conf.py @@ -32,7 +32,7 @@ extensions = [ 'sphinx.ext.autosectionlabel', 'sphinxnotes.strike', 'sphinx_reredirects', - 'videos', + 'youtube_frame', ] redirects = { @@ -72,12 +72,10 @@ exclude_patterns = [ html_theme = 'sphinx_rtd_theme' -html_title = f'{project} {release} Documentation' +html_title = f'{project} Documentation' html_theme_options = { 'style_external_links': True, - 'body_min_width': '50%', - 'body_max_width': '90%', 'collapse_navigation': True, } From fa7a62b52924479e1ac316b9eed514def849708c Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Sun, 27 Jul 2025 02:03:08 -0400 Subject: [PATCH 12/24] Use console lexer instead of bash with a prompt --- developer/building/development-workflow.rst | 4 +- developer/building/qubes-builder-v2.rst | 47 +++++++++++-------- developer/building/qubes-iso-building.rst | 2 +- developer/code/code-signing.rst | 4 +- developer/debugging/automated-tests.rst | 4 +- developer/debugging/mount-lvm-image.rst | 12 ++--- developer/debugging/safe-remote-ttys.rst | 6 +-- developer/services/qrexec.rst | 22 ++++----- developer/services/qrexec2.rst | 4 +- introduction/faq.rst | 4 +- project-security/security-pack.rst | 4 +- project-security/verifying-signatures.rst | 44 ++++++++--------- user/advanced-topics/awesomewm.rst | 4 +- .../disposable-customization.rst | 18 +++---- .../how-to-install-software-in-dom0.rst | 2 +- user/advanced-topics/i3.rst | 14 +++--- user/advanced-topics/kde.rst | 6 +-- user/advanced-topics/managing-vm-kernels.rst | 18 +++---- user/advanced-topics/rpc-policy.rst | 2 +- user/advanced-topics/salt.rst | 24 +++++----- user/advanced-topics/standalones-and-hvms.rst | 6 +-- .../installation-guide-4.1.rst | 2 +- .../installation-guide.rst | 2 +- .../upgrade/2b2.rst | 2 +- .../upgrade/3_0.rst | 2 +- .../backup-emergency-restore-v2.rst | 14 +++--- .../backup-emergency-restore-v3.rst | 20 ++++---- .../backup-emergency-restore-v4.rst | 32 ++++++------- .../how-to-back-up-restore-and-migrate.rst | 2 +- .../how-to-guides/how-to-install-software.rst | 14 +++--- user/how-to-guides/how-to-update.rst | 6 +-- user/security-in-qubes/ctap-proxy.rst | 6 +-- user/security-in-qubes/firewall.rst | 18 +++---- user/security-in-qubes/firewall_4.1.rst | 12 ++--- user/security-in-qubes/split-gpg.rst | 24 +++++----- user/templates/debian/debian-upgrade.rst | 22 ++++----- user/templates/debian/debian.rst | 2 +- user/templates/fedora/fedora-upgrade.rst | 26 +++++----- user/templates/fedora/fedora.rst | 2 +- user/templates/minimal-templates.rst | 12 ++--- user/templates/templates.rst | 8 ++-- .../windows/qubes-windows-tools-4-0.rst | 4 +- .../windows/qubes-windows-tools-4-1.rst | 14 +++--- user/templates/xfce-templates.rst | 8 ++-- .../app-menu-shortcut-troubleshooting.rst | 12 ++--- user/troubleshooting/disk-troubleshooting.rst | 2 +- .../installation-troubleshooting.rst | 2 +- .../resume-suspend-troubleshooting.rst | 14 +++--- user/troubleshooting/vm-troubleshooting.rst | 8 ++-- 49 files changed, 276 insertions(+), 267 deletions(-) diff --git a/developer/building/development-workflow.rst b/developer/building/development-workflow.rst index 64e546d8..9a7c61d6 100644 --- a/developer/building/development-workflow.rst +++ b/developer/building/development-workflow.rst @@ -17,7 +17,7 @@ The best way to write and contribute code is to create a git repo somewhere (e.g **Example:** -.. code:: bash +.. code:: console $ cd qubes-builder/artifacts/sources/qubes-manager $ git remote add abel git@GitHub.com:abeluck/qubes-manager.git @@ -290,7 +290,7 @@ You will also need to setup qrexec policy in dom0 (``/etc/qubes-rpc/policy/local Usage: -.. code:: bash +.. code:: console [user@source core-agent-linux]$ git remote add testbuilder "ext::git-qrexec testbuilder 3 core-agent-linux" [user@source core-agent-linux]$ git push testbuilder master diff --git a/developer/building/qubes-builder-v2.rst b/developer/building/qubes-builder-v2.rst index 7e297a0f..34995e19 100644 --- a/developer/building/qubes-builder-v2.rst +++ b/developer/building/qubes-builder-v2.rst @@ -2,6 +2,7 @@ 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 `__. @@ -9,11 +10,13 @@ For details and customization, use `Qubes OS v2 builder documentation ` for more info): -.. code:: bash +.. code:: console $ sudo dnf install git createrepo rpm-build rpm-sign make python3-sh rpmdevtools rpm-sign dialog perl-open python3-pyyaml perl-Digest-MD5 perl-Digest-SHA diff --git a/developer/code/code-signing.rst b/developer/code/code-signing.rst index 27e496dd..9e786523 100644 --- a/developer/code/code-signing.rst +++ b/developer/code/code-signing.rst @@ -13,7 +13,7 @@ Generating a Key Alex Cabal has written an excellent `guide `__ on creating a PGP keypair. Below, we reproduce just the minimum steps in generating a keypair using GnuPG. Please read Cabal’s full guide for further important details. -.. code:: bash +.. code:: console $ gpg --gen-key gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc. @@ -75,7 +75,7 @@ Replace 6E2F4E7AF50A5827 with your key ID, preferably the **long keyID** which i -.. code:: bash +.. code:: console $ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827 gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com diff --git a/developer/debugging/automated-tests.rst b/developer/debugging/automated-tests.rst index 3240fca9..8a4cfabd 100644 --- a/developer/debugging/automated-tests.rst +++ b/developer/debugging/automated-tests.rst @@ -39,7 +39,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a You can use ``python3 -m qubes.tests.run -h`` to get usage information: -.. code:: bash +.. code:: console [user@dom0 ~]$ python3 -m qubes.tests.run -h usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast] @@ -82,7 +82,7 @@ You can use ``python3 -m qubes.tests.run -h`` to get usage information: For instance, to run only the tests for the fedora-21 template, you can use the ``-l`` option, then filter the list: -.. code:: bash +.. code:: console [user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21 network/VmNetworking_fedora-21/test_000_simple_networking diff --git a/developer/debugging/mount-lvm-image.rst b/developer/debugging/mount-lvm-image.rst index 5b90ba3d..dbc19b61 100644 --- a/developer/debugging/mount-lvm-image.rst +++ b/developer/debugging/mount-lvm-image.rst @@ -7,7 +7,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star 1: make the image available for qubesdb. From dom0 terminal: -.. code:: bash +.. code:: console # Example: /dev/qubes_dom0/vm-debian-9-tmp-root [user@dom0]$ dev=$(basename $(readlink /dev/YOUR_LVM_VG/YOUR_LVM_IMAGE)) @@ -16,7 +16,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star 2: Create a new disposable VM -.. code:: bash +.. code:: console [user@dom0]$ qvm-run -v --dispvm=YOUR_DVM_TEMPLATE --service qubes.StartApp+xterm & @@ -25,28 +25,28 @@ You want to read your LVM image (e.g., there is a problem where you can’t star From the GUI, or from the command line: -.. code:: bash +.. code:: console [user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev 4: Mount the partition you want to, and do what you want with it -.. code:: bash +.. code:: console [user@dispXXXX]$ mount /dev/xvdiX /mnt/ 5: Umount and kill the VM -.. code:: bash +.. code:: console [user@dispXXXX]$ umount /mnt/ 6: Remove the image from qubesdb -.. code:: bash +.. code:: console [user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/ diff --git a/developer/debugging/safe-remote-ttys.rst b/developer/debugging/safe-remote-ttys.rst index a5afedff..f2da265e 100644 --- a/developer/debugging/safe-remote-ttys.rst +++ b/developer/debugging/safe-remote-ttys.rst @@ -17,7 +17,7 @@ To a different VM As an example of forwarding terminal output to another VM on the same machine: -.. code:: bash +.. code:: console $ mkfifo /tmp/foo $ qvm-run -p some-vm 'xterm -e "cat 0<&5" 5<&0' /dev/null 2>&1 & @@ -31,7 +31,7 @@ To a different machine In this case over SSH (from a network-connected VM): -.. code:: bash +.. code:: console $ mkfifo /tmp/foo $ qvm-run -p some-vm \ @@ -55,7 +55,7 @@ Terminal size It is up to you to ensure the sizes of the local and remote terminal are the same, otherwise things may display incorrectly (especially in interactive programs). Depending on your shell, the size of your local (blind) terminal is likely stored in the ``$LINES`` and ``$COLUMNS`` variables. -.. code:: bash +.. code:: console $ echo $COLUMNS $LINES 80 24 diff --git a/developer/services/qrexec.rst b/developer/services/qrexec.rst index 61ca9c90..2fe7c36c 100644 --- a/developer/services/qrexec.rst +++ b/developer/services/qrexec.rst @@ -18,7 +18,7 @@ Qrexec is built on top of *vchan*, a Xen library providing data links between VM The ``qrexec-client`` command is used to make connections to VMs from dom0. For example, the following command creates an empty file called ``hello-world.txt`` in the home folder of ``someVM``: -.. code:: bash +.. code:: console $ qrexec-client -e -d someVM user:'touch hello-world.txt' @@ -26,7 +26,7 @@ The ``qrexec-client`` command is used to make connections to VMs from dom0. For The string before the colon specifies which user will run the command. The ``-e`` flag tells ``qrexec-client`` to exit immediately after sending the execution request and receiving a status code from ``qrexec-agent`` (if the process creation succeeded). With this option, no further data is passed between the domains. The following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell): -.. code:: bash +.. code:: console $ qrexec-client -d someVM user:bash @@ -83,7 +83,7 @@ Making an RPC call From outside of dom0, RPC calls take the following form: -.. code:: bash +.. code:: console $ qrexec-client-vm target_vm_name RPC_ACTION_NAME rpc_client_path client arguments @@ -91,7 +91,7 @@ From outside of dom0, RPC calls take the following form: For example: -.. code:: bash +.. code:: console $ qrexec-client-vm work qubes.StartApp+firefox @@ -101,7 +101,7 @@ Note that only stdin/stdout is passed between RPC server and client – notably, It is also possible to call service without specific client program – in which case server stdin/out will be connected with the terminal: -.. code:: bash +.. code:: console $ qrexec-client-vm target_vm_name RPC_ACTION_NAME @@ -168,7 +168,7 @@ Be very careful when coding and adding a new RPC service. Unless the offered fun For example, this command will run the ``firefox`` command in a DisposableVM based on ``work``: -.. code:: bash +.. code:: console $ qvm-run --dispvm=work firefox @@ -176,7 +176,7 @@ For example, this command will run the ``firefox`` command in a DisposableVM bas By contrast, consider this command: -.. code:: bash +.. code:: console $ qvm-run --dispvm=work --service qubes.StartApp+firefox @@ -204,7 +204,7 @@ The argument is specified in the second column of the policy line, as +ARGUMENT. When calling a service that takes an argument, just add the argument to the service name separated with ``+``. -.. code:: bash +.. code:: console $ qrexec-client-vm target_vm_name RPC_ACTION_NAME+ARGUMENT @@ -264,7 +264,7 @@ This will allow our client and server to communicate. Before we make the call, ensure that the client and server scripts have executable permissions. Finally, invoke the RPC service. -.. code:: bash +.. code:: console $ qrexec-client-vm anotherVM test.Add /usr/bin/our_test_add_client 1 2 @@ -310,7 +310,7 @@ Now we create the policy file in dom0, at ``/etc/qubes/policy.d/30-test.policy`` With this done, we can run some tests. Invoke RPC from ``source_vm1`` via -.. code:: bash +.. code:: console [user@source_vm1] $ qrexec-client-vm target_vm test.File+testfile1 @@ -318,7 +318,7 @@ With this done, we can run some tests. Invoke RPC from ``source_vm1`` via We should get the contents of ``/home/user/testfile1`` printed to the terminal. Invoking the service from ``source_vm2`` should result in a denial, but ``testfile2`` should work. -.. code:: bash +.. code:: console [user@source_vm2] $ qrexec-client-vm target_vm test.File+testfile1 Request refused diff --git a/developer/services/qrexec2.rst b/developer/services/qrexec2.rst index 3ebc66e2..fbefc5a7 100644 --- a/developer/services/qrexec2.rst +++ b/developer/services/qrexec2.rst @@ -17,7 +17,7 @@ Typically, the first thing that a ``qrexec-client`` instance does is to send a r E.g., to start a primitive shell in a VM type the following in Dom0 console: -.. code:: bash +.. code:: console [user@dom0 ~]$ /usr/lib/qubes/qrexec-client -d user:bash @@ -147,7 +147,7 @@ We will show the necessary files to create a simple RPC call that adds two integ - Policy file in dom0 (``/etc/qubes-rpc/policy/test.Add``) - .. code:: bash + .. code:: $anyvm $anyvm ask diff --git a/introduction/faq.rst b/introduction/faq.rst index 2bb0ca44..65dcd406 100644 --- a/introduction/faq.rst +++ b/introduction/faq.rst @@ -570,7 +570,7 @@ For Debian: - .. code:: bash + .. code:: console $ sudo apt install vlc @@ -589,7 +589,7 @@ For Fedora: - .. code:: bash + .. code:: console $ sudo dnf install vlc diff --git a/project-security/security-pack.rst b/project-security/security-pack.rst index d62a86e6..d0d3c7cc 100644 --- a/project-security/security-pack.rst +++ b/project-security/security-pack.rst @@ -79,7 +79,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and 4. Verify signed Git tags. - .. code:: bash + .. code:: console $ cd qubes-secpack/ $ git tag -v `git describe` @@ -97,7 +97,7 @@ The following example demonstrates one method of obtaining the qubes-secpack and 5. Verify detached PGP signatures. - .. code:: bash + .. code:: console $ cd canaries/ $ gpg --verify canary-001-2015.txt.sig.joanna canary-001-2015.txt diff --git a/project-security/verifying-signatures.rst b/project-security/verifying-signatures.rst index 49bfd49d..0a140d7e 100644 --- a/project-security/verifying-signatures.rst +++ b/project-security/verifying-signatures.rst @@ -51,14 +51,14 @@ Once you have appropriate OpenPGP software installed, there are several ways to - If you’re on Qubes OS, it’s available in every qube (`except dom0 `__): - .. code:: bash + .. code:: console $ gpg2 --import /usr/share/qubes/qubes-master-key.asc - If you’re on Fedora, you can get it in the `distribution-gpg-keys `__ package: - .. code:: bash + .. code:: console $ dnf install distribution-gpg-keys $ gpg2 --import /usr/share/distribution-gpg-keys/qubes/* @@ -68,14 +68,14 @@ Once you have appropriate OpenPGP software installed, there are several ways to - Fetch it with GPG: - .. code:: bash + .. code:: console $ gpg2 --fetch-keys https://keys.qubes-os.org/keys/qubes-master-signing-key.asc - Get it from a public `keyserver `__ (specified on first use with ``--keyserver `` along with keyserver options to include key signatures), e.g.: - .. code:: bash + .. code:: console $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --keyserver hkp://keyserver.ubuntu.com --recv-keys 0x427F11FD0FAA4B080123F01CDDFA1A3E36879494 @@ -94,7 +94,7 @@ Once you have appropriate OpenPGP software installed, there are several ways to Once you have the key as a file, import it: - .. code:: bash + .. code:: console $ gpg2 --import //qubes-master-signing-key.asc @@ -213,7 +213,7 @@ Now, when you import any of the release signing keys and many Qubes team member As a final sanity check, make sure the QMSK is in your keyring with the correct trust level. -.. code:: bash +.. code:: console $ gpg2 -k "Qubes Master Signing Key" pub rsa4096 2010-04-01 [SC] @@ -242,21 +242,21 @@ After you have completed these two prerequisite steps, the next step is to obtai - If you have access to an existing Qubes installation, the release keys are available in dom0 in ``/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*``. These can be :ref:`copied ` into other qubes for further use. In addition, every other qube contains the release key corresponding to that installation’s release in ``/etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-*``. If you wish to use one of these keys, make sure to import it into your keyring, e.g.: - .. code:: bash + .. code:: console $ gpg2 --import /etc/pki/rpm-gpg/RPM-GPG-KEY-qubes-* - Fetch it with GPG: - .. code:: bash + .. code:: console $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --fetch-keys https://keys.qubes-os.org/keys/qubes-release-X-signing-key.asc - Download it as a file. You can find the RSK for your Qubes release on the `downloads `__ page. You can also download all the currently used developers’ signing keys, RSKs, and the Qubes Master Signing Key from the :doc:`Qubes security pack ` and the `Qubes keyserver `__. Once you’ve downloaded your RSK, import it with GPG: - .. code:: bash + .. code:: console $ gpg2 --keyserver-options no-self-sigs-only,no-import-clean --import ./qubes-release-X-signing-key.asc @@ -265,7 +265,7 @@ After you have completed these two prerequisite steps, the next step is to obtai Now that you have the correct RSK, you simply need to verify that it is signed by the QMSK: -.. code:: bash +.. code:: console $ gpg2 --check-signatures "Qubes OS Release X Signing Key" pub rsa4096 YYYY-MM-DD [SC] @@ -281,7 +281,7 @@ This is just an example, so the output you receive may not look exactly the same As a final sanity check, make sure the RSK is in your keyring with the correct trust level: -.. code:: bash +.. code:: console $ gpg2 -k "Qubes OS Release X Signing Key" pub rsa4096 YYYY-MM-DD [SC] @@ -351,7 +351,7 @@ If the filename of your ISO is ``Qubes-RX-x86_64.iso``, then the name of the dig Four digests have been computed for this ISO. The hash functions used, in order from top to bottom, are MD5, SHA-1, SHA-256, and SHA-512. One way to verify that the ISO you downloaded matches any of these hash values is by using the respective ``*sum`` command: -.. code:: bash +.. code:: console $ md5sum -c Qubes-RX-x86_64.iso.DIGESTS Qubes-RX-x86_64.iso: OK @@ -371,7 +371,7 @@ The ``OK`` response tells us that the hash value for that particular hash functi Another way is to use ``openssl`` to compute each hash value, then compare them to the contents of the digest file: -.. code:: bash +.. code:: console $ openssl dgst -md5 Qubes-RX-x86_64.iso MD5(Qubes-RX-x86_64.iso)= 3c951138b8b9867d8657f173c1b58b82 @@ -387,7 +387,7 @@ Another way is to use ``openssl`` to compute each hash value, then compare them However, it is possible that an attacker replaced ``Qubes-RX-x86_64.iso`` with a malicious ISO, computed the hash values for that malicious ISO, and replaced the values in ``Qubes-RX-x86_64.iso.DIGESTS`` with his own set of values. Therefore, we should also verify the authenticity of the listed hash values. Since ``Qubes-RX-x86_64.iso.DIGESTS`` is a clearsigned PGP file, we can use GPG to verify the signature in the digest file: -.. code:: bash +.. code:: console $ gpg2 -v --verify Qubes-RX-x86_64.iso.DIGESTS gpg: armor header: Hash: SHA256 @@ -423,7 +423,7 @@ Every Qubes ISO is released with a **detached PGP signature** file, which you ca Download both the ISO and its signature file. Put both of them in the same directory, then navigate to that directory. Now, you can verify the ISO by executing this GPG command in the directory that contains both files: -.. code:: bash +.. code:: console $ gpg2 -v --verify Qubes-RX-x86_64.iso.asc Qubes-RX-x86_64.iso gpg: armor header: Version: GnuPG v1 @@ -449,7 +449,7 @@ This section will walk through an example of re-verifying the installer on such Now, our goal is to perform the same verification steps as we did with the original ISO, except, this time, we’ll be reading the installer data directly from the write-protected USB drive instead of from the original ISO file. First, let’s compute the SHA-256 hash value of the data on the drive. (This assumes you’re already familiar with `how to verify the cryptographic hash values of Qubes ISOs <#how-to-verify-the-cryptographic-hash-values-of-qubes-isos>`__.) In order to do this, we have to know the exact size, in bytes, of the original ISO. There are two ways to get this information: from the ISO itself and from the Qubes website. Here’s an example of the first way: -.. code:: bash +.. code:: console $ dd if=/dev/sdX bs=1M count=$(stat -c %s /path/to/iso) iflag=count_bytes | sha256sum @@ -472,7 +472,7 @@ Now, reading the number of bytes directly from the ISO is fine, but you may be c Therefore, in order to make things a bit more difficult for your hypothetical adversary, you may instead wish to perform the re-verification in an environment that has never seen the original ISO, e.g., a separate offline computer or a fresh VM the storage space of which is too small to hold the ISO. (**Note:** If you’re doing this in Qubes, you can attach the block device from sys-usb to a separate new qube. You don’t have to perform the re-verification directly in sys-usb.) In that case, you’ll have to obtain the size of the ISO in bytes and enter it into the above command manually. You can, of course, obtain the size by simply using the ``stat -c %s /path/to/iso`` command from above on the machine that has the ISO. You can also obtain it from the Qubes website by hovering over any ISO download button on the `downloads page `__. (You can also view these values directly in the downloads page’s `source data `__.) Once you have the exact size of the ISO in bytes, simply insert it into the same command, for example: -.. code:: bash +.. code:: console $ dd if=/dev/sdX bs=1M count=5791285248 iflag=count_bytes | sha256sum @@ -481,7 +481,7 @@ If you wish to compute the values of other hash functions, you can replace ``sha In addition to checking hash values, you can also use GnuPG to verify the detached PGP signature directly against the data on the USB drive. (This assumes you’re already familiar with `how to verify detached PGP signatures on Qubes ISOs <#how-to-verify-detached-pgp-signatures-on-qubes-isos>`__.) -.. code:: bash +.. code:: console $ dd if=/dev/sdX bs=1M count= iflag=count_bytes | gpg -v --verify Qubes-RX-x86_64.iso.asc - gpg: Signature made ` you may clone the AwesomeWM repository as follows: -.. code:: bash +.. code:: console $ git clone https://github.com/QubesOS/qubes-desktop-linux-awesome diff --git a/user/advanced-topics/disposable-customization.rst b/user/advanced-topics/disposable-customization.rst index f3559700..dc17c290 100644 --- a/user/advanced-topics/disposable-customization.rst +++ b/user/advanced-topics/disposable-customization.rst @@ -12,14 +12,14 @@ Introduction A :doc:`disposable ` can be based on any :ref:`app qube `. You can also choose to use different :ref:`disposable templates ` for different disposables. To prepare an app qube to be a disposable template, you need to set the ``template_for_dispvms`` property: -.. code:: bash +.. 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:: bash +.. code:: console [user@dom0 ~]$ qvm-features appmenus-dispvm 1 @@ -38,7 +38,7 @@ Creating a new disposable template 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: -.. code:: bash +.. code:: console [user@dom0 ~]$ qvm-create --template