[CTX] [ALL] SockMux over HTTP

---

HTMUX parameter     ==  HTMUX=sv[:[hostList][:portList]]
                     |  HTMUX=cl:host:port
                     |  HTMUX=px:host:port
                    --  restriction: requires CAPSKEY
                    --  default: none

HTMUX is used to accept requests at a port which is not directly accessible from a DeleGate to serve the requests. Typically it is a port on a remote host. HTTP DeleGate acts as a HTMUX server when given HTMUX=sv parameter. A DeleGate for any application protocol can act as a HTMUX client specifying its HTMUX server with HTMUX=cl:host:port parameter. A HTMUX server accepts TCP connections at a port (specified by a HTMUX client) on the host and relays the connections to HTMUX clients.

Not only incoming connections but also outgoing connections from a HTMUX client is established via the HTMUX server by default. This might not necessary for a DeleGate that relays incoming request to internal server. In such case, use the CONNECT parameter to specify such connections to be established directory, as CONNECT="direct:*:192.168.1.*" for example.

Example:

hostX% delegated -P192.168.1.1:9876 HTMUX=sv SERVER=http
hostI% delegated -Pxx.xx.xx.xx:8080 HTMUX=cl:192.168.1.1:9876 SERVER=http
hostJ% delegated -Pxx.xx.xx.xx:8021 HTMUX=cl:192.168.1.1:9876 SERVER=ftp


This example implies that hostX is a multi-homed host with a private addresses 192.168.1.1 and a global address xx.xx.xx.xx. The DeleGate on hostX acts as a HTMUX server. HTTP DeleGate on hostI and FTP DeleGate on hostJ act as HTMUX client which remotely accepts requests (arrived at xx.xx.xx.xx) via the HTMUX server on HostX.

A pair of HTMUX server and client uses a single persistent connection to relay multiple parallel connections on it multiplexing them by the SockMux protocol.
This feature must not be exploited maliciously, for example to invite incoming connections violating a restriction on a firewall. Therefore you need to install CAPSKEY to enable this feature. Other usages of HTMUX being disabled by default are non-direct connection between client and server (connection via NAT or proxy), too large clock skew between client and server (300 seconds by default), or inserting SSL encryption between client and server.

There are two ways to enable non-direct connection for HTMUX. One way is to install a CAPSKEY to enable indirect HTMUX connection. Another way is inserting a HTMUX proxy as the following example.

Example: cascading HTMUX with a HTMUX proxy

hostX% delegated -PhostX:9876 HTMUX=sv SERVER=http
hostI% delegated -PhostI:6789 HTMUX=px:hostX:9876 SERVER=http
hostJ% delegated -PhostX:8080 HTMUX=cl:hostI:6789 SERVER=http


The persistent connection between HTMUX client and server is capable to convey connections bi-directionally, thus can be used to make a pair of proxies over it. Each proxy accepts requests at the local port and forwards them to the remote peer as the following example.

Example: using HTMUX to make symmetric proxies (the simplest generic configuration)

hostX% delegated -P9876 HTMUX=sv SERVER=http
hostY% delegated -P8080 HTMUX=cl:hostX:9876 SERVER=http

In this example, -P8080 is equivalent to a wild-card address expression "-P*:8080" to accept from the port number 8080 on any network interfaces on the host. Therefore requests to the port 8080 on any interface on hostX is forwarded to the servers via the DeleGate on hostY as a HTMUX client (and a HTTP proxy). Symmetrically, requests to the port 8080 on any interface on hostY is forwarded to the servers via the DeleGate on hostX as a HTTP proxy (and a HTMUX server at hostX:9876).
(Again, note that this feature is disabled by default and needs CAPSKEY to enable it)

The port to be used on the server side and on the client side can be specified separately with the "/local" and "/remote" modifiers for -P or -Q option. "/local" marks a port to be used on the local host (on a HTMUX client), and "/remote" marks the port to be used on the remote host (on a HTMUX server). The specification "-P8080" in the above example is equivalent to "-P*:8080/remote,*:8080/local".

Example: using HTMUX bi-directionally

hostX% delegated -PhostX:9876 HTMUX=sv SERVER=http
hostI% delegated -Plocalhost:8081 HTMUX=cl:hostX:9876 SERVER=http
hostJ% delegated -P8082/remote,8083/local HTMUX=cl:hostX:9876 SERVER=http

In this example, between hostX and hostI, requests to localhost:8081 on each host are forwarded to the peer (equivalent to "-Plocalhost:8081/remote,localhost:8081/local") Between hostX and hostJ, hostX:8082 and hostJ:8083 are forwarded to the peer (equivalent to "-PhostX:8082/remote,hostJ:8083/local")

Example: using HTMUX only for outbound requests

hostX% delegated -PhostX:9876 HTMUX=sv SERVER=http
hostI% delegated -Plocalhost:8084/local HTMUX=cl:hostX:9876 SERVER=http

This is an example to use HTMUX only for outbound requests. It works even without the HTMUX parameter, but with HTMUX, a single persistent connection is used between the server and client. This usage of HTMUX is enabled by default when DeleGate is executed in foreground (with -fv option, running not as a service or a daemon), without restrictions described as above, and don't require CAPSKEY.

---