doc: clarify the use of ssh port forwarding

Reported-by: [email protected]
Discussion: https://postgr.es/m/159854511172.24991.4373145230066586863@wrigleys.postgresql.org

Backpatch-through: 9.5

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index f975406acd67a57943f3270cd8b46cda254279b1..418aa3f85c7a5354e266143626aefb367366dcb6 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2611,34 +2611,39 @@ openssl x509 -req -in server.csr -text -days 365 \
    First make sure that an SSH server is
    running properly on the same machine as the
    PostgreSQL server and that you can log in using
-   ssh as some user. Then you can establish a secure
-   tunnel with a command like this from the client machine:
+   ssh as some user;  you then can establish a
+   secure tunnel to the remote server.  A secure tunnel listens on a
+   local port and forwards all traffic to a port on the remote machine.
+   Traffic sent to the remote port can arrive on its
+   localhost address, or different bind
+   address if desired;  it does not appear as coming from your
+   local machine.  This command creates a secure tunnel from the client
+   machine to the remote machine foo.com:
 
 ssh -L 63333:localhost:5432 [email protected]
 
    The first number in the -L argument, 63333, is the
-   port number of your end of the tunnel; it can be any unused port.
-   (IANA reserves ports 49152 through 65535 for private use.)  The
-   second number, 5432, is the remote end of the tunnel: the port
-   number your server is using. The name or IP address between the
-   port numbers is the host with the database server you are going to
-   connect to, as seen from the host you are logging in to, which
-   is foo.com in this example. In order to connect
-   to the database server using this tunnel, you connect to port 63333
-   on the local machine:
+   local port number of the tunnel; it can be any unused port.  (IANA
+   reserves ports 49152 through 65535 for private use.)  The name or IP
+   address after this is the remote bind address you are connecting to,
+   i.e., localhost, which is the default.  The second
+   number, 5432, is the remote end of the tunnel, e.g., the port number
+   your database server is using.  In order to connect to the database
+   server using this tunnel, you connect to port 63333 on the local
+   machine:
 
 psql -h localhost -p 63333 postgres
 
-   To the database server it will then look as though you are really
+   To the database server it will then look as though you are
    user joe on host foo.com
-   connecting to localhost in that context, and it
+   connecting to the localhost bind address, and it
    will use whatever authentication procedure was configured for
-   connections from this user and host.  Note that the server will not
+   connections by that user to that bind address.  Note that the server will not
    think the connection is SSL-encrypted, since in fact it is not
    encrypted between the
    SSH server and the
    PostgreSQL server.  This should not pose any
-   extra security risk as long as they are on the same machine.
+   extra security risk because they are on the same machine.
   
 
   
@@ -2650,12 +2655,12 @@ psql -h localhost -p 63333 postgres
   
 
   
-   You could also have set up the port forwarding as
+   You could also have set up port forwarding as
 
 ssh -L 63333:foo.com:5432 [email protected]
 
    but then the database server will see the connection as coming in
-   on its foo.com interface, which is not opened by
+   on its foo.com bind address, which is not opened by
    the default setting listen_addresses =
    'localhost'.  This is usually not what you want.