StdioTunnel — multiplex arbitrary TCP connections over the standard input/output of a connecting process
StdioTunnel [-l] [-D] [-V] [-t] [-T] [[-L] | [-R]connection-spec...] {-e connection command}
StdioTunnel {-r} [-D] [-V]
Sometimes, you can get a connection to a remote host that gives you command-line access, as with ssh, but nothing else. You'd like to use different kinds of connection-oriented protocols between your machine and the remote host, such as vnc or imap. ssh provides the option of forwarding TCP ports for such purposes, but sometimes this facility is disabled. You might also create a ppp link over such a connection, but you might lack permissions on one end or the other required to do so. It is in this circumstance (however rare it may be) that StdioTunnel is useful. It assumes nothing more than that you can run a command (such as rsh, ssh or telnet) on your local machine that will give command-line access to (technically, an 8-bit clear path to the standard input and standard output or a process on) a remote machine, and that StdioTunnel exists on both machines. If you can get command-line access, you can use StdioTunnel to do TCP port forwarding.
The StdioTunnel command takes two forms, one on the local (originating) side of the connection and one on the remote.
You originate a StdioTunnel connection with the Local form; the local form is indicated with the -l but this may be omitted because it is the default. You will also need to supply one or more connection-spec arguments to specify the TCP connections that StdioTunnel will carry. These arguments are designed to be familiar to those who have used the port forwarding capabilities of ssh.
The connection-spec consists of three or four fields separated by colons (:) in the form listen port:connect host:connect port[:flag characters].
You can use the arguments to define any number of either of two kinds of connections:
A connection-spec may also have flag characters, single characters appearing in the optional fourth part of the connection-spec. The supported flags are:
Normally, when StdioTunnel creates a listen port, it binds it only to the loopback address, so connections may be made to it only from the host on which StdioTunnel is running. This flag--for [p]romiscuous--binds the port to any incoming address, so StdioTunnel will forward connection attempts from any host. This is an even bigger security risk than the normal operation of StdioTunnel, so this flag should be used with care.
Note: On some platforms (i.e., Mac OS/X) binding to the loopback address does not appear to work, so you must specify promiscuous for any connection that is to listen on that platform.
In addition to the connection definitions, when starting the local StdioTunnel you must use the -e to specify a connection command. The conection command is a single argument that is interpreted as a complete command line, so make sure it is quoted properly. The command line is passed to your shell; the resulting process runs as if you had started it directly from your command line. Before passing it to you, StdioTunnel reads the process' output, looking for the handshaking string from the remote side of StdioTunnel.
Whatever connection command you specify, it is very important that it provide an 8-bit clear data path. If the connection allows for any escape characters to trigger special behavior, the escapes will interfere with the StdioTunnel data passed over the connection. For the telnet command, you might specify the -8 -E flags; for the ssh, the -e none flag.
After you've connected to the remote machine, you must start StdioTunnel there with the -r in order to start the remote side of the connection. The two StdioTunnel processes will perform a simple handshake over the connection and if successful they will be able to do the TCP port forwarding specified on the Local Side command line.
StdioTunnel -l -L 2001:localhost:22:a -L 5900:localhost:5900 -e "ssh -e none remotehost.remotedomain.com"
In this example StdioTunnel is initiating a connection to remotehost.remotedomain.com via ssh. The user is expected to start StdioTunnel -r on the remote host; after this, StdioTunnel will forward two local ports to the remote host: local port 2001 on the local host will be forwarded to port 22 (the ssh port) on the remotehost, and StdioTunnel will use extra handshaking on that connection; also, the 5900 port on the local host (vnc default port) will be forwarded to the same port on the remote host.
StdioTunnel -r -D 2>stdiotunnel.log
Start the remote side of StdioTunnel with debugging turned on, sending the debugging output to stdiotunel.log.
StdioTunnel -l -t -R 2002:localhost:143:p -e "ssh remotehost.remotedomain.com StdioTunnel -r"
In this example StdioTunnel will forward a connection from any host to port 2002 on the remote host to port 143 on the local host. Note that the connection command itself starts the remote side of StdioTunnel.
On platforms that lack forkpty(3) (such as Solaris?) StdioTunnel will always behave as if the -T flag is provided. This can make setting up the connection difficult.
Some platforms, notable Mac OS/X, seem unable to bind solely to the loopback address. Any connection spec that is to listen on such a platform must include the promiscuous flag or it won't work.
StdioTunnel and the StdioTunnel manpage are Copyright 2004,2005 by Michael A. MacDonald, licensed under the terms of the GNU General Public License. All trademarks are the property of their respective owners.
| stdiotunnel home page | contact antlersoft |
free software news |