mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-11-25 14:06:34 -05:00
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:
parent
a252dc4338
commit
4212c5eda8
98 changed files with 1022 additions and 1029 deletions
|
|
@ -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"
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 didn’t 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 didn’t 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
|
|||
|
||||
We’ll 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 @@ We’ll 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue