improve labgrid tls docs

Signed-off-by: Asher Pemberton <asher.pemberton@arm.com>
Reviewed-by: Asher Pemberton <asher.pemberton@arm.com> # gatekeeper

Author: asher-pem-arm

doc/getting_started.rst

@@ -446,12 +446,14 @@ Refer to the ``labgrid-coordinator`` man page for details.
 
 When you are connecting with ``labgrid-client`` or ``labgrid-exporter`` to a
 ``labgrid-coordinator`` that has TLS gRPC channels enabled you need to pass
-the ``--tls`` (and ``--cert`` if the certificate is not trusted by the host
-machine) option.
+the ``--tls`` option. If ``--cert`` is not set, labgrid uses the host CA
+certificates to verify the coordinator certificate. Use ``--cert`` to provide
+a specific CA certificate instead.
 Refer to the ``labgrid-client`` and ``labgrid-exporter`` man pages for details.
 For ``RemotePlace`` connections from an environment config, set the
-``coordinator_tls`` option or ``LG_COORDINATOR_TLS``. If the certificate
-is not trusted by the host machine, set ``coordinator_cert`` in the config.
+``coordinator_tls`` option or ``LG_COORDINATOR_TLS``. If ``coordinator_cert``
+is not set, labgrid uses the host CA certificates. Set ``coordinator_cert``
+to provide a specific CA certificate instead.
 
 Using a Strategy
 ----------------

doc/man/coordinator.rst

@@ -34,6 +34,32 @@ OPTIONS
 -d, --debug
     enable debug mode
 
+TLS WITH A REVERSE PROXY
+------------------------
+
+Instead of enabling TLS in ``labgrid-coordinator`` directly, a reverse proxy can
+terminate TLS and forward cleartext gRPC to the coordinator. For example, with
+``nginx``:
+
+.. code-block:: nginx
+
+   server {
+       listen 20407 ssl http2;
+       server_name labgrid.example.com;
+
+       ssl_certificate     /etc/ssl/labgrid-coordinator.crt;
+       ssl_certificate_key /etc/ssl/labgrid-coordinator.key;
+
+       location / {
+           grpc_pass grpc://127.0.0.1:20408;
+       }
+   }
+
+In this setup, start ``labgrid-coordinator`` without ``--tls`` and point
+``labgrid-client`` and ``labgrid-exporter`` at the reverse proxy using
+``--tls``.
+
+
 SEE ALSO
 --------
 

man/labgrid-coordinator.1

@@ -63,6 +63,33 @@ path to TLS key (in PEM format)
 .B  \-d\fP,\fB  \-\-debug
 enable debug mode
 .UNINDENT
+.SS TLS WITH A REVERSE PROXY
+.sp
+Instead of enabling TLS in \fBlabgrid\-coordinator\fP directly, a reverse proxy can
+terminate TLS and forward cleartext gRPC to the coordinator. For example, with
+\fBnginx\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.EX
+server {
+    listen 20407 ssl http2;
+    server_name labgrid.example.com;
+
+    ssl_certificate     /etc/ssl/labgrid\-coordinator.crt;
+    ssl_certificate_key /etc/ssl/labgrid\-coordinator.key;
+
+    location / {
+        grpc_pass grpc://127.0.0.1:20408;
+    }
+}
+.EE
+.UNINDENT
+.UNINDENT
+.sp
+In this setup, start \fBlabgrid\-coordinator\fP without \fB\-\-tls\fP and point
+\fBlabgrid\-client\fP and \fBlabgrid\-exporter\fP at the reverse proxy using
+\fB\-\-tls\fP\&.
 .SS SEE ALSO
 .sp
 \fBlabgrid\-client\fP(1), \fBlabgrid\-exporter\fP(1)