Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'pierwill-qrexec-rewrite-phase-3-internals'

Browse Source
This commit is contained in:
Andrew David Wong 2019-10-29 00:32:40 -05:00
commit 97cc887658
No known key found for this signature in database
GPG Key ID: 8CE137352A019A17
2 changed files with 17 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
developer/services/qrexec-internals.md
View File

@ -15,21 +15,27 @@ redirect_from:
A [general introduction](/doc/qrexec/) to qrexec is also available. A [general introduction](/doc/qrexec/) to qrexec is also available.
For the implementation of qrexec2, see [here](/doc/qrexec2/#qubes-rpc-internals).*) 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). 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 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. 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. 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 ## Dom0 tools implementation
* `/usr/lib/qubes/qrexec-daemon`: One instance is required for every active domain. Responsible for: ### qrexec-daemon
* `/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 execution and service requests from **dom0** (source: `qrexec-client`).
* Handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`). * Handling service requests from the associated domain (source: `qrexec-client-vm`, then `qrexec-agent`).
* Command line: `qrexec-daemon domain-id domain-name [default user]` * Command line: `qrexec-daemon domain-id domain-name [default user]`
* `domain-id`: Numeric Qubes ID assigned to the associated domain. * `domain-id`: Numeric Qubes ID assigned to the associated domain.
* `domain-name`: Associated domain name. * `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. * `default user`: Optional. If passed, `qrexec-daemon` uses this user as default for all execution requests that don't specify one.
* `/usr/lib/qubes/qrexec-policy`: Internal program used to evaluate the RPC policy and deciding whether a RPC call should be allowed.
* `/usr/lib/qubes/qrexec-client`: Used to pass execution and service requests to `qrexec-daemon`. Command line parameters: ### qrexec-policy
* `/usr/bin/qrexec-policy`: Internal program used to evaluate the RPC policy and deciding whether a RPC call should be allowed.
### qrexec-client
* `/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. * `-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. * `-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. * `-e`: Optional. If present, stdout/stdin are not connected to the remote peer. Only process creation status code is received.
@ -40,11 +46,12 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951
## VM tools implementation ## 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. * Handling service requests from `qrexec-client-vm` and passing them to connected `qrexec-daemon` in dom0.
* Executing associated `qrexec-daemon` execution/service requests. * Executing associated `qrexec-daemon` execution/service requests.
* Command line parameters: none. * 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]` * 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. * `target-domain-name`: Target domain for the service request. Source is the current domain.
* `service-name`: Requested service name. * `service-name`: Requested service name.
@ -52,7 +59,7 @@ Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951
## Qrexec protocol details ## 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. All messages share a common header followed by an optional data packet.
/* uniform for all peers, data type depends on message type */ /* uniform for all peers, data type depends on message type */

2
developer/services/qrexec.md
View File

@ -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. 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. 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 ## 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). 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).