From 1514d2e8542aa12e6a9ce3491c4abe83321847ee Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Fri, 27 Sep 2019 14:50:11 -0500 Subject: [PATCH 1/4] Begin revising qrexec internals Add section headings, minor rewordings --- developer/services/qrexec-internals.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index e13be781..8ee70025 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -21,6 +21,7 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951 ## Dom0 tools implementation +### qrexec-daemon * `/usr/lib/qubes/qrexec-daemon`: One instance is required for every active domain. Responsible for: * Handling execution and service requests from **dom0** (source: `qrexec-client`). * Handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`). @@ -28,7 +29,11 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951 * `domain-id`: Numeric Qubes ID assigned to the associated domain. * `domain-name`: Associated domain name. * `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one. + +### qrexec-policy * `/usr/lib/qubes/qrexec-policy`: Internal program used to evaluate the RPC policy and deciding whether a RPC call should be allowed. + +### qrexec-client * `/usr/lib/qubes/qrexec-client`: Used to pass execution and service requests to `qrexec-daemon`. Command line parameters: * `-d target-domain-name`: Specifies the target for the execution/service request. * `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer. @@ -40,11 +45,12 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951 ## VM tools implementation -* `qrexec-agent`: One instance runs in each active domain. Responsible for: +### `qrexec-agent`: One instance runs in each active domain. Responsible for: * Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0. * Executing associated `qrexec-daemon` execution/service requests. * Command line parameters: none. -* `qrexec-client-vm`: Runs in an active domain. Used to pass service requests to `qrexec-agent`. + +### `qrexec-client-vm`: Runs in an active domain. Used to pass service requests to `qrexec-agent`. * Command line: `qrexec-client-vm target-domain-name service-name local-program [local program arguments]` * `target-domain-name`: Target domain for the service request. Source is the current domain. * `service-name`: Requested service name. @@ -52,7 +58,7 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951 ## Qrexec protocol details -Qrexec protocol is message-based. +The qrexec protocol is message-based. All messages share a common header followed by an optional data packet. /* uniform for all peers, data type depends on message type */ From e4cbcf49e1c718c15e92381d82d38dfe915c76ca Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Wed, 2 Oct 2019 12:15:37 -0700 Subject: [PATCH 2/4] Add link to qrexec internals page --- developer/services/qrexec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/developer/services/qrexec.md b/developer/services/qrexec.md index b8a4926f..737f195f 100644 --- a/developer/services/qrexec.md +++ b/developer/services/qrexec.md @@ -66,6 +66,8 @@ Thus, it is usually more convenient to use `qvm-run`. There can be an almost arbitrary number of `qrexec-client` processes for a given domain. The limiting factor is the number of available vchan channels, which depends on the underlying hypervisor, as well the domain's OS. +For more details on the qrexec framework and protocol, see "[Qubes RPC internals](/doc/qrexec-internals)." + ## Qubes RPC services Some common tasks (like copying files between VMs) have an RPC-like structure: a process in one VM (say, the file sender) needs to invoke and send/receive data to some process in other VM (say, the file receiver). From b4a28c82615e64226f8ab8772ea29d75a55d018c Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Wed, 2 Oct 2019 12:37:13 -0700 Subject: [PATCH 3/4] Revise qrexec internals introduction --- developer/services/qrexec-internals.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 8ee70025..2b28b00b 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -15,8 +15,9 @@ redirect_from: A [general introduction](/doc/qrexec/) to qrexec is also available. For the implementation of qrexec2, see [here](/doc/qrexec2/#qubes-rpc-internals).*) -Qrexec framework consists of a number of processes communicating with each other using common IPC protocol (described in detail below). -Components residing in the same domain (`qrexec-client-vm` to `qrexec-agent`, `qrexec-client` to `qrexec-daemon`) use pipes as the underlying transport medium, while components in separate domains (`qrexec-daemon` to `qrexec-agent`, data channel between `qrexec-agent`s) use vchan link. +The qrexec framework consists of a number of processes communicating with each other using common IPC protocol (described in detail below). +Components residing in the same domain (`qrexec-client-vm` to `qrexec-agent`, `qrexec-client` to `qrexec-daemon`) use local sockets as the underlying transport medium. +Components in separate domains (`qrexec-daemon` to `qrexec-agent`, data channel between `qrexec-agent`s) use vchan links. Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951), it is not possible to establish qrexec connection back to the source domain. ## Dom0 tools implementation From 8f53aa8154a527487a6763f1b139372563691c2e Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sat, 12 Oct 2019 17:50:18 -0700 Subject: [PATCH 4/4] Fix paths to qrexec tools --- developer/services/qrexec-internals.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 2b28b00b..bd8d74a8 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -23,7 +23,7 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951 ## Dom0 tools implementation ### qrexec-daemon -* `/usr/lib/qubes/qrexec-daemon`: One instance is required for every active domain. Responsible for: +* `/usr/sbin/qrexec-daemon`: One instance is required for every active domain. Responsible for: * Handling execution and service requests from **dom0** (source: `qrexec-client`). * Handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`). * Command line: `qrexec-daemon domain-id domain-name [default user]` @@ -32,10 +32,10 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951 * `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one. ### qrexec-policy -* `/usr/lib/qubes/qrexec-policy`: Internal program used to evaluate the RPC policy and deciding whether a RPC call should be allowed. +* `/usr/bin/qrexec-policy`: Internal program used to evaluate the RPC policy and deciding whether a RPC call should be allowed. ### qrexec-client -* `/usr/lib/qubes/qrexec-client`: Used to pass execution and service requests to `qrexec-daemon`. Command line parameters: +* `/usr/bin/qrexec-client`: Used to pass execution and service requests to `qrexec-daemon`. Command line parameters: * `-d target-domain-name`: Specifies the target for the execution/service request. * `-l local-program`: Optional. If present, `local-program` is executed and its stdout/stdin are used when sending/receiving data to/from the remote peer. * `-e`: Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received.