qrexec-client-vm.rst 2.5 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879
  1. ================
  2. qrexec-client-vm
  3. ================
  4. NAME
  5. ====
  6. qrexec-client-vm - call Qubes RPC service
  7. SYNOPSIS
  8. ========
  9. | qrexec-client-vm *target_vmname* *service* [*local_program* [*local program arguments*]]
  10. DESCRIPTION
  11. ===========
  12. Call Qubes RPC (aka qrexec) service to a different VM. The service call request
  13. is sent to dom0, where Qubes RPC policy is evaluated and when it allows the
  14. call, it is forwarded to appropriate target VM (which may be different than
  15. requested, if policy says so). Local program (if given) is started only
  16. when service call is allowed by the policy.
  17. Remote service can communicate with the caller (``qrexec-client-vm``) using
  18. stdin/stdout. When *local_program* is given, its stdin/stdout is connected to
  19. service stdin/stdout (stderr is not redirected), otherwise - service
  20. stdin/stdout is connected to those of ``qrexec-client-vm``.
  21. OPTIONS
  22. =======
  23. *target_vmname*
  24. Name of target VM to which service is requested. Qubes RPC policy may
  25. ignore this value and redirect call somewhere else.
  26. This argument, can contain VM name, or one of special values:
  27. * ``$default`` or empty string - let Qubes RPC policy decide, without giving any preference
  28. * ``$dispvm`` - new Disposable VM
  29. * ``$dispvm:dispvm-template`` - new Disposable VM based on *dispvm-template*
  30. This field is limited to 31 characters (alphanumeric, plus ``-_.$``).
  31. *service*
  32. Requested service. Besides service name, it can contain a service argument
  33. after ``+`` character. For example ``some.service+argument``.
  34. This field is limited to 63 characters (alphanumeric, plus ``-_.$+``).
  35. *local_program*
  36. Full path to local program to be connected with remote service. Optional.
  37. *local program arguments*
  38. Arguments to *local_program*. Optional.
  39. EXIT STATUS
  40. ===========
  41. If service call is allowed by dom0 and ``qrexec-client-vm`` is started without
  42. *local_program* argument, it reports remote service exit code.
  43. If service call is allowed by dom0 and ``qrexec-client-vm`` is started with
  44. *local_program* argument, it reports the local program exit code. There is no
  45. way to learn exit code of remote service in this case.
  46. In both cases, if process (local or remote) was terminated by a signal, exit
  47. status is 128+signal number.
  48. If service call is denied by dom0, ``qrexec-client-vm`` exit with status 126.
  49. AUTHORS
  50. =======
  51. | Joanna Rutkowska <joanna at invisiblethingslab dot com>
  52. | Rafal Wojtczuk <rafal at invisiblethingslab dot com>
  53. | Marek Marczykowski-Górecki <marmarek at invisiblethingslab dot com>