mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-11-23 13:17:45 -05:00
Merge remote-tracking branch 'parulin/clean-code-block-console' into rst
This commit is contained in:
qubedmaiska
commit
d4e09e079f
111 changed files with 1270 additions and 1265 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
@ -65,7 +65,7 @@ Policy files
|
|||
|
||||
Policies are defined in lines with the following format:
|
||||
|
||||
.. code:: bash
|
||||
.. code:: text
|
||||
|
||||
service-name|* +argument|* source destination action [options]
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -129,7 +129,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
|
||||
|
||||
|
|
@ -137,7 +137,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
|
||||
|
||||
|
|
@ -147,7 +147,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
|
||||
|
|
@ -165,7 +165,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
|
||||
|
||||
|
|
@ -173,7 +173,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
|
||||
|
||||
|
|
@ -191,7 +191,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
|
||||
|
|
@ -201,7 +201,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
|
||||
|
||||
|
|
@ -243,7 +243,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
|
||||
|
||||
|
|
@ -251,7 +251,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
|
||||
|
||||
|
|
@ -261,7 +261,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
|
||||
|
||||
|
|
@ -297,7 +297,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
|
||||
|
|
@ -307,7 +307,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
|
||||
|
||||
|
|
@ -315,7 +315,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
|
||||
|
|
|
|||
|
|
@ -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 <vm name> user:bash
|
||||
|
||||
|
|
@ -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:: bash
|
||||
.. 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