From 7e1c5f5d1f24b3bd916f8ab0a27149104cc0aee6 Mon Sep 17 00:00:00 2001
From: Christian Schwarz <me@cschwarz.com>
Date: Mon, 22 Oct 2018 11:25:16 +0200
Subject: [PATCH] docs: discourage use of ssh+stdinserver transport due to
 inferior error handling

---
 docs/changelog.rst                | 3 +++
 docs/configuration/transports.rst | 7 +++++++
 2 files changed, 10 insertions(+)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index a5e2fb1..627daa4 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -49,6 +49,9 @@ Notes to Package Maintainers
   This functionality will cause SIGABRT on panics and can be used to capture a coredump of the panicking process.
   To that extend, make sure that your package build system, your OS's coredump collection and the Go delve debugger work together.
   Use your build system to package the Go program in `this tutorial on Go coredumps and the delve debugger <https://rakyll.org/coredumps/>`_ , and make sure the symbol resolution etc. work on coredumps captured from the binary produced by your build system. (Special focus on symbol stripping, etc.)
+* Use of ``ssh+stdinserver`` :ref:`transport <transport-ssh+stdinserver>` is no longer encouraged.
+  Please encourage users to use the new ``tcp`` or ``tls`` transports.
+  You might as well mention some of the :ref:`tunneling options listed here <transport-tcp-tunneling>`.
 
 Changes
 ~~~~~~~
diff --git a/docs/configuration/transports.rst b/docs/configuration/transports.rst
index 7e8fab2..a705bc9 100644
--- a/docs/configuration/transports.rst
+++ b/docs/configuration/transports.rst
@@ -29,6 +29,8 @@ This transport may also be used in conjunction with network-layer encryption and
 To make the IP-based client authentication effective, such solutions should provide authenticated IP addresses.
 Some options to consider:
 
+.. _transport-tcp-tunneling:
+
 * `WireGuard <https://www.wireguard.com/>`_: Linux-focussed, in-kernel TLS
 * `OpenVPN <https://openvpn.net/>`_: Cross-platform VPN, uses tun on \*nix
 * `IPSec <https://en.wikipedia.org/wiki/IPsec>`_: Properly standardized, in-kernel network-layer VPN
@@ -202,6 +204,11 @@ The serve & connect configuration will thus look like the following:
 ``ssh+stdinserver`` is inspired by `git shell <https://git-scm.com/docs/git-shell>`_ and `Borg Backup <https://borgbackup.readthedocs.io/en/stable/deployment.html>`_.
 It is provided by the Go package ``github.com/problame/go-netssh``.
 
+.. ATTENTION::
+
+   ``ssh+stdinserver`` has inferior error detection and handling compared to the ``tcp`` and ``tls`` transports.
+   If you require tested timeout & retry handling, use ``tcp`` or ``tls`` transports, or help improve package go-netssh.
+
 .. _transport-ssh+stdinserver-serve:
 
 Serve