Common Notation
TCPrelay
Example: two proxies on TCP with similar function
UDPrelay
Example: two proxies on UDP with similar function
Example: a gateway between UDP and TCP
A pair of gateways like above can be used to convey UDP packets over TCP connections, but such relaying (tunneling) is realized more efficiently using SockMux with a single TCP connection.
DGAuth server
Example: DGAuth-DeleGate server and its client
Example: DGAuth-DeleGate server and its client on the same host
A DGAuth server receives a set of components to be used to calculate digest for each application protocol, then return the digest, as follows.
PAM server
Example: PAM-DeleGate server and its client
Example: PAM-DeleGate server and its client communicating over SSL
Note that most of PAM authentications need to be executed under the privilege of superuser on Unix (with OWNER="root" option). But you can avoid running your PAM-DeleGate server with superuser privilege by installing external program "dgpam" under DGROOT/subin/.
The default port number of the experimental PAM/HTTP server is 8686. Other ports can be specified as AUTHRIZER=-pam//host..port, for example as AUTHORIZER="-pam//hostX..8765/passwd".
PAM/HTTP protocol uses the format of HTTP compatible request/response messages as follows.
Request: GET /-/pam/service/auth HTTP/1.0 Authorization: Basic BASE64of(User:Pass) Response (one of followings): HTTP/1.0 200 OK, authorized HTTP/1.0 401 Not authorized HTTP/1.0 403 Forbidden to use the PAM serverThe base of request URL "/-/pam/" can be replaced with an arbitrary path with PAMCONF="baseurl:/basePath/". The whole request URL can be replaced by PAMCONF="url:/path". The content of response message is not cared in the current specification but it could convey some authentication related data or capability information in future.
Following the format, you can easily develop your own PAM server,
instead of PAM-DeleGate, using your own HTTP server with CGI or so.
FTPxHTTP server
YYsh server
YYMUX server
host:port specifies the port toward which a SockMux
persistent connection is established.
The connection is established from the DeleGate with "con"
option to the DeleGate with "acc" option.
Options:
Example: SOCKS proxies chained over SockMux
Example: SOCKS proxies chained over SockMux connected from the server side
Example: HTTP proxies chained over SockMux
SockMux server
The persistent connection is established with "-Phost:port" parameter
at receptor side, and "SERVER=sockmux://host:port" at connector side.
The port to accept outgoing connections to be forwarded to remote is specified
with PORT="listOfPorts parameter.
The server to be connected for incoming connections from remote is specified
with a postfix string ",-in" like SERVER="telnet://host:23,-in".
An incoming connection can be processed with DeleGate as a proxy of the
specified protocol.
If only protocol name is specified like SERVER="telnet,-in", or if "-in"
is postfixed like "-in(option list)", then a DeleGate is
invoked to process the connection.
The option list is passed to the invoked DeleGate as the list of
command line options.
For example, SERVER="telnet://host,-in(+=config.cnf)" will invoke a DeleGate
with command line options like ``delegated SERVER=telnet://host +=config.cnf''.
Example: bi-directional SockMux-DeleGate
Example: uni-directional SockMux-DeleGate
Example: uni-directional to proxy-Telent-DeleGate
When SockMux is used just to relay data between sockets, without
interpreting the application protocol relayed over SockMux,
such relaying can be represented with simpler expression using
DEST parameter instead of SERVER as follows:
Example: tcprelay over SockMux
Example: relaying UDP over SockMux/TCP
Another way to establish a persistent connection between
two SockMux-DeleGate is using a FIFO device like named pipe.
It is specified like SERVER=sockmux:commtype@fifoName
where commtype is one of "commin", "commout", and "comm",
which represents uni-directional input, uni-directional output and
bi-directional input/output respectively.
Example: use fifo device on a host
Example: use communication port between two hosts (not tested yet)
The persistent connection can be established by a given external
program invoked by DeleGate.
The process of the program is passed a socket to/from DeleGate at
file descriptor number 0 and 1;
Example: establish connection by external command
The destination SERVER for an incoming connection from remote can be
selected depending on which port it was accepted.
A SERVER parameter postfixed with
":-:-Pxxxx"
will be applied only to connections which is accepted on remote host
with PORT=xxxx.
Example: forwarding multiple port
NOTE: forwarding FTP data connection is not supported (yet).
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:
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.
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
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)
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).
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
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
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.
Socks server
Example: Socks-DeleGate
To accept an incoming TCP connection via a SOCKS-DeleGate server,
the network interface to be used for it is selected automatically
by DeleGate (based on the DST.ADDR or DSTIP which is sent from
a SOCKS client as the parameter of the BIND command).
With the SRCIF parameter, you can select a network
interface (and port number) manually, with the pseudo protocol name "tcpbind".
The complete syntax of the parameter is
SRCIF=
"[host]:[port]:tcpbind[:dstHostList[:srcHostList]]".
Typically, only the host filed is specified to select a network
interface, like SRCIF="150.29.202.120::tcpbind" for example.
NOTE: When you chain DeleGate with another SOCKS server, it may
cause problems in UDP relaying due to the private and tentative
extensions to the SOCKS protocol by DeleGate.
The following SRCIF parameters can be useful to escape such problems.
Example: Socks-DeleGate which do caching for HTTP and FTP
Example: Socks-DeleGate which do caching for HTTP with an upstream proxy
See
http://www.delegate.org/delegate/sockstap/>
for more details.
HTTP proxy/server
Then use this DeleGate from your client on the internal host,
specifying "firewall:8080" as the proxy for
HTTP, HTTPS (Security), FTP, Gopher, Wais, and so on.
Example: cascaded DeleGate as an HTTP proxy
Run a generalist DeleGate on the firewall which only accepts
request from internal host,
then run a specialist on internal which use the generalist
on firewall host.
A generalist can be shared as an upstream DeleGate from multiple
DeleGates of arbitrary protocol.
Example: DeleGate as an origin HTTP server
A file with a name with ".cgi" extension is treated as a CGI script.
Also you can use arbitrary name of CGI scripts under a specified
directory with a MOUNT like:
Example: DeleGate as a CGI program
HTTP Transfer Log Format
SOCKMUX parameter* == SOCKMUX=host:port:option[,option]*
option == acc | con | ssl
-- default: none
-- status: tentative
If specified together with SOCKS,
PROXY, MASTER (to chain two DeleGate),
then the communication between DeleGate is multiplexed on a single
persistent connection using SockMux.
This is useful to reduce the delay to establish many connections repeatedly
between DeleGate which are running distant from each other with long RTT.
acc -- accept a SockMux connection at "host:port".
con -- connect a SockMux connection to "host:port".
ssl -- use SSL instead of the "Credhy" encryption.
hostA% delegated SOCKMUX=hostA:8000:acc SERVER=socks -P2080
hostB% delegated SOCKMUX=hostA:8000:con SERVER=socks -P1080 SOCKS=hostA:8000
hostA% delegated SOCKMUX=hostB:8000:con SERVER=socks -P2080
hostB% delegated SOCKMUX=hostB:8000:acc SERVER=socks -P1080 SOCKS=hostA:8000
SOXCONF parameter* == SOXCONF=confSpec[,confSpec]*
-- default: none
SockMux is an experimental protocol designed for inter-DeleGate communication.
It is a simple protocol for "port forwarding" to accept, relay and destroy
connections, multiplexed over a single persistent connection.
A pair of SockMux-DeleGate establish and retain a connection between them,
then forward port from local to remote each other over the connection.
hostX% delegated SERVER=sockmux -PhostX:9000 PORT=9023 SERVER="telnet://hostX,-in"
hostY% delegated SERVER=sockmux://hostX:9000 PORT=9023 SERVER="telnet://hostY,-in"
// a pair of SockMux-DeleGate is connected at the port "hostX:9000", then
// the port "hostX:9023" is forwarded to "telnet://hostY"
// the port "hostY:9023" is forwarded to "telnet://hostX"
hostX% delegated SERVER=sockmux -PhostX:9000 SERVER="telnet://hostX,-in"
hostY% delegated SERVER=sockmux://hostX:9000 PORT=hostY:9023
// hostY:9023 is forwarded to "telnet://hostX".
hostX% delegated SERVER=sockmux -PhostX:9000 PORT=hostX:9023
hostY% delegated SERVER=sockmux://hostX:9000 SERVER="telnet,-in"
// hostX:9023 is forwarded to a Telnet proxy on hostY.
DEST=host:port[:srcHostList]
for
SERVER=tcprelay://host:port,-in[:-:srcHostList]
DEST=host:port/udp[:srcHostList]
for
SERVER=udprelay://host:port,-in[:-:srcHostList]
hostX% delegated SERVER=sockmux://hostY:9000 PORT=hostX:111
hostY% delegated SERVER=sockmux -PhostY:9000 DEST=hostT:111
// hostX:111/tcp is forwarded to the server at hostT:111/tcp via hostY.
% mkfifo /tmp/com0
% mkfifo /tmp/com1
serv1) SERVER=sockmux:commin@/tmp/com0 SERVER=sockmux:commout@/tmp/com1 ...
serv2) SERVER=sockmux:commin@/tmp/com1 SERVER=sockmux:commout@/tmp/com0 ...
% SERVER="sockmux:proc@connectCommand" ...
hostX% ... PORT=8023,8080
hostY% ... SERVER=telnet,-in:-:-P8023 SERVER=http,-in:-:-P8080
// hostX:8023 is forwarded to Telnet-proxy on hostY
// hostX:8080 is forwarded to HTTP-proxy on hostY
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.
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 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.
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
hostX% delegated -P9876 HTMUX=sv SERVER=http
hostY% delegated -P8080 HTMUX=cl:hostX:9876 SERVER=http
(Again, note that this feature is disabled by default and needs
CAPSKEY to enable it)
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
hostX% delegated -PhostX:9876 HTMUX=sv SERVER=http
hostI% delegated -Plocalhost:8084/local HTMUX=cl:hostX:9876 SERVER=http
CAPSKEY parameter* == CAPSKEY=opaque
-- default: none
Socks-DeleGate with SERVER=socks accepts both SocksV4 and SocksV5,
whereas SERVER=socks4 and SERVER=socks5 accepts only SocksV4 and SocksV5
respectively.
Currently, only USER/PASS authentication scheme of SocksV5 is supported.
# delegated -P1080 SERVER=socks
Example: forwarding to an upstream Socks server
SRCIF="0.0.0.0:0:socks-udp-tosv"
makes DeleGate as a SOCKS client behave compliantly to
the SOCKSv5 specification on UDP ASSOCIATE.
SRCIF="0.0.0.0:0:socks-udp-tocl"
suppresses the failure in DeleGate as a SOCKS server
trying to bind a UDP socket to a specific port number.
SOCKSTAP parameter* == SOCKSTAP=ProtoList[:[dstHostList][:[srcHostList][:params]]]
-- default: none
If specified with a SOCKS server, the data stream relayed over the SOCKS is
interpreted in each application protocol.
For example, with SOCKSTAP=http, the delegated act as a server
of SERVER=http when the relayed protocol is detected to be the HTTP protocol.
Example: DeleGate as an HTTP proxy
firewall% delegated -P8080 SERVER=http
firewall% delegated -P8888 SERVER=delegate RELIABLE=internal
internal% delegated -P8080 SERVER=http MASTER=firewall:8888
MOUNT="/xxx/* cgi:/path/of/cgi-bin/*"
You can use DeleGate as a CGI program from a HTTP server. For example,
specify in the "httpd.conf" file of your HTTP server(A) as follows.
Exec /other/* /path/of/cgi-delegate
Then write the content of the file /path/of/cgi-delegate as follows:
#!/bin/sh
This will add a pseudo sub tree "/other/" onto server(A)
including
/other/www2/ which is a content of a HTTP server "wwwserv2", and
/other/news/ which is a content of a NNTP server "newsserv".
The format of PROTOLOG for HTTP protocol can be modified with a
optional format specification postfixed after the LogFilename as
PROTOLOG="LogFilename:format".
In this case, default file name can be omitted.
For example, PROTOLOG=":%X" specifies making a NCSA like
extended common logfile format.
The default format is PROTOLOG=":%C %D".
%C -- common logfile format of CERN-HTTPD
%c -- same as %C except the date is recorded in millisecond precision
%D -- extension by DeleGate
(connTime+relayTime:status)
%X == '%C "%r" "%u"' common logfile format with Referer and User-Agent
%r -- Referer field in the request message
%u -- User-Agent field in the request message
%S -- status of CONNECTion to the server (c,m,p,d,s,v)
%s -- session Id by HTTPCONF=session
%As -- session Id in Digest Authorization
%{field} -- arbitrary field in the request message
The session identifier put by "%s" is generated by specifying HTTPCONF=session:cookie option while "%As" is generated by AUTHORIZER=-dgauth option. The format of session identifier is as this:
For example, "031114-173045.1234.5+6+7.9" means that it is the 9th request from the client in the session started at 17:30:45 on November 14 by the process of PID=1234. The start of the session is recorded in LOGFILE as this:
Note that the reqnum part may not be unique because of parallel or pipelined requests generated by a client as the owner of the session. Note that the reqnum part for "%As" may not be incremented on each request because the container of session identifier, the opaque" parameter in Digest Authentication in this case, may not be updated on each request.
HTTPCONF parameter == HTTPCONF=what:conf
Automatically detects virtual servers in MOUNT parameters and notate
each of them as a MOUNT rule to be applied only to a virtual server.
It can be done manually by specifying "nvserv" MountOption
for each MOUNT parameter.
"nvserv:alias" means detecting target servers of host names with
common IP-addresses and notate them as virtual servers.
"nvserv:gen" means notating MOUNT parameters with "genvhost"
MountOption as virtual servers.
"nvserv:auto" is equivalent to "nvserv:alias,gen".
The guessing can be overridden by explicitly specifying
the avserv MountOption for each MOUNT parameter.
"nvserv:none" disables any treatment of virtual servers which are
detected automatically or specified explicitly by the "nvserv" MountOption.
Example:
Example:
Example:
encrypt specified attributes in a Set-Cookie response to be stored in a client, then decrypt and forward the Cookie request only to the originator of the Cookie. An attribute in a Cookie is specified as "attribute@host" or "attribute@.domain". In the former case, a cookie generated by a host is encrypted and echoed to host only. In the latter case, a cookie generated by hosts in the domain can be echoed to hosts in the domain. The special string "%a" in cryptKey is substituted by the IP-address of the client. This makes the crypted Cookie be usable only by clients on the host of the IP-address.
Example:
Example:
Example:
HTTPCONF="add-qhead:X-Forward-For:%a"
Example:
Example:
Example:
Example:
FILETYPE parameter == FILETYPE=suffix:gopherType:altText:iconName:contentType -- default: FILETYPE=".txt:0:TXT:text:text/plain" FILETYPE=...
Example:
CGIENV parameter == CGIENV=name[,name]* -- default: CGIENV="*"
MountOptions for HTTP-DeleGate
CONTROLS:
Example: virtual hosting, acting as multiple HTTP servers
MOUNT="/* http://wwwA/* vhost=-dom1.com"
MOUNT="/* http://wwwB/* vhost=-dom2.org"
MOUNT="/* file:data/wwwC/* vhost=-dom3.net"
MOUNT="/* file:data/www/*"
Example:
MOUNT="http:* = method=POST,asproxy,useproxy"
MOUNT="http:* = withquery,asproxy,useproxy"
AUTH parameters for HTTP-DeleGate
Example:
| %u | -- user name got using Ident protocol |
| %h | -- host name of the client got from the socket |
| %i | -- host name of the network interface to the client |
| %I | -- like %i but use the value of "Host:" if given in HTTP |
| %a | -- host address of the client |
| %n | -- network address of the client |
| %H | -- hostname of the DeleGate |
| %M | -- the ADMIN of the DeleGate |
| %A | -- generated string by "CMAP=string:authgen:mapSpec" |
| %U | -- username part of client's [Proxy-]Authorization: username:password |
| %P | -- password part of client's [Proxy-]Authorization: username:password |
Example:
A generated password is formatted as "passWord/%i" and a DeleGate rejects incoming requests with an Authorization field of such pattern. Thus forged password cannot pass the DeleGate on the host "%i".
Example:
| %F | -- E-mail address in From field |
| %L | -- local part of From: local@domain field |
| %D | -- domain part of From: local@domain field |
| %U | -- username part of Authorization: username:password |
| %P | -- password part of Authorization: username:password |
| %Q | -- "for clientFQDN" part of Forwarded: field |
Example:
Configuration of DeleGate by Users
Example: MOUNTing news serverN at http://delegate/news/servN/
(This mechanism should be applied to other protocols like FTP...)
Server Side Include in SHTML files
SSI tags
META tags