doc: update qrexec-remotevm

Author: fepitre

doc/qrexec-remotevm.rst

@@ -102,13 +102,27 @@ SSH-based communication between Local‑Relay and Remote‑Relay
 ------------------------------------------------------------
 
 Prerequisites
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 - SSH key-based authentication is configured between all involved hosts (Local‑Relay, Remote‑Relay, and any intermediate jump hosts).
 - (Optional) Configure any necessary proxies or jump hosts by following the OpenSSH Cookbook guidelines: Proxies and Jump Hosts <https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Proxies_and_Jump_Hosts>.
 
-Example Transport RPC: ``qubesair.SSHProxy``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Workflow Overview
+^^^^^^^^^^^^^^^^^
+
+1. **Local-Qube to Local-Relay**: The `transport_rpc` property of `Remote‑Relay` is used to refer to RPC call to be made from Local-Qube to Local-Relay with arguments of the form:
+
+   ``Remote-Qube+<service>``
+
+    where `<service>` contains the original service with argument that has been processed by policies.
+
+2. **Destination lookup**: The RPC script extracts `Remote-Qube` and queries QubesDB `/remotes/Remote-Qube` on Local‑Relay to verify and translate it into the actual qube name in `Remote-QubesOS` (in this example it is assumed to be the same).
+    The QubesDB path is set based on `Remote-Qube` property `remote_name`.
+
+3. **RPC**: The RPC connects to Remote‑Relay and runs ``qrexec-client-vm`` on that host.
+
+4. **Remote-QubesOS policy evaluation**: `Remote‑QubesOS` applies its policy rules for a request from `Local‑Relay` to `Remote‑Qube` with information that source qube is `Local-Qube`.
+    The information about source qube has to be resolved to a registered RemoteVM into `Remote-QubesOS` referencing `Local-Qube`.
 
 Below is an example Bash script implementing the ``qubesair.SSHProxy`` transport RPC. It parses a destination and service, looks up the remote Qube name, and invokes ``qrexec-client-vm`` over SSH.
 
@@ -143,31 +157,19 @@ Below is an example Bash script implementing the ``qubesair.SSHProxy`` transport
    # Forward the qrexec call via SSH
    ssh "$remote_qube" qrexec-client-vm --source-qube="$QREXEC_REMOTE_DOMAIN" "$remote_qube" "$service"
 
-Workflow Overview
-"""""""""""""""""
-
-1. **Local-Qube to Local-Relay**: A Qubes RPC call is made from Local-Qube to Local-Relay with arguments of the form:
-
-   ``Remote-Qube+<service>``
-
-    where `<service>` contains the original service with argument that has been processed by policies.
-
-2. **Destination lookup**: The RPC script extracts `Remote-Qube` and queries QubesDB on Local‑Relay to verify and translate it into the actual qube name in `Remote-QubesOS` (in this example it is assumed to be the same).
-
-3. **SSH**: The script uses SSH to connect to the identified host (configured to forward to the Remote‑Relay). It then runs ``qrexec-client-vm`` on that host, passing along the original source domain via the environment variable ``$QREXEC_REMOTE_DOMAIN``.
-
-4. **Remote-QubesOS policy evaluation**: `Remote‑QubesOS` applies its policy rules for a request from `Local‑Relay` to `Remote‑Qube` with information that source qube is `Local-Qube`.
+.. note::
+    Using QREXEC_REMOTE_DOMAIN directly here assumes that a RemoteVM called `Local-Qube` exists in `Remote-QubesOS`.
 
 SSH Client Configuration Hint
 +++++++++++++++++++++++++++++
 
-To ensure that any SSH connection to a given host actually lands on the corresponding `Remote‑Relay`, add an entry like the following to your ``/etc/ssh/ssh_config``:
+To ensure that any SSH connection to a given host actually lands on the corresponding `Remote‑Relay`, add an entry like the following to your ``~/.ssh/config``:
 
 .. code-block:: ini
 
    Host *
        HostName <Remote-Relay_ip>
 
 Adjust the pattern, hostname, and jump host settings to match your environment.
-This guarantees that SSH connections intended for a RemoteVM are transparently proxied through Remote‑Relay./
+This guarantees that SSH connections intended for a RemoteVM are transparently proxied through Remote‑Relay.