Date: Mon, 31 Aug 2020 20:42:57 -0400
From: Bruce Momjian <bruce@momjian.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
Cc: Tom Lane <tgl@sss.pgh.pa.us>, karimelghazouly@gmail.com,
	Pg Docs <pgsql-docs@lists.postgresql.org>
Subject: Re: small clairifcation
Message-ID: <20200901004257.GU13613@momjian.us>
References: <159854511172.24991.4373145230066586863@wrigleys.postgresql.org>
 <3379769.1598577411@sss.pgh.pa.us>
 <CAKFQuwZZ2k0p=x1MPwGWQh1v8prq_efvNBs8ncsxrWOyd+45cg@mail.gmail.com>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="tThc/1wpZn/ma/RB"
Content-Disposition: inline
In-Reply-To: 
 <CAKFQuwZZ2k0p=x1MPwGWQh1v8prq_efvNBs8ncsxrWOyd+45cg@mail.gmail.com>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk


--tThc/1wpZn/ma/RB
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Thu, Aug 27, 2020 at 09:51:49PM -0700, David G. Johnston wrote:
> On Thu, Aug 27, 2020 at 6:17 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:
> 
>     PG Doc comments form <noreply@postgresql.org> writes:
>     > The following documentation comment has been logged on the website:
>     > Page: https://www.postgresql.org/docs/9.5/ssh-tunnels.html
>     > Description:
> 
>     > "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. "
> 
>     > as a beginner This took me some time to understand what do you mean by
>     "your
>     > server" "your end of the tunnel "
> 
>     Hm, do you have a suggestion for better wording?
> 
> 
> 
> I agree on the need for a different perspective here since it reads just fine
> once you know what it is talking about.
> 
> But absent that maybe a slightly more tutorial flow would be good.

I didn't think a tutorial flow was the right thing to here, so I
reworded the section to be more details and have a clearer flow ---
patch attached.

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EnterpriseDB                             https://enterprisedb.com

  The usefulness of a cup is in its emptiness, Bruce Lee


--tThc/1wpZn/ma/RB
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="ssh.diff"

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 6cda39f3ab..bc68ddc94b 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -2548,34 +2548,39 @@ openssl x509 -req -in server.csr -text -days 365 \
    First make sure that an <application>SSH</application> server is
    running properly on the same machine as the
    <productname>PostgreSQL</productname> server and that you can log in using
-   <command>ssh</command> as some user. Then you can establish a secure
-   tunnel with a command like this from the client machine:
+   <command>ssh</command> 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
+   <literal>localhost</literal> 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 <literal>foo.com</literal>:
 <programlisting>
 ssh -L 63333:localhost:5432 joe@foo.com
 </programlisting>
    The first number in the <option>-L</option> 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 <literal>foo.com</literal> 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., <literal>localhost</literal>, 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:
 <programlisting>
 psql -h localhost -p 63333 postgres
 </programlisting>
-   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 <literal>joe</literal> on host <literal>foo.com</literal>
-   connecting to <literal>localhost</literal> in that context, and it
+   connecting to the <literal>localhost</literal> 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
    <application>SSH</application> server and the
    <productname>PostgreSQL</productname> 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.
   </para>
 
   <para>
@@ -2587,12 +2592,12 @@ psql -h localhost -p 63333 postgres
   </para>
 
   <para>
-   You could also have set up the port forwarding as
+   You could also have set up port forwarding as
 <programlisting>
 ssh -L 63333:foo.com:5432 joe@foo.com
 </programlisting>
    but then the database server will see the connection as coming in
-   on its <literal>foo.com</literal> interface, which is not opened by
+   on its <literal>foo.com</literal> bind address, which is not opened by
    the default setting <literal>listen_addresses =
    'localhost'</literal>.  This is usually not what you want.
   </para>

--tThc/1wpZn/ma/RB--