Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-12-25 23:39:37 -05:00
Code Issues Packages Projects Releases Wiki Activity

Edit for grammar and clarity qrexec.md

Browse Source
This commit is contained in:
ooops 2024-03-02 02:11:33 +01:00 committed by GitHub
parent 72052be4d5
commit 896aaf5681
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 16 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
developer/services/qrexec.md
View File

@ -22,14 +22,14 @@ However, the OS needs a mechanism to allow the administrative domain (dom0) to f
For instance, when a user selects an application from the KDE menu, it should start in the selected VM. For instance, when a user selects an application from the KDE menu, it should start in the selected VM.
Also, it is often useful to be able to pass stdin/stdout/stderr from an application running in a VM to dom0 (and the other way around). Also, it is often useful to be able to pass stdin/stdout/stderr from an application running in a VM to dom0 (and the other way around).
(For example, so that a VM can notify dom0 that there are updates available for it). (For example, so that a VM can notify dom0 that there are updates available for it).
By default, Qubes allows VMs initiate such communications in specific circumstances. By default, Qubes allows VMs to initiate such communications in specific circumstances.
The qrexec framework generalizes this process by providing a remote procedure call (RPC) protocol for the Qubes architecture. The qrexec framework generalizes this process by providing a remote procedure call (RPC) for the Qubes architecture.
It allows users and developers to use and design secure inter-VM tools. It allows users and developers to use and design secure inter-VM tools.
## Qrexec basics: architecture and examples ## Qrexec basics: architecture and examples
Qrexec is built on top of *vchan*, a Xen library providing data links between VMs. Qrexec is built on top of *vchan*, a Xen library providing data links between VMs.
During domain startup , a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM. During domain startup, a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM.
They are connected over a **vchan** channel. They are connected over a **vchan** channel.
`qrexec-daemon` listens for connections from a dom0 utility named `qrexec-client`. `qrexec-daemon` listens for connections from a dom0 utility named `qrexec-client`.
Let's say we want to start a process (call it `VMprocess`) in a VM (`someVM`). Let's say we want to start a process (call it `VMprocess`) in a VM (`someVM`).
@ -47,18 +47,18 @@ For example, the following command creates an empty file called `hello-world.txt
$ qrexec-client -e -d someVM user:'touch hello-world.txt' $ qrexec-client -e -d someVM user:'touch hello-world.txt'
``` ```
The string before the colon specifies what user to run the command as. 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` (whether the process creation succeeded). 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. With this option, no further data is passed between the domains.
By contrast, the following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell): The following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell):
``` ```
$ qrexec-client -d someVM user:bash $ qrexec-client -d someVM user:bash
``` ```
The `qvm-run` command is heavily based on `qrexec-client`. The `qvm-run` command is heavily based on `qrexec-client`.
It also takes care of additional activities, e.g. starting the domain if it is not up yet and starting the GUI daemon. It also handles additional activities, e.g. starting the domain if the domain is not up yet and starting the GUI daemon.
Thus, it is usually more convenient to use `qvm-run`. 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.
@ -70,17 +70,17 @@ For more details on the qrexec framework and protocol, see "[Qubes RPC internals
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).
The Qubes RPC framework was created to securely facilitate a range of such actions. The Qubes RPC framework was created to securely facilitate a range of such actions.
Obviously, inter-VM communication must be tightly controlled to prevent one VM from taking control of another, possibly more privileged, VM. Inter-VM communication must be tightly controlled to prevent one VM from taking control of another, possibly more privileged, VM.
Therefore the design decision was made to pass all control communication via dom0, that can enforce proper authorization. The design decision was made to pass all control communication via dom0 which can enforce proper authorization.
Then, it is natural to reuse the already-existing qrexec framework. It is therefore natural to reuse the already-existing qrexec framework.
Also, note that bare qrexec provides `VM <-> dom0` connectivity, but the command execution is always initiated by dom0. Note that bare qrexec provides `VM <-> dom0` connectivity, but the command execution is always initiated by dom0.
There are cases when VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed `.desktop` files). There are cases when a VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed `.desktop` files).
Thus, the framework allows dom0 to be the RPC target as well. This framework allows dom0 to be the RPC target as well.
Thanks to the framework, RPC programs are very simple -- both RPC client and server just use their stdin/stdout to pass data. Thanks to the framework, RPC programs are very simple -- both RPC client and server just use their stdin/stdout to pass data.
The framework does all the inner work to connect these processes to each other via `qrexec-daemon` and `qrexec-agent`. The framework does all the inner work to connect the processes to eachother via `qrexec-daemon` and `qrexec-agent`.
Additionally, disposable VMs are tightly integrated -- RPC to a DisposableVM is identical to RPC to a normal domain, all one needs is to pass `@dispvm` as the remote domain name. Disposable VMs are tightly integrated -- RPC to a DisposableVM is identical to RPC to an AppVM or StandaloneVM: all one needs is to pass `@dispvm` as the remote domain name.
## Qubes RPC administration ## Qubes RPC administration