From ff26dcfe5306b1e93d9a2797149529cbc9409a44 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?=
 <marmarek@invisiblethingslab.com>
Date: Tue, 20 Jun 2017 23:34:43 +0200
Subject: [PATCH] Add qrexec-client-vm man page

This clarifies and also defines some corner cases like exit code
reporting.

QubesOS/qubes-issues#2861
---
 debian/qubes-core-agent-qrexec.install |  1 +
 doc/vm-tools/qrexec-client-vm.rst      | 76 ++++++++++++++++++++++++++
 rpm_spec/core-agent.spec               |  1 +
 3 files changed, 78 insertions(+)
 create mode 100644 doc/vm-tools/qrexec-client-vm.rst

diff --git a/debian/qubes-core-agent-qrexec.install b/debian/qubes-core-agent-qrexec.install
index 7dc25d6..1c61677 100644
--- a/debian/qubes-core-agent-qrexec.install
+++ b/debian/qubes-core-agent-qrexec.install
@@ -5,3 +5,4 @@ usr/lib/qubes/qrexec-agent
 usr/lib/qubes/qrexec-client-vm
 usr/lib/qubes/qrexec_client_vm
 usr/lib/qubes/qubes-rpc-multiplexer
+usr/share/man/man1/qrexec-client-vm.1.gz
diff --git a/doc/vm-tools/qrexec-client-vm.rst b/doc/vm-tools/qrexec-client-vm.rst
new file mode 100644
index 0000000..cdb10e5
--- /dev/null
+++ b/doc/vm-tools/qrexec-client-vm.rst
@@ -0,0 +1,76 @@
+================
+qrexec-client-vm
+================
+
+NAME
+====
+qrexec-client-vm - call Qubes RPC service
+
+SYNOPSIS
+========
+| qrexec-client-vm *target_vmname* *service* [*local_program* [*local program arguments*]]
+
+DESCRIPTION
+===========
+
+Call Qubes RPC (aka qrexec) service to a different VM. The service call request
+is sent to dom0, where Qubes RPC policy is evaluated and when it allows the
+call, it is forwarded to appropriate target VM (which may be different than
+requested, if policy says so). Local program (if given) is started only
+when service call is allowed by the policy.
+
+Remote service can communicate with the caller (``qrexec-client-vm``) using
+stdin/stdout.  When *local_program* is given, its stdin/stdout is connected to
+service stdin/stdout (stderr is not redirected), otherwise - service
+stdin/stdout is connected to those of ``qrexec-client-vm``.
+
+OPTIONS
+=======
+
+*target_vmname*
+
+    Name of target VM to which service is requested. Qubes RPC policy may
+    ignore this value and redirect call somewhere else.
+
+    This argument, can contain VM name, or one of special values:
+
+    * ``$default`` or empty string - let Qubes RPC policy decide, without giving any preference 
+
+    * ``$dispvm`` - new Disposable VM
+
+    * ``$dispvm:dispvm-template`` - new Disposable VM based on *dispvm-template*
+
+    This field is limited to 31 characters (alphanumeric, plus ``-_.$``).
+
+*service*
+
+    Requested service. Besides service name, it can contain a service argument
+    after ``+`` character. For example ``some.service+argument``.
+
+    This field is limited to 63 characters (alphanumeric, plus ``-_.$+``).
+
+*local_program*
+
+    Full path to local program to be connected with remote service. Optional.
+
+*local program arguments*
+
+    Arguments to *local_program*. Optional.
+
+EXIT STATUS
+===========
+
+If service call is allowed by dom0 and ``qrexec-client-vm`` is started without
+*local_program* argument, it reports remote service exit code.
+
+If service call is allowed by dom0 and ``qrexec-client-vm`` is started with
+*local_program* argument, it reports the local program exit code. There is no
+way to learn exit code of remote service in this case.
+
+If service call is denied by dom0, ``qrexec-client-vm`` exit with status 126.
+
+AUTHORS
+=======
+| Joanna Rutkowska <joanna at invisiblethingslab dot com>
+| Rafal Wojtczuk <rafal at invisiblethingslab dot com>
+| Marek Marczykowski-Górecki <marmarek at invisiblethingslab dot com>
diff --git a/rpm_spec/core-agent.spec b/rpm_spec/core-agent.spec
index 6699930..3cc098f 100644
--- a/rpm_spec/core-agent.spec
+++ b/rpm_spec/core-agent.spec
@@ -618,6 +618,7 @@ rm -f %{name}-%{version}
 /usr/lib/qubes/qrexec_client_vm
 /usr/lib/qubes/qubes-rpc-multiplexer
 /lib/systemd/system/qubes-qrexec-agent.service
+%{_mandir}/man1/qrexec-client-vm.1*
 
 %files nautilus
 /usr/lib/qubes/qvm-copy-to-vm.gnome