From 9b11c6d10765490ad3f46955efb84d46ee3a3215 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 13 Oct 2019 21:55:20 -0700 Subject: [PATCH 1/6] Add diagrams to qrexec internals docs --- developer/services/qrexec-internals.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index bd8d74a8..864a38a5 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -82,6 +82,8 @@ Details of all possible use cases and the messages involved are described below. ### dom0: request execution of `some_command` in domX and pass stdin/stdout +![qrexec basics diagram](/attachment/wiki/qrexec3/qrexec-internals-dom0.png) + - **dom0**: `qrexec-client` is invoked in **dom0** as follows: qrexec-client -d domX [-l local_program] user:some_command` @@ -117,6 +119,8 @@ Details of all possible use cases and the messages involved are described below. ### domY: invoke execution of qubes service `qubes.SomeRpc` in domX and pass stdin/stdout +![qrexec basics diagram](/attachment/wiki/qrexec3/qrexec-internals-domY.png) + - **domY**: `qrexec-client-vm` is invoked as follows: qrexec-client-vm domX qubes.SomeRpc local_program [params] From accb8fe9454069c7e1461a9c1b90c1feea919601 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 13 Oct 2019 22:09:48 -0700 Subject: [PATCH 2/6] Edit qrexec internals docs --- developer/services/qrexec-internals.md | 43 ++++++++++++++++++++------ 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 864a38a5..0a4b5d64 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -15,15 +15,23 @@ redirect_from: A [general introduction](/doc/qrexec/) to qrexec is also available. For the implementation of qrexec2, see [here](/doc/qrexec2/#qubes-rpc-internals).*) -The qrexec framework consists of a number of processes communicating with each other using common IPC protocol (described in detail below). +The qrexec framework consists of a number of processes communicating with each other using a 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 +The following programs handle parts of the framework: sending and receiving requests, verifying permissions, and administering connections. +These tools are not designed to be used by users directly. + ### qrexec-daemon -* `/usr/sbin/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,26 +40,41 @@ 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/bin/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 decide whether an RPC call should be allowed. ### qrexec-client -* `/usr/bin/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. * `-c `: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example. * `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example. -**Note:** None of the above tools are designed to be used by users directly. - ## 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. @@ -82,7 +105,7 @@ Details of all possible use cases and the messages involved are described below. ### dom0: request execution of `some_command` in domX and pass stdin/stdout -![qrexec basics diagram](/attachment/wiki/qrexec3/qrexec-internals-dom0.png) +![qrexec internals diagram dom0](/attachment/wiki/qrexec3/qrexec-internals-dom0.png) - **dom0**: `qrexec-client` is invoked in **dom0** as follows: @@ -119,7 +142,7 @@ Details of all possible use cases and the messages involved are described below. ### domY: invoke execution of qubes service `qubes.SomeRpc` in domX and pass stdin/stdout -![qrexec basics diagram](/attachment/wiki/qrexec3/qrexec-internals-domY.png) +![qrexec internals diagram domY](/attachment/wiki/qrexec3/qrexec-internals-domY.png) - **domY**: `qrexec-client-vm` is invoked as follows: From 3246a0ab94f3897d9f7a5d67c9267c818e085d53 Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 17 Nov 2019 20:26:33 -0800 Subject: [PATCH 3/6] Add paths for qrexec vm tools --- developer/services/qrexec-internals.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 0a4b5d64..7b1bbb46 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -59,9 +59,9 @@ Command line parameters: ## VM tools implementation -### `qrexec-agent` +### qrexec-agent - +`/usr/lib/qubes/qrexec-agrent` One instance runs in each active domain. Responsible for: @@ -69,9 +69,9 @@ Responsible for: * Executing associated `qrexec-daemon` execution/service requests. * Command line parameters: none. -### `qrexec-client-vm` +### qrexec-client-vm - +`/usr/bin/qrexec-client-vm` Runs in an active domain. Used to pass service requests to `qrexec-agent`. From c967c7b145a46f379a715fb6809988b47a109ff8 Mon Sep 17 00:00:00 2001 From: pierwill Date: Thu, 5 Dec 2019 21:45:58 -0800 Subject: [PATCH 4/6] Edit qrexec doc page titles --- developer/services/qrexec-internals.md | 2 +- developer/services/qrexec.md | 2 +- doc.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 7b1bbb46..4f69ef08 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -1,6 +1,6 @@ --- layout: doc -title: Qubes RPC internals +title: "Qrexex: Qubes RPC internals" permalink: /doc/qrexec-internals/ redirect_from: - /doc/qrexec3-implementation/ diff --git a/developer/services/qrexec.md b/developer/services/qrexec.md index 737f195f..9f5542a0 100644 --- a/developer/services/qrexec.md +++ b/developer/services/qrexec.md @@ -1,6 +1,6 @@ --- layout: doc -title: Qrexec +title: "Qrexec: secure communication across domains" permalink: /doc/qrexec/ redirect_from: - /en/doc/qrexec3/ diff --git a/doc.md b/doc.md index be853c48..537e6f9c 100644 --- a/doc.md +++ b/doc.md @@ -167,7 +167,7 @@ Core documentation for Qubes developers and advanced users. * [Implementation of DisposableVMs](/doc/dvm-impl/) * [Dom0 secure update mechanism](/doc/dom0-secure-updates/) * [Qrexec: secure communication across domains](/doc/qrexec/) - * [Qubes RPC internals](/doc/qrexec-internals/) + * [Qrexec: Qubes RPC internals](/doc/qrexec-internals/) ### Debugging From 5bc91a4bcd74363e64c5152cee6696ba4f584f81 Mon Sep 17 00:00:00 2001 From: pierwill Date: Thu, 5 Dec 2019 22:13:15 -0800 Subject: [PATCH 5/6] Edit qrexec command line tools descriptions --- developer/services/qrexec-internals.md | 35 +++++++++++++++++--------- 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/developer/services/qrexec-internals.md b/developer/services/qrexec-internals.md index 4f69ef08..cc50fe2c 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -31,10 +31,14 @@ These tools are not designed to be used by users directly. `/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]` +`qrexex-daemon` is responsible for both: +- handling execution and service requests from **dom0** (source: `qrexec-client`); and +- handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`). + +Command line usage: + +`qrexec-daemon domain-id domain-name [default user]` + * `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. @@ -50,12 +54,14 @@ Internal program used to evaluate the RPC policy and decide whether an RPC call `/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. - * `-c `: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example. - * `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example. + +Command line usage: + +* `-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. +* `-c `: used for connecting a VM-VM service request by `qrexec-policy`. Details described below in the service example. +* `cmdline`: Command line to pass to `qrexec-daemon` as the execution/service request. Service request format is described below in the service example. ## VM tools implementation @@ -67,7 +73,8 @@ 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. + +The `qrexec-agent` command takes no paramaters. ### qrexec-client-vm @@ -75,7 +82,11 @@ Responsible for: 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]` + +Command line usage: + +`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. * `local-program`: `local-program` is executed locally and its stdin/stdout are connected to the remote service endpoint. From 53673f00ce542986282e3f42602675fc1df155a9 Mon Sep 17 00:00:00 2001 From: pierwill Date: Fri, 27 Dec 2019 10:47:17 -0800 Subject: [PATCH 6/6] Fix typos --- 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 cc50fe2c..8a60e2f9 100644 --- a/developer/services/qrexec-internals.md +++ b/developer/services/qrexec-internals.md @@ -1,6 +1,6 @@ --- layout: doc -title: "Qrexex: Qubes RPC internals" +title: "Qrexec: Qubes RPC internals" permalink: /doc/qrexec-internals/ redirect_from: - /doc/qrexec3-implementation/ @@ -31,7 +31,7 @@ These tools are not designed to be used by users directly. `/usr/sbin/qrexec-daemon` One instance is required for every active domain. -`qrexex-daemon` is responsible for both: +`qrexec-daemon` is responsible for both: - handling execution and service requests from **dom0** (source: `qrexec-client`); and - handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`). @@ -74,7 +74,7 @@ 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. -The `qrexec-agent` command takes no paramaters. +The `qrexec-agent` command takes no parameters. ### qrexec-client-vm