ssh(1) documentation for -L and -R

[D. Hugh Redelmeier]

[Please excuse my awkward reply.  I'm not used to replying on a mailing 
list that I'm not subscribed to.]

Thanks very much for looking at my suggestions.

I had avoided using SSH tunnels because I found the description opaque.
But this last week, I broke down and decided I really needed to use
them.

Once I'd figured them out, they were easy, and I thought I could
improve ssh(1)'s description.

Why should you listen to me?  Because I'm sort of new at this and
don't come in already understanding what the documentation says: fresh
eyes.

Why you should not listen to me?  I'm not an SSH guru.

So: my short email was a "solution" but you should perhaps listen to
my problems and come up with better solutions.

| From: bert.wesarg at googlemail.com (Bert Wesarg)
| 
| On Sun, Sep 16, 2012 at 12:06 AM, D. Hugh Redelmeier <hugh at mimosa.com> wrote:
| > I found that the documentation for -L and -R was hard to understand.
| > So I made some changes to try to make it clearer.  I started with Revision
| > 1.328 from http://www.openbsd.org/cgi-bin/cvsweb/src/usr.bin/ssh/ssh.1
| >
| > Comments welcome.
| 
| I think the 'remote' in here
| 
| > --L port:host:hostport
| > +-L localport:remoteaddr:remoteport
| 
| and the 'local' in here
| 
| > --R port:host:hostport
| > +-R remoteport:localaddr:localport
| 
| is now totally misleading. It suggest that the host:port has anything
| to do with the corresponding side, which is not.

I don't understand what you are saying.  What is host:port?  I don't
see that literally anywhere.

| Read this again:
| 
|   Specifies that the given port on the local (client) host is to be
|   forwarded to the given host and port on the remote side.

"given port" ought to be "given _port_" to link it to the synopsis.
"given host and port" ought to be "given _host_ and _hostport_" for the
same reason.  Otherwise the reader cannot easily know what is being
referenced.  The word "given" is rather weak and confusing (even so,
I kept it out of conservatism).

| It states clearly, that the connection is made from the remote side to
| host:port. And now it reads:
| 
|   Specifies that the given TCP port localport on the local (client)
| host is to be
|   forwarded to the given remoteaddr and remoteport on the remote side.

Please: the underscores/italics matter in linking the prose to the
synopsis.

| But now, why do I need to specify 'remoteaddr', if it makes a
| connection to the 'remote side', because 'remoteaddr' and 'remote
| side' is equal, isn't it?

You are right that the terse terminology is still somewhat ambiguous.
I meant "address on the remote side", not "address of the remote
side".  If the prose does not make that clear, that is a weakness that
I did not introduce.

Would you prefer _portonremote_ or _port_on_remote_ to _remoteport_?

| One possible improvement, could be to use targethost:targetport for
| both, -L and -R.

I think that "target" is a fine word.  What I was trying to do was
make the visual representation (synopsis) communicate a very important
feature:  the host and port are from the "point of view" of the
remote system.

Of course it is important to have it in the text, but the diagram is
what people look at to remember the structure.  So it must have the
important conceptual information (and still be compact).

So what is the important stuff that I missed when I first read
ssh(1)?

- The only mention that port forwarding only applied to TCP was
  a passing reference in the last sentence of the first paragraph,
  far from the description of -L and -R.
  [So I sprinkled "TCP" once in the description of -L and once
  in the description of -R]

- in my testing, I wanted the remotehost (my term) to be 127.0.0.1.
  I thought that saying "localhost" would be better than either
  leaving it blank or using 127.0.0.1.  But on my local machine
  I needed to use "localhost4" to be unambiguous.

  This was a disaster because the remote machine (which resolved
  remotehost) had never heard of localhost4, tried to resolve it,
  failed, and generated a totally useless/misleading/unclear
  diagnostic on my (local) end:

	channel 3: open failed: administratively prohibited: open failed

  I went off on a wild-goose chase thinking the problem was that the
  remoteport was privileged (it was privileged, but that's not a
  problem).

  The best fix would be a better diagnostic, but I didn't have the
  time to dive into the code to figure out how to do that (for all
  I know, it might take a protocol change!).

  Instead, I thought that clarifying where it gets resolved would
  at least help and be very appropriate for a manpage.

- I was surprised to find that the local packet could be IPv6 and
  the packet on the other side of the tunnel could be IPv4.  At least
  that seemed to be the case.  I didn't do enough testing to be sure
  but if so, the full generality of this neat feature should be
  documented.  Because I wasn't sure, I didn't document it.


- the -L synopsis was: -L [bind_address:]port:host:hostport

  In the prose, the "_port_" value was referenced in "the given port
  on the local (client) host", "port on the local side", "this port",
  "local port", and "listening port", and "the port".  Surely these
  should be "_port_" to link each reference more clearly to the
  synopsis and each other.

  Also in the prose, "port on the remote side", and "host port
  _hostport_" refer to _hostport_.

  + Surely all ports are on hosts, so "_hostport_" isn't a very good
    name.  I thought "_remoteport_" would be more descriptive.

  It is a small leap to change "port" to "localport".

  + it more clearly distinguishes it from "hostport"

  + the synopsis communicates more topological information

  + the generality of "port" is narrowed appropriately.

- in that same synopsis, "host" is also a too-general word:
  there are potentially several hosts involved: the client host,
  the server host, the host from which the original packet
  originated (it might not be the client), and the "target" host
  where the packet goes from the server.  All these hosts
  might not be distinct, but they could be.

  What is good nomenclature for these hosts?  Perhaps we don't
  need to name all of them.  I used local and remote for the
  SSH client and SSH server machines, following the existing
  pattern.  Certainly the bare word "host" is too ambiguous
  for good exposition.  Perhaps "target" is good for the
  ultimate target of the packets.

  Some of this is on thin ice since TCP connections are bidirectional.


- "bind_address" is a bit odd.  I don't have an immediate suggestion
  for improvement.  "localhost"?  Oops: that's a well-known-name
  that isn't general enough.

  That's why I used "localaddr" in -R instead of "localhost" so
  symmetry drove the decision to use "remoteaddr" in -L.

  PERHAPS -L's "bind_address" could be renamed "localaddr"
  and -R's "bind_address" could be renamed "remoteaddr"


| Using 'localport' in -L and 'remoteport' in -R does sounds like an
| improvement to me.

Good!


| From: peter at stuge.se (Peter Stuge)

| Bert Wesarg wrote:
| > totally misleading. It suggest that the host:port has anything
| > to do with the corresponding side, which is not.
| 
| The destination in both -L and -R is only ever used on the respective
| side. host in -L is resolved locally, host in -R is resolved remotely.

Quite true (when reversed) and important and possibly not obvious (I
didn't get it at first).

| I guess this is what the patch wants to clarify.

It is part of what I was trying to clarify.


| From: bert.wesarg at googlemail.com (Bert Wesarg)
| 
| On Mon, Sep 17, 2012 at 8:09 AM, Peter Stuge <peter at stuge.se> wrote:

| > I guess this is what the patch wants to clarify.
| 
| I hoped I understood the intention of the patch, but the proposed new
| namings are misleading. And I think adding 'remote' to the host name
| in -L does not makes it clearer that it will be resolved on the remote
| size.

I agree: that wasn't my main purpose in the naming.  It was to point
out that the remoteaddr and remoteport were interpreted and used on
the remote site, with all the corresponding implications.  Similarly,
localport 


| From: peter at stuge.se (Peter Stuge)

| Bert Wesarg wrote:

| Right, maybe changing only the wording and not the parameter names is
| a good middle road?

I still think that some improvement to the synopsis naming is
possible.  I'm not adamant about my choices.

| > I think adding 'remote' to the host name in -L does not makes it
| > clearer that it will be resolved on the remote size.
| 
| I agree with that. I think it's better to keep it called host and use
| prose to explain how it works.

As argued above, resolution is not the only issue.  And "host" is way
too ambiguous given that up to four hosts are involved.