openssh unix dev - Sep 2012 - ssh(1) documentation for -L and -R

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.

================ ssh.1.patch ===============--- ssh.1	2012/09/15 16:08:48	1.1
+++ ssh.1	2012/09/15 20:23:35
@@ -51,13 +51,13 @@
 .Op Fl F Ar configfile
 .Op Fl I Ar pkcs11
 .Op Fl i Ar identity_file
-.Op Fl L Oo Ar bind_address : Oc Ns Ar port : Ns Ar host : Ns Ar hostport
+.Op Fl L Oo Ar bind_address : Oc Ns Ar localport : Ns Ar remoteaddr : Ns Ar
remoteport
 .Op Fl l Ar login_name
 .Op Fl m Ar mac_spec
 .Op Fl O Ar ctl_cmd
 .Op Fl o Ar option
 .Op Fl p Ar port
-.Op Fl R Oo Ar bind_address : Oc Ns Ar port : Ns Ar host : Ns Ar hostport
+.Op Fl R Oo Ar bind_address : Oc Ns Ar remoteport : Ns Ar localaddr : Ns Ar
localport
 .Op Fl S Ar ctl_path
 .Op Fl W Ar host : Ns Ar port
 .Op Fl w Ar local_tun Ns Op : Ns Ar remote_tun
@@ -296,26 +296,37 @@
 .It Fl L Xo
 .Sm off
 .Oo Ar bind_address : Oc
-.Ar port : host : hostport
+.Ar localport : remoteaddr : remoteport
 .Sm on
 .Xc
-Specifies that the given port on the local (client) host is to be
-forwarded to the given host and port on the remote side.
+Specifies that the given TCP port
+.Ar localport
+on the local (client) host is to be
+forwarded to the given
+.Ar remoteaddr
+and
+.Ar remoteport
+on the remote side.
 This works by allocating a socket to listen to
-.Ar port
+.Ar localport
 on the local side, optionally bound to the specified
 .Ar bind_address .
 Whenever a connection is made to this port, the
 connection is forwarded over the secure channel, and a connection is
 made to
-.Ar host
+.Ar remoteaddr
 port
-.Ar hostport
+.Ar remoteport
 from the remote machine.
+.Ar remoteaddr
+is resolved on the remote machine.
 Port forwardings can also be specified in the configuration file.
 IPv6 addresses can be specified by enclosing the address in square brackets.
-Only the superuser can forward privileged ports.
-By default, the local port is bound in accordance with the
+Only the superuser can forward a privileged
+.Ar localport .
+By default, the
+.Ar localport
+is bound in accordance with the
 .Cm GatewayPorts
 setting.
 However, an explicit
@@ -488,23 +499,31 @@
 .It Fl R Xo
 .Sm off
 .Oo Ar bind_address : Oc
-.Ar port : host : hostport
+.Ar remoteport : localaddr : localport
 .Sm on
 .Xc
-Specifies that the given port on the remote (server) host is to be
-forwarded to the given host and port on the local side.
+Specifies that the given TCP port
+.Ar remoteport
+on the remote (server) host is to be
+forwarded to the given
+.Ar localaddr
+and
+.Ar localport
+on the local side.
 This works by allocating a socket to listen to
-.Ar port
+.Ar remoteport
 on the remote side, and whenever a connection is made to this port, the
 connection is forwarded over the secure channel, and a connection is
 made to
-.Ar host
+.Ar localaddr
 port
-.Ar hostport
+.Ar localport
 from the local machine.
 .Pp
 Port forwardings can also be specified in the configuration file.
-Privileged ports can be forwarded only when
+A privileged
+.Ar remoteport
+ can be forwarded only when
 logging in as root on the remote machine.
 IPv6 addresses can be specified by enclosing the address in square brackets.
 .Pp
@@ -525,7 +544,7 @@
 .Xr sshd_config 5 ) .
 .Pp
 If the
-.Ar port
+.Ar remoteport
 argument is
 .Ql 0 ,
 the listen port will be dynamically allocated on the server and reported
@@ -972,12 +991,12 @@
 .Dq #users ,
 nickname
 .Dq pinky ,
-using port 1234.
+using port 1234/TCP.
 It doesn't matter which port is used,
 as long as it's greater than 1023
 (remember, only root can open sockets on privileged ports)
 and doesn't conflict with any ports already in use.
-The connection is forwarded to port 6667 on the remote server,
+The connection is forwarded to port 6667/TCP on the remote server,
 since that's the standard port for IRC services.
 .Pp
 The
================ end ================

Hi,

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. 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.

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.

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?

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

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

Bert

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.

I guess this is what the patch wants to clarify.


//Peter