Skip to content

Commit 23944c8

Browse files
Thomas Prestonjluebbe
authored andcommitted
doc/overview: clarify proxy mechanism for exporter
Resources made available via the exporter specify a proxy hostname, which takes precedence over LG_PROXY even when --isolated is not set. I've changed the documentation to reflect this behaviour. Signed-off-by: Thomas Preston <thomas.preston@codethink.co.uk> [jlu: updated commit message to match the content] Signed-off-by: Jan Luebbe <jlu@pengutronix.de>
1 parent 3eb7807 commit 23944c8

File tree

3 files changed

+24
-13
lines changed

3 files changed

+24
-13
lines changed

CHANGES.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ New Features in 0.4.0
1616
The 256-color schemes now use purple instead of green for the ``run`` lines to
1717
make them easier distinguishable from pytest's "PASSED" output.
1818
- Network controlled relay providing GET/PUT based REST API
19+
- Improved LG_PROXY documentation in docs/usage.rst.
1920

2021
Bug fixes in 0.4.0
2122
~~~~~~~~~~~~~~~~~~

doc/overview.rst

Lines changed: 19 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -352,6 +352,8 @@ file names refer to a shared filesystem (such as NFS or SMB).
352352
For exporters which are not directly accessible via SSH, add the host to your
353353
.ssh/config file, with a ProxyCommand when need.
354354

355+
.. _overview-proxy-mechanism:
356+
355357
Proxy Mechanism
356358
~~~~~~~~~~~~~~~
357359

@@ -360,17 +362,22 @@ connections to a remote host. To enable and force proxy mode on the exporter use
360362
the :code:`-i` or :code:`--isolated` command line option. This indicates to clients that all
361363
connections to remote resources made available by this exporter need to be
362364
tunneled using a SSH connection.
363-
On the other hand, clients may need to access the remote infrastrucure using a
364-
SSH tunnel. In this case the :code:`LG_PROXY` environment variable needs to be
365-
set to the remote host which should tunnel the connections. The client then
366-
forwards all network traffic through SSH, even the coordinator connection is
367-
forwarded. This means that with :code:`LG_PROXY` and :code:`LG_CROSSBAR` labgrid can be used
368-
fully remotely with only a SSH connection as a requirement.
369-
One remaining issue here is the forward of UDP connections, which is currently
370-
not possible. UDP connections are used by some of the power backends in the form
371-
of SNMP.
365+
366+
On the other hand, clients may need to access the remote coordinator
367+
infrastrucure using a SSH tunnel. In this case the :code:`LG_PROXY` environment
368+
variable needs to be set to the remote host which should tunnel the connection
369+
to the coordinator. The client then forwards all network traffic -
370+
client-to-coordinator and client-to-exporter - through SSH, via their
371+
respective proxies. This means that with :code:`LG_PROXY` and
372+
:code:`LG_CROSSBAR` labgrid can be used fully remotely with only a SSH
373+
connection as a requirement.
372374

373375
.. note::
374-
Labgrid prefers to connect to an isolated exporter over using the LG_PROXY
375-
variable. This means that for an isolated exporter, a correct entry for the
376-
exporter needs to be set up in the ~/.ssh/config file.
376+
Labgrid prefers to connect to an exporter-defined proxy over using the
377+
LG_PROXY variable. This means that a correct entry for the exporter needs to
378+
be set up in the ~/.ssh/config file. You can view exporter proxies with
379+
:code:`labgrid-client -v resources`.
380+
381+
One remaining issue here is the forward of UDP connections, which is currently
382+
not possible. UDP connections are used by some of the power backends in the
383+
form of SNMP.

doc/usage.rst

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -356,7 +356,10 @@ Takes effect only when used with ``--lg-colored-steps``.
356356
LG_PROXY
357357
^^^^^^^^
358358
Specifies a SSH proxy host to be used for port forwards to access the
359-
coordinator and network resources.
359+
coordinator. Network resources made available by the exporter will prefer their
360+
own proxy, and only fallback to LG_PROXY.
361+
362+
See also :ref:`overview-proxy-mechanism`.
360363

361364
Simple Example
362365
~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)