stdiotunnel home page contact antlersoft
free software news


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.

Local Side

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:

-L connection-spec
These connections will forward the listen port on the local machine, listening for connection attempts to that port. When a connection is made, StdioTunnel will attempt to forward the connection, connecting from the remote machine to connect port on the host specified by connect host.
-R connection-spec
These connections will forward the listen port on the remote machine, listening at the remote machine for connection attempts to that port. When a connection is made, StdioTunnel will attempt to forward the connection to the local machine, connecting from the local machine to connect port on the host specified by connect host.

A connection-spec may also have flag characters, single characters appearing in the optional fourth part of the connection-spec. The supported flags are:

This flag--for [a]cknowledge--adds handshaking to all data transfers over the defined connection, greatly increasing latency but overcoming problems with some connections on some platforms.

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.

Other options

By default, StdioTunnel communicates with the connection command through a pseudo-tty. Some commands may not expect to be communicating through a tty device and may not set the terminal modes correctly; this flag instructs StdioTunnel to compensate for such commands.
As mentioned, StdioTunnel normally connects to the connection command through a pseudo-tty. This option forces StdioTunnel to use pipes instead.

Remote Side

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.

Common Flags

Use this flag to put either side of StdioTunnel in debug mode. In this mode, StdioTunnel will write a lot of debugging information to the standard error output; this will interfere with the connection unless the standard error is redirected.
Prints the version of StdioTunnel.


StdioTunnel -l -L 2001:localhost:22:a -L 5900:localhost:5900 -e "ssh -e none"

In this example StdioTunnel is initiating a connection to 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 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.

Environment Variables

StdioTunnel passes the connection command to the program specified by the SHELL environment variable.


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