From 804acc1f6548b19a1ea1de1f4ada71eb7d4ea17a Mon Sep 17 00:00:00 2001 From: parulin <161326115+parulin@users.noreply.github.com> Date: Fri, 12 Sep 2025 17:09:41 -0400 Subject: [PATCH] Clarify how-to-edit-a-policy following review Following @rapenne-s review: * make clear that the first method is for the most common policies * explain how priority works * provide the user a way to modify the default editor * some typos Reading again the help text of `qubes-policy-editor` I made some corrections. --- user/how-to-guides/how-to-edit-a-policy.rst | 32 ++++++++++++++------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/user/how-to-guides/how-to-edit-a-policy.rst b/user/how-to-guides/how-to-edit-a-policy.rst index 3e0d21e0..4120a7bf 100644 --- a/user/how-to-guides/how-to-edit-a-policy.rst +++ b/user/how-to-guides/how-to-edit-a-policy.rst @@ -11,12 +11,16 @@ There are three ways to edit a :ref:`policy `: * with :program:`qubes-policy-editor`, a command-line text editor that will validate the file before saving it. -In this how-to, we will restrict the clipboard policy to prevent an *untrusted* qube from pasting something in a *vault* qube. +In this how-to, we will restrict the clipboard policy to prevent an *untrusted* qube from pasting something in a *vault* qube, **as an example**. + +.. _edit-a-policy-with-qubes-os-global-config: Edit a policy with :program:`Qubes OS Global Config` ---------------------------------------------------- -1. You need to go to the :guilabel:`Clipboard` tab. +:program:`Qubes OS Global Config` allows you to edit the most common policies. Following our clipboard example: + +1. you need to go to the :guilabel:`Clipboard` tab. 2. Under :guilabel:`Custom policy`, select :guilabel:`Add` @@ -31,9 +35,9 @@ Edit a policy with :program:`Qubes Policy Editor` 1. Open :program:`Qubes Policy Editor` -2. You have to: +2. You have to either: - * either open an existing file using :menuselection:`&File --> &Open` or :kbd:`Ctrl` + :kbd:`O` + * open an existing file using :menuselection:`&File --> &Open` or :kbd:`Ctrl` + :kbd:`O` * or create a new file using :menuselection:`&File --> &New` or :kbd:`Ctrl` + :kbd:`N` In that case, you need to choose a filename. The filename can only contain alphanumeric characters, underscores and hyphens. The common practice is to use a name like :file:`{30}-{user}.policy` where: @@ -41,11 +45,11 @@ Edit a policy with :program:`Qubes Policy Editor` * :samp:`{30}` indicates the priority (i.e. the default policies start with ``90`` while the policies from :program:`Qubes OS Global Config` start with ``50``) * :samp:`{user}` could be any name - In order to change some clipboard policy, :file:`20-clipboard` could be a good name. + In order to override some clipboard policy, :file:`30-clipboard` could be a good name. Starting with ``20`` makes sure that the file will be read before any file starting with ``31`` or more, especially :file:`50-config-clipboard.policy`: this file is automatically created if you :ref`edit-a-policy-with-qubes-os-global-config`. If you want to create a policy that will never override the policies from :program:`Qubes OS Global Config`, use a name starting with a number between ``51`` and ``89``. The default policies from Qubes OS start with ``90``, so using a number equal or superior might b bee useless. 3. Add a line to the file. In order to prevent the *untrusted* qube from pasting to the *vault* qube, the line should be: - .. code: text + .. code:: text qubes.ClipboardPaste * untrusted vault deny @@ -54,15 +58,21 @@ Edit a policy with :program:`Qubes Policy Editor` Edit a policy with :program:`qubes-policy-editor` ------------------------------------------------- -`qubes-policy-editor` is a command-line tool that ensures that the filename of the policy is correct and that the syntax is valid. +:program:`qubes-policy-editor` is a command-line tool that ensures that the syntax of the policy is valid. You have to run it as root: -You can invoke the program with any valid filename (only alphanumeric characters, underscores and hyphens), with or without the ``.policy`` extension: +.. code:: console -.. code: console + [root@dom0] # qubes-policy-editor - [root@dom0] # qubes-policy-editor 20-clipboard +An editor will open; it will be your default editor if you have set the environment variable ``$EDITOR`` or ``$VISUAL``, otherwise it will fall back to :program:`vi`. After saving the file, :program:`qubes-policy-editor` will check the content and tell you if there is something wrong with the syntax. -Your default editor will open. After saving the file, `qubes-policy-editor` will check the file and tell you if there is something wrong with the syntax. +It will open :file:`30-user.policy` by default but you can invoke the program with any valid filename (only alphanumeric characters, underscores and hyphens), without the ``.policy`` extension: + +.. code:: console + + [root@dom0] # qubes-policy-editor 30-clipboard + +In that case, :program:`qubes-policy-editor` will also check that the filename of the policy is correct. See also --------