Correct code-block lexers

Changing `bash` lexer to `console` because it is appropriate most of
the time. Then after a manual review, some lexer have been changed.

I used `text` each time I was unsure, and for prompt outputs.

The page `/developer/building/qubes-iso-building.rst` still need to be
reviewed (look for lines starting with `$ #`).

I'm not sure about the Windows pages, should we use
[doscon](https://pygments.org/docs/lexers/#pygments.lexers.shell.MSDOSSessionLexer)
or `powershell`?

Is there an appropriate lexer for `guid.conf` content?

**Statistics - Before**
    870 bash
      9 python
      9 c
      2 yaml

**Statistics - After**
    684 console
    111 text
     44 bash
     16 yaml
      9 systemd
      9 c
      8 python
      4 ini
      4 doscon
      2 markdown
      2 desktop
      1 xorg.conf
      1 xml+jinja
      1 xml
      1 kconfig
      1 html

This suggests that the default lexer should be `console`.
This commit is contained in:
parulin 2025-07-30 09:43:09 -04:00
parent a252dc4338
commit 4212c5eda8
No known key found for this signature in database
GPG key ID: BC3830B42F4BF1F5
98 changed files with 1022 additions and 1029 deletions

View file

@ -142,7 +142,7 @@ dom0: request execution of ``cmd`` in domX
- **dom0**: ``qrexec-client`` is invoked in **dom0** as follows:
.. code:: bash
.. code:: console
qrexec-client -d domX [-l local_program] user:cmd
@ -189,7 +189,7 @@ domX: request execution of service ``admin.Service`` in dom0
- **domX**: ``qrexec-client-vm`` is invoked as follows:
.. code:: bash
.. code:: console
qrexec-client-vm dom0 admin.Service [local_program] [params]
@ -215,7 +215,7 @@ domX: request execution of service ``admin.Service`` in dom0
- **dom0**: If the RPC is allowed, ``qrexec-policy`` will launch a ``qrexec-client`` with the right command:
.. code:: bash
.. code:: console
qrexec-client -d dom0 -c domX,X,SOCKET11 "QUBESRPC admin.Service domX name dom0"
@ -258,7 +258,7 @@ domX: invoke execution of qubes service ``qubes.Service`` in domY
- **domX**: ``qrexec-client-vm`` is invoked as follows:
.. code:: bash
.. code:: console
qrexec-client-vm domY qubes.Service [local_program] [params]
@ -276,7 +276,7 @@ domX: invoke execution of qubes service ``qubes.Service`` in domY
- **dom0**: If the RPC is allowed, ``qrexec-policy`` will launch a ``qrexec-client`` with the right command:
.. code:: bash
.. code:: console
qrexec-client -d domY -c domX,X,SOCKET11 user:cmd "DEFAULT:QUBESRPC qubes.Service domX"

View file

@ -15,7 +15,7 @@ When a Qubes RPC service is invoked, qrexec searches for a file that handles it
Before passing user input, the socket service will receive a null-terminated service descriptor, i.e. the part after ``QUBESRPC``. When running in a VM, this is:
.. code:: bash
.. code:: text
<service_name> <source>\0
@ -23,7 +23,7 @@ Before passing user input, the socket service will receive a null-terminated ser
When running in dom0, it is:
.. code:: bash
.. code:: text
<service_name> <source> <target_type> <target>\0
@ -81,18 +81,18 @@ Systemd unit files
**/lib/systemd/user/qubes-qrexec-policy-agent.service**: This is the service configuration.
.. code:: bash
.. code:: systemd
[Unit]
Description=Qubes remote exec policy agent
ConditionUser=!root
ConditionGroup=qubes
Requires=qubes-qrexec-policy-agent.socket
[Service]
Type=simple
ExecStart=/usr/bin/qrexec-policy-agent
[Install]
WantedBy=default.target
@ -100,17 +100,17 @@ Systemd unit files
**/lib/systemd/user/qubes-qrexec-policy-agent.socket**: This is the socket file that will activate the service.
.. code:: bash
.. code:: systemd
[Unit]
Description=Qubes remote exec policy agent socket
ConditionUser=!root
ConditionGroup=qubes
PartOf=qubes-qrexec-policy-agent.service
[Socket]
ListenStream=/var/run/qubes/policy-agent.sock
[Install]
WantedBy=sockets.target
@ -120,7 +120,7 @@ Note the ``ConditionUser`` and ``ConditionGroup`` that ensure that the socket an
Start the socket using ``systemctl --user start``. Enable it using ``systemctl --user enable``, so that it starts automatically.
.. code:: bash
.. code:: console
systemctl --user start qubes-qrexec-policy-agent.socket
systemctl --user enable qubes-qrexec-policy-agent.socket
@ -129,7 +129,7 @@ Start the socket using ``systemctl --user start``. Enable it using ``systemctl -
Alternatively, you can enable the service by creating a symlink:
.. code:: bash
.. code:: console
sudo ln -s /lib/systemd/user/qubes-qrexec-policy-agent.socket /lib/systemd/user/sockets.target.wants/
@ -141,7 +141,7 @@ Link in qubes-rpc
``qrexec-policy-agent`` will handle a Qubes RPC service called ``policy.Ask``, so we add a link:
.. code:: bash
.. code:: console
sudo ln -s /var/run/qubes/policy-agent.sock /etc/qubes-rpc/policy.Ask
@ -155,7 +155,7 @@ Socket activation in systemd works by starting our program with the socket file
Install the Python systemd library:
.. code:: bash
.. code:: console
sudo dnf install python3-systemd
@ -168,20 +168,20 @@ Here is the server code:
import os
import asyncio
import socket
from systemd.daemon import listen_fds
class SocketService:
def __init__(self, socket_path, socket_activated=False):
self._socket_path = socket_path
self._socket_activated = socket_activated
async def run(self):
server = await self.start()
async with server:
await server.serve_forever()
async def start(self):
if self._socket_activated:
fds = listen_fds()
@ -191,41 +191,41 @@ Here is the server code:
sock = socket.socket(fileno=fds[0])
return await asyncio.start_unix_server(self._client_connected,
sock=sock)
if os.path.exists(self._socket_path):
os.unlink(self._socket_path)
return await asyncio.start_unix_server(self._client_connected,
path=self._socket_path)
async def _client_connected(self, reader, writer):
try:
data = await reader.read()
assert b'\0' in data, data
service_descriptor, data = data.split(b'\0', 1)
response = await self.handle_request(service_descriptor, data)
writer.write(response)
await writer.drain()
finally:
writer.close()
await writer.wait_closed()
async def handle_request(self, service_descriptor, data):
# process params, return response
return response
def main():
socket_path = '/var/run/qubes/policy-agent.sock'
service = SocketService(socket_path)
loop = asyncio.get_event_loop()
loop.run_until_complete(service.run())
if __name__ == '__main__':
main()
@ -238,7 +238,7 @@ Using the service
The service is invoked in the same way as a standard Qubes RPC service:
.. code:: bash
.. code:: console
echo <input_data> | qrexec-client -d domX 'DEFAULT:QUBESRPC policy.Ask'
@ -246,7 +246,7 @@ The service is invoked in the same way as a standard Qubes RPC service:
You can also connect to it locally, but remember to include the service descriptor:
.. code:: bash
.. code:: console
echo -e 'policy.Ask dom0\0<input data>' | nc -U /etc/qubes-rpc/policy.Ask

View file

@ -67,7 +67,7 @@ Policy files
Policies are defined in lines with the following format:
.. code:: bash
.. code:: text
service-name|* +argument|* source destination action [options]
@ -131,7 +131,7 @@ There are severals methods for specifying source/target VMs in RPC policies.
Target VM can be also specified as ``@default``, which matches the case when calling VM didnt specified any particular target (either by using ``@default`` target, or empty target). For DisposableVMs, ``@dispvm:DISP_VM`` is very similar to ``@dispvm`` but forces using a particular VM (``DISP_VM``) as a base VM to be started as DisposableVM. For example:
.. code:: bash
.. code:: text
* * anon-whonix @dispvm:anon-whonix-dvm allow
@ -139,7 +139,7 @@ Target VM can be also specified as ``@default``, which matches the case when cal
Adding such policy itself will not force usage of this particular ``DISP_VM`` - it will only allow it when specified by the caller. But ``@dispvm:DISP_VM`` can also be used as target in request redirection, so *it is possible* to force particular ``DISP_VM`` usage, when caller didnt specify it:
.. code:: bash
.. code:: text
* * anon-whonix @dispvm allow target=@dispvm:anon-whonix-dvm
@ -149,7 +149,7 @@ Note that without redirection, this rule would allow using default Disposable VM
The policy confirmation dialog (``ask`` action) allows the user to specify target VM. User can choose from VMs that, according to policy, would lead to ``ask`` or ``allow`` actions. It is not possible to select VM that policy would deny. By default no VM is selected, even if the caller provided some, but policy can specify default value using ``default_target=`` parameter. For example:
.. code:: bash
.. code:: text
* * work-mail work-archive allow
* * work-mail @tag:work ask default_target=work-files
@ -193,7 +193,7 @@ For this reason it is possible to specify a service argument, which will be subj
The argument is specified in the second column of the policy line, as +ARGUMENT. If the policy uses “*” as an argument, then it will match any argument (including no argument). As rules are processed in order, any lines with a specific argument below the line with the wildcard argument will be ignored. So for instance, we might have policies which are different depending on the argument:
.. code:: bash
.. code:: text
Device +device1 * * allow
Device +device2 * * deny
@ -245,7 +245,7 @@ Our server will be anotherVM at ``/usr/bin/our_test_add_server``. The code for t
Well need to create a service called ``test.Add`` with its own definition and policy file in dom0. Now we need to define what the service does. In this case, it should call our addition script. We define the service with a symlink at ``/etc/qubes-rpc/test.Add`` pointing to our server script (the script can be also placed directly in ``/etc/qubes-rpc/test.Add`` - make sure the file has executable bit set!):
.. code:: bash
.. code:: console
ln -s /usr/bin/our_test_add_server /etc/qubes-rpc/test.Add
@ -253,7 +253,7 @@ Well need to create a service called ``test.Add`` with its own definition and
The administrative domain will direct traffic based on the current RPC policies. In dom0, create a file at ``/etc/qubes/policy.d/30-test.policy`` containing the following:
.. code:: bash
.. code:: text
test.Add * * * ask
@ -299,7 +299,7 @@ Make sure the file is executable! (The service argument is already sanitized by
Now we create the policy file in dom0, at ``/etc/qubes/policy.d/30-test.policy``. The contents of the file are below. Replace “source_vm1” and others with the names of your own chosen domains.
.. code:: bash
.. code:: text
test.File +testfile1 source_vm1 target_vm allow
test.File +testfile2 source_vm2 target_vm allow

View file

@ -54,7 +54,7 @@ Besides each VM needing to provide explicit programs to serve each supported ser
In dom0, there is a bunch of files in ``/etc/qubes-rpc/policy/`` directory, whose names describe the available RPC actions; their content is the RPC access policy database. Some example of the default services in Qubes are:
.. code:: bash
.. code:: text
qubes.Filecopy
qubes.OpenInVM
@ -70,7 +70,7 @@ In dom0, there is a bunch of files in ``/etc/qubes-rpc/policy/`` directory, whos
These files contain lines with the following format:
.. code:: bash
.. code:: text
srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to]
@ -88,7 +88,7 @@ Requesting VM-VM (and VM-Dom0) services execution
In a src VM, one should invoke the qrexec client via the following command:
.. code:: bash
.. code:: console
/usr/lib/qubes/qrexec-client-vm <target vm name> <service name> <local program path> [local program arguments]
@ -112,7 +112,7 @@ Qubes RPC policy supports an “ask” action, that will prompt the user whether
In order to remove such authorization, issue this command from a Dom0 terminal (example below for ``qubes.Filecopy`` service):
.. code:: bash
.. code:: console
sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
@ -147,14 +147,14 @@ 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::
.. code:: text
$anyvm $anyvm ask
- Server path definition on target VM (``/etc/qubes-rpc/test.Add``)
.. code:: bash
.. code:: text
/usr/bin/our_test_add_server
@ -162,7 +162,7 @@ We will show the necessary files to create a simple RPC call that adds two integ
- To test this service, run the following in the source VM:
.. code:: bash
.. code:: console
/usr/lib/qubes/qrexec-client-vm <target VM> test.Add /usr/bin/our_test_add_client 1 2