SERVER parameter*   ==  SERVER=protocol[://host[:portNum]][:-:MountOptions]
           portNum  ==  [+|-]number
                    --  default: SERVER=delegate

SERVER=protocol specifies the protocol to be used for communication with clients, which will be the default protocol with servers.

Example: a SERVER parameter for unbound Telnet-DeleGate

SERVER=telnet
If SERVER="delegate" is given, the DeleGate will become a generalist (or MASTER-DeleGate), which acts as an upstream DeleGate of other DeleGates. Note that a generalist can remit arbitrary protocols by default, so that it can be dangerous without enough consideration on access control (see REMITTABLE). A generalist automatically detects multiple protocol, including HTTP, proxy-Whois, as well as DeleGate original protocol.

If no destination server (host) is specified, it is to be be given by client somehow at run-time, on application level in protocol dependent way.

Several protocols including "http" and "socks" have inherent and automatic way to do proxying. Some protocols, like "ftp" and "pop", with a subprotocol to login to server are naturally extended so that information about destination server is encoded as user@host for user name as login information. Some protocols, including "whois" and "gopher", in which the first message is sent from client side, typically as a query message, the message is extended (without changing the specification) to include information about destination server. Some of other protocols like "telnet" have interaction with user on a client program thus can be extended with login dialogue for proxying.

The protocol with server is implicitly expected to be the same with the protocol with the client. Some protocols like HTTP have their inherent way to specify the protocol with the destination server. Otherwise it must be explicitly given with MOUNT parameter, like MOUNT="/news/* nntp://server/*" for example.

SERVER=protocol://host:portNum specifies the URL of destination server. The ":portNum" part is omittable as usual in URL if the number is that of standard port number of the protocol. A list of protocols and standard port numbers recognized by the DeleGate is available at: "http://delegate/-/builtin/mssgs/config.dhtml".

Port mapping: If a portNum is prefixed with "-" or "+", it means mapping the port number of the entrance port adding the specified offset, or using the port number as is by "-" with empty portNum.

Example: forwarding multiple ports to an another host

-P21,23,25,80 SERVER=tcprelay://host:-/

A special hostname "odst.-" can be used to refer the original destination host when the incoming data is forwarded by NAT.

Example: forwarding NAT to the original destination via a SOCKS proxy

-P9999 SERVER=tcprelay://odst.-:- SOCKS=sockshost

Note that a DeleGate bound to a specific server is not disabled to work as a proxy for arbitrary servers. Proxying ability must be restricted if necessary, using PERMIT, REACHABLE and RELAY parameters.

If a SERVER parameter is with ":-:MountOptions", the SERVER parameter will be dynamically selected if the condition specified in the MountOptions is evaluated to be true. As a special case, ":-:via=HostList" can be abbreviated as ":-:HostList".

Example: selecting an appropriate NNTP server for a client

SERVER="nntp://newsserver1:-:from={*.dom1}"
SERVER="nntp://newsserver2:-:from={*.dom2}"

Example: {NNTP,SMTP,POP}-DeleGate as a single server

-P119,110,25
SERVER="nntp://nntpserver:-:{*:119}"
SERVER="smtp://smtpserver:-:{*:25}"
SERVER="pop://popserver:-:{*:110}"

ADMIN parameter     ==  ADMIN=user@host.domain
                    --  default: built in at compile time

This parameter must be correctly given especially when the DeleGate runs on a host directly reachable to/from internet. This E-mail address will be used as follows:

-	Shown in (error) messages to clients, as the name of the administrator of this DeleGate (HTTP, etc.).
-	Shown in opening messages or in a help message to clients, as the name of the administrator (FTP, NNTP, Telnet).
-	Sent as a default user name (in PASS command) on anonymous access to FTP servers.
-	Sent as sender name (in FROM command) in access to remote SMTP server on verification by AUTH=anonftp:smtp-vrfy.
-	Report messages are sent to the address on occurrence of fatal signals

OWNER parameter*    ==  OWNER=user[/group][:srcHostList]
                    --  default: OWNER="nobody/nogroup"
                    --  restriction: super-user only on most of Unix
                    --  restriction: setting the user of a service on Windows

This parameter is effective only when the invoker is a super-user. If specified, the DeleGate will run with the right of specified user, calling setuid(2) and setgid(2) system calls. User and group can be specified either in symbolic name or in id-number prefixed with "#" like "#1234".
If srcHostList is specified, owner of this DeleGate will be set to the user when the client host is included in the list. The user name "*" will be substituted by the user name of the client when it can be got from an Identification server on the client host.

Example: run with the user ID corresponding to the user name of the client

OWNER="*:*@*".

On Windows, OWNER=user may be specified when it is invoked as a service, to set the user of the DeleGate service to be created. With empty user name as OWNER="", the user name is got from the USERNAME environment variable. The password can be specified with a PASS=pass parameter or an environment variable, or it will be asked on the console.

CRON parameter*     ==  CRON="crontab-spec"
       crontab-spec ==  minute hour day month dayOfWeek action
                    --  default: none

Cause an action at a time specified in the format of crontab-spec which is compatible with that of standard crontab(5) of cron(8) servers in Unix systems. If the action is prefixed with "/" then it is an external action which will be executed by the system(3) function. If the action is prefixed with "-" then it is a built-in internal action of DeleGate.

-suspend N	-- suspend for N seconds
-restart	-- restart the DeleGate
-exit	-- finish the DeleGate
-expire N	-- execute expiration for $CACHEDIR by "-atime +Nd"
-system command	-- execute command as a shell command
/dir/command args	-- equiv. to "-system /dir/command args"
- args	-- equiv. to "/dir/delegated args"
-Ffunc args	-- equiv. to "/dir/delegated -Ffunc args"

Example:

CRON="0 0 * * * -restart"
CRON="0 3 * * * -expire 3" (this is equivalent to followings)
CRON="0 3 * * * -Fexpire /path/of/cache -rm -atime +3 -sum"
CRON="0 3 * * * /path/of/delegated -Fexpire /path/of/cache -rm -atime +3 -sum"

INETD parameter*    ==  INETD="inetd-conf"
        inetd-conf  ==  port sockType proto waitStat uid execPath argList
              port  ==  [host:]portNum
          sockType  ==  stream | dgram
             proto  ==  tcp | udp
          waitStat  ==  nowait ("wait" is not yet supported)
                    --  default: none

Invoke a new DeleGate process with the specified configuration when a request is arrived at the specified port. The format of the inetd-conf specification is like that of standard inetd.conf(5) in Unix systems.
A default value of each field can be represented by "-". Default values of sockType, proto and waitStat are "stream", "tcp" and "nowait" respectively. The uid field will be used as OWNER parameter in the invoked process. Specifying "-" as uid value means invoking DeleGate without OWNER parameter. If execPath is "-", it means to start child DeleGate process with the given argList. The configuration of the parent DeleGate process is inherited to child DeleGates. For example, when a parent DeleGate is invoked like:
delegated ADMIN=foo EXPIRE=1 INETD=conf1 INETD=conf2
these ADMIN and EXPIRE parameters are inherited to DeleGates described in conf1 and conf2.

Example:

INETD="8080 stream tcp nowait nobody - SERVER=http"
INETD="8080 - - - nobody - SERVER=http" (equivalent to the above)
INETD="8119 - - - - - SERVER=nntp://nntpserver/"
INETD="8888 - - - - /bin/date date" (equivalent to the following)
INETD="8888 - - - - - SERVER=exec XCOM="/bin/date date"'
INETD="8888 dgram udp - - /bin/date date"
INETD="localhost:8888 - - - - - /bin/sh sh"
INETD=+=/path/of/inetd.conf (load configuration from a file)

HOSTLIST parameter* ==  HOSTLIST=listName:HostList

Define a named HostList with the name listName. A named HostList can be referred in other HostLists. If multiple HOSTLIST parameters with the same listName are defined, the lastly defined one is referred. If a HostList is prefixed with "+," like HOSTLIST="listName:+,newHostList" then the newHostList is appended to the current definition of the list.

Predefined named HostList:

HOSTLIST=.localnet:localhost,./.,-/.,.o/."

HOSTLIST=.socksdst:!.localnet

Example:

// redefine .localnet
HOSTLIST=".localnet:localhost,./32,192.168.*"
// exclude localhost form the predefined .localnet
HOSTLIST=".localnet:+,!localhost"

CLUSTER parameter*  ==  CLUSTER=[protoList]:ServerList
        ServerList  ==  [/R,]Server[,ServerList]
            Server  ==  Host[..Port]

The CLUSTER parameter defines an ordered set of alternative or complemental servers (origin or proxy). It is referred when DeleGate failed to connect or authenticate with an upstream proxy server or an origin server. It is applied to proxy server specified in MASTER, PROXY, SSLTUNNEL, SOCKS, or an origin server specified in SERVER or in the right-hand of MOUNT.

If a list is prefixed with "/R", the servers in the list are tried in random order (the first server to be tried is selected randomly and other servers are tried in the round-robin order). It could be useful for load balancing among equivalent (proxy) servers.

The retrial by this parameter is commonly applied to servers of any protocols in the phase of establishment of a TCP connection to a server. The retrial covers the authentication phase for several protocols. In HTTP origin/gateway servers, the retrial may be caused depending on the response from the server, including the response code 503 (Service Unavailable) and 404 (Not Found) for example.

Example:

CLUSTER=http:www1,www2,www3..8080 MOUNT="/* http://www1/*"
CLUSTER=ftp:ftp1,ftp2,ftp3 MOUNT="/* ftp://ftp1/*"
CLUSTER=http-proxy:/R,px1..8080,px2..9090,px3..8080 PROXY=px1:8080
CLUSTER=socks:/R,sock1,sock2,sock3 SOCKS=socks1

CMAP parameter*     ==  CMAP=resultStr:mapName:connMap
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none

A generic parameter to make some parameters be conditional on the current connection. When the protocol, the destination and the source of the current connection match the connMap, this map is enabled providing resultStr string to be used for mapName.
Not only host name/address but also port number of destination servers can be used for matching in dstHostList. A typical usage of this parameter is for applying filter conditionally.

TLSCONF parameter*  ==  TLSCONF=tlsConf[,tlsConf]*
           tlsConf  ==  what:value
                    --  default: TLSCONF=scache:do,xcache:do

-v[d|s]

specify the detailness of logging of TLS setup and relay. "-vd" make logging detailed whereas "-vs" suppresses any logging.

scache[:[do]|no|acc|con]

enable or disable the session caches. By default, both session caches for accept and connect are enabled. "no" disables both of these caches. "acc" enables only the cache for clients. "con" enables only the cache for servers.

xcache[:[do]|no|acc|con]

enable or disable the context cache for certificates of this DeleGate.

shutdown | shutdown:flush | shutdown:wait | shutdown:none

enable sending the shutdown alert (close notify) to the peer before disconnection. It is enabled by default for FTP (TLSCONF="shutdown" is preset for SERVER="ftp" or SERVER="ftps").

libs:libname[+libname]

specify the dynamic libraries for SSL in the order to be loaded instead of the default ones, as TLSCONF="libs:crypto+ssl" for example. A libname can be with a version number like "libssl.so.0.9.8" or in a full-path name like "/usr/local/lib/libcrypto.0.9.8.dylib".

STLS parameter*     ==  STLS=stlsSpecs[,sslwayCom][:connMap]
         stlsSpecs  ==  [-]stlsSpec[/im][/ssl][,stlsSpecs]
          stlsSpec  ==  fsv | fcl | mitm | imimSec
         sslwayCom  ==  {sslway [-Vrfy] [-CApath dir] ...}
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none
                    --  restriction: applicable to HTTP, FTP, SMTP, POP, IMAP, SOCKS
                    --  required: SSLway

This parameter controls the initiation of SSL (TLS) based on a negotiation between client and server in each application protocol. The common scheme of the negotiation is known as "STARTTLS". "fsv" specifies using SSL with server and "fcl" specifies using SSL with client. When SSL is not supported on a connection, the STARTTLS negotiation will fail and the connection will be closed by default. To continue a session even when SSL is not available, prefix "-" to "fsv" or "fcl".

If "fcl" is specified, a client may start SSL without STARTTLS negotiation. Such implicit SSL negotiation from the client-side is detected by peeping a SSL hand-shake packet on the connection from the client-side at the beginning of a session for a certain period specified with imimSec. The default value is "im0.25" (250m seconds). "-im" disables this implicit SSL negotiation. If a stlsSpec is followed with "/im" as STLS="fsv/im" for example, SSL with the peer (with the server in this case) is applied without the STARTTLS negotiation.

If "mitm" is specified, it behaves like "-fcl,-fsv" that is if SSL is enabled in the client side then SSL on the server side is enabled. It can be used with a HTTP proxy DeleGate as a "secure proxy" or "SSL-tunnel" to peep the bidirectional communication in CONNECT method, relaying it as a usual HTTP applying filters and cache. ("mitm" means "Man-In-The-Middle" mode) If it is set optional as "STLS=-mitm" then the MITM mode is activated only when the client specified the server name prefixing with "-mitm." as "https://-mitm.host.domain/" for "https://host.domain/".

If non default SSLway command path or options are necessary to be used, the SSLway command can be specified after stlsSpecs as STLS="fcl,sslway -Vrfy -cert mycert.pem" for example.

Example:

STLS="fcl" -- use SSL with client (exit the session if not available)
STLS="-fcl" -- use SSL with client if available
STLS="fsv,-fcl" -- use SSL with server, and with client if available
STLS="fsv/ssl" SERVER="ftp" -- use AUTH SSL instead of AUTH TLS
STLS="fsv,im0.5" SERVER="ftp" -- automatic detection of implicit/explicit SSL server

CERTDIR parameter   ==  CERTDIR=dir
                    --  default: ${ETCDIR}/certs
                    --  version: DeleGate/9.8.0 + OpenSSL0.9.8g or laters

CERTDIR specifies the directory as the repository of certificates to be used by SSLway. Certificate files in the directory are named as follows. All of these files are optional.

me.pem -- my certificate

The certificate of this DeleGate to be sent to clients (and to servers if requested). It may contain the private-key too. It can be a chained certificate followed with the certificates of intermediate CAs.

me-key.pem -- my private-key

This file is necessary if the private-key for me.pem is not contained in itself.

me-key.pas -- the pass-phrase for my private-key

This file is necessary if the private-key in me-key.pem is encrypted.

common.pas -- the pass-phrase common to private-keys

This file can be used as the default pass-phrase common to all encrypted private-keys.

dhparam.pem -- DH PARAMETERS

This file is necessary to enable ciphers using Diffie-Hellman algorithm.

sn.domain.pem -- the certificate for SNI

The certificate for the domain indicated by SNI (Server Name Indication). Like me.pem, it may be in the combination of sn.domain-key.pem and sn.domain-key.pas (or common.pas).

sa.address.pem -- my certificate to clients

The certificate to be sent to clients when accessed via the network interface with address (ex. "sa.127.0.0.1.pem").

to-sv.pem -- my certificate to servers

The certificate like me.pem which is sent to servers only.

to-cl.pem -- my certificate to clients

The certificate like me.pem which is sent to clients only.

ca-sv.pem -- servers' CAs' certificates

The certificates of CAs to be used to verify acceptable certificates shown by servers. It may contain CRL too.

ca-sv/ -- directory of certificates of servers' CAs

each certificate is named with 'openssl x509 -hash -noout < certificate.pem'

ca-cl.pem -- clients' CAs' certificates

The certificates of CAs to be used to verify acceptable certificates shown by clients. It may contain CRL too.

ca-cl/ -- directory of certificates of clients' CAs

each certificate is named with 'openssl x509 -hash -noout < certificate.pem'

DGCONF parameter    ==  DGCONF=dir/file
                    --  default: DGCONF='${EXECDIR}/${EXECNAME}.conf'

DGCONF specifies the file of configuration parameters to be loaded, if exists, on the invocation. The default value is relative to the name of the executable file of DeleGate. For example, if the path of the executable is "X:/path/of/dg9_4_1.exe" then DGCONF="X:/path/of/dg9_4_1.conf".

DYCONF parameter*   ==  DYCONF=[conditions]parameters
        parameters  ==  file:path | cgi:path | arg:{listOfParameters}
                    --  default: none

DYCONF specifies configuration parameters to be loaded dynamically on the beginning of relaying application protocol after the acception of a TCP connection from a client before starting a session over it. The loading of parameters can be conditional based on the specified conditions, and the parameter value can be generated and/or evaluated on each loading.

A condition for loading can be based on the identity (address or name) of the host of a client which is requesting over the new connection. Or it can be based on the content (sub-string or pattern) of the initial request data which is sent from a client over a connection. The request data is polled for a specified period (15sec. by default) and peeked by a specified size (4K bytes at max. by default).

Conditions:

qstr/string ... matching by request sub-string

qreq/pattern ... matching by request pattern

{from/hostList} ... matching by client hosts

excl[/number] ... exclusive with other DYCONFs

poll/seconds ... timeout of polling request [4k]

peek/bytes ... max. bytes of peeking request [15.0s]

skip ... purge peeked data before starting relay

debug ... enable logging for debugging of DYCONF

Example:

DYCONF="file:path.txt" # load parameters from path.txt
DYCONF="cgi:path.cgi" # load parameters generated by path.cgi
DYCONF="qstr/string,arg:{SERVER=tcprelay://sv1:1234;TIMEOUT=io:3}"
DYCONF="{qrex/[a-z][0-9]*},arg:{SERVER=tcprelay://sv1:1234}"

DYLIB parameter     ==  DYLIB=libfilePattern[,libfilePattern]*
                    --  default: DYLIB='dglib*.so,lib*.so,dglib*.dylib,lib*.dylib'

DYLIB specifies a list of file name patterns for dynamic linking library files to be retrieved. The character "*" in each pattern is replaced with the library name to be retrieved, for example with a pattern "lib*.so", "libssl.so" is retrieved for "ssl". A special pattern "+" means to include the default list. If a pattern is not in full-path format, the library file will be retrieved in some directories which depends on the system configuration or an environment variable like LD_LIBRARY_PATH or so. A pattern can be in full-path like "/usr/local/ssl/lib/lib*.so", or without "*" character like "/usr/local/ssl/lib/libssl.so".

Example:

DYLIB="" ... disable dynamic linking
DYLIB="lib*.so,lib*.so.1"
DYLIB="libz.so,libssl.so"
DYLIB="+,lib*.so.0.9.7"
DYLIB="/usr/lib/libz.so.1,/lib/libssl.so"

LDPATH parameter    ==  LDPATH=dirPath[;dirPath]*
                    --  default: LDPATH='${LIBDIR};${EXECDIR};${HOME}/lib;/usr/lib;/lib'

Specify where dynamic libraries (DYLIB) are searched.

LIBPATH parameter   ==  LIBPATH=dirPath[:dirPath]*
                    --  default: LIBPATH='.:${STARTDIR}:${LIBDIR}:${EXECDIR}:${ETCDIR}'

Library files, including parameter files, CFI scripts and filter programs, are searched in multiple directories in order specified in LIBPATH if it is specified as relative path. By default, LIBPATH is a ordered list of the following directories:

WORKDIR (.) -- the working directory
STARTDIR -- the directory where the DeleGate is invoked
LIBDIR -- ${DGROOT}/lib by default
EXECDIR -- the directory where the executable file of DeleGate is placed
ETCDIR -- ${DGROOT}/etc by default

DATAPATH parameter  ==  DATAPATH=dirPath[:dirPath]*
                    --  default: DATAPATH='.:${DGROOT}:${STARTDIR}

The list of directories each contains data files to be provided to client. This parameter is used by a DeleGate which generates response data from local file specified in relative path like MOUNT="/path/* file:dir/*".

DGPATH parameter    ==  DGPATH=dirPath[:dirPath]*
                    --  default: DGPATH='+:.:${HOME}/delegate:${EXECDIR}:${ETCDIR}'

The search path of parameter files. A special directory name "+" stands for the place where the "caller" resource (a parameter file referring the parameter file) is.

DGSIGN parameter    ==  DGSIGN=signatureSpec
                    --  default: DGSIGN="V.R.P/Y.M.D"

Specify the signature of the DeleGate to be shown to client or server. The full form signature "Version.Revision.Patch (Month Day, Year)" is represented as "V.R.P/Y.M.D". To hide the a specific part, replace the corresponding character with "x". For example, DGSIGN="V.x.x/Y.x.x" will make signature like "DeleGate/9.x.x (x x, 2005)".

DGOPTS parameter    ==  DGOPTS=opt[,opt]*
                    --  default: none

A list of command line options. This may be useful when those options like -P or -v, not in name=value format, are to be given in an environment variable.

SOCKOPT parameter*  ==  SOCKOPT=[no]name[:value]
                    --  default: reuse

Set socket options.

[reuse] | noreuse

enables instant reuse of a port number. (SO_REUSEADDR)

share | [noshare]

enables simultaneous use of a port. (SO_REUSEPORT)

[shut] | noshut

do shutdown(socket,SD_SEND) before closing a socket

shutdown:g[:connMap]

do graceful shutdown (for HTTP response) on Win32

buffsize:size[kiosc][:connMap]

set the size of socket buffers. The size value can be followed with following specifiers:

k -- size in kilo bytes
i -- input buffer (SO_RCVBUF)
o -- output buffer (SO_SNDBUF)
s -- socket to server
c -- socket from client


For example, SOCKOPT="buffsize:2kis" set the size of the socket buffer to receive data from a server to 2048 bytes. Multiple buffer size specifications can be concatenated with "+". For example, SOCKOPT="buffsize:2k" is equivalent to SOCKOPT="buffsize:2kis+2kos+2kic+2koc:*:*:*".

PORT parameter      ==  PORT=port[,port]*
              port  ==  [host:]portNum[/udp]
           portNum  ==  number[-number]
                    --  default: none

Make entrance ports as -P option does.

FORWARD parameter*  ==  FORWARD=gatewayURL[-_-connMap]
        gatewayURL  ==  gwproto://[user:pass@]gwhost[:gwport]
           connMap  ==  protoList:dstHostList:srcHostList
                    --  default: none

Forwards a request toward a proxy server specified in gatewayURL if the request matches the condition specified in connMap, that is, the request is in a protocol listed in protoList and for servers listed in dstHostList and from clients in srcHostList. If connMap is omitted, any request are forwarded to the gatewayURL unconditionally. If an authentication information is given as "user:pass@" prefixed to gwhost, it is used on the authentication phase after the connection with the gwhost.
FORWARD is a generalized notation of ROUTE and the following two notations are equivalent.
ROUTE=gwproto://gwhost:gwport/-_-dstHostList:srcHostList
FORWARD=gwproto://gwhost:gwport/-_-*:dstHostList:srcProtoList

For special gwproto, FORWARD works as a generalized notation of MASTER, PROXY, SOCKS and SSLTUNNEL as follows.

delegate -- forward to a DeleGate

MASTER=gwhost:gwport:dstHostList
FORWARD=delegate://gwhost:gwport/-_-*:dstHostList:*

http, ftp, telnet -- forward to an application level proxy (HTTP, FTP, or Telnet)

PROXY=gwhost:gwport:dstHostList
FORWARD=gwproto://gwhost:gwport/-_-*:dstHostList:*

socks -- forward to a SOCKS server

SOCKS=gwhost:gwport[/socksOpt]:dstHostList:srcHostList
FORWARD=socks://gwhost:gwport[/socksOpt]-_-*:dstHostList:srcHostList

ssltunnel -- forward to a SSL-tunnel (HTTP proxy with the CONNECT method)

SSLTUNNEL=gwhost:gwport
FORWARD="ssltunnel://gwhost:gwport/-_-*:*:*"

direct -- directly connect to the server

CONNECT="direct:protoList:dstHostList:srcHostList"
FORWARD="direct-_-protoList:dstHostList:srcHostList"

noroute -- don't try connection to the server

CONNECT="cache:protoList:dstHostList:srcHostList"
FORWARD="noroute-_-protoList:dstHostList:srcHostList"

If multiple FORWARD parameters are specified, they are tried in the order of the definition. If multiple routes to the destination server are available, specified with a mixture of FORWARD and other parameters (MASTER, PROXY, SOCKS or SSLTUNNEL), the route defined by FORWARD is tried in precedence defined by "proxy" or "master" in CONNECT.

Example: a gateway for HTTP clients to a HTTPS server reachable via SSLtunnel with authentication

MOUNT="/* https://sslhost/*"
STLS=fsv:https:sslhost
FORWARD=ssltunnel://user:pass@proxyhost:8080-_-https:sslhost

ROUTE parameter*    ==  ROUTE=proto://host:port/-_-dstHostList:srcHostList
                    --  default: none

Forwards requests from hosts in srcHostList to the resources listed in dstHostList toward the server at host:port in proto protocol. ROUTE is a generalized notation for MASTER and PROXY. MASTER="host:port:dstHostList" is the abbreviation of ROUTE="delegate://host:port/-_-dstHostList:*". PROXY="host:port:dstHostList" with SERVER=proto is equals to ROUTE="proto://host:port/-_-dstHostList:*".

A host specification in the dstHostList may be prefixed with "proto://" to restrict the protocol to be forwarded. For example, ROUTE="http://host:port/-_-{ftp://*}:*" means that only access to FTP servers are forwarded to the HTTP-proxy at "http://host:port/".

A host specification in the dstHostList can be restricted further with port number. For example, ROUTE="http://host:port/-_-{*:21}:*" means that only accesses to the port number 21 (FTP service) is forwarded to the proxy.

MASTER parameter*   ==  MASTER=host:port[/masterControl][:dstHostList]
                    --  default: none

This parameter specifies an upstream generalist DeleGate (MASTER-DeleGate) to which this DeleGate will forward requests. Forwarding to a MASTER-DeleGate can be filtered by postfixing ":dstHostList"; only request toward destination servers listed in dstHostList are forwarded to the MASTER-DeleGate. When multiple MASTERs are given, they are tried in order until connection to a MASTER succeed.

Optional "/masterControl" can be:

cache -- use the MASTER only if cache hits in the MASTER
teleport -- make a persistent Teleport connection to the MASTER

MASTERP parameter   ==  MASTERP=[host:port]
                    --  default: none

Invoke a MASTER-DeleGate private to this DeleGate. HTTP-DeleGate working as a gateway to another protocol needs MASTER-DeleGate to do connection cache for FTP and NNTP. MASTERP may be specified with MASTER to force data caching at the local host when the MASTER is running at a remote host.

RPORT parameter     ==  RPORT={tcp|udp}[:host]
                    --  default: none

This parameter should be used together with MASTER parameter. If specified, a connection (for response data transfer) from the MASTER-DeleGate to this DeleGate is established separately from the connection (for request data transfer) from the DeleGate to its MASTER-DeleGate. A specified type of response connection will be made from the MASTER toward the delegate at the specified host.

PROXY parameter*    ==  PROXY=host:port[:dstHostList]
                    --  default: none
                    --  restriction: applicable to HTTP, FTP, Telnet

Specify an upstream proxy (specialist DeleGate or standard proxies) to which the DeleGate should forward requests. If dstHostList is specified, forwarding to the upstream proxy is done only when the destination host is in the list. Only HTTP, FTP, and Telnet specialist DeleGate can specify this parameter.

Example:

SERVER=http PROXY=proxyhost:8080:!*.localdomain
SERVER=ftp PROXY=proxyhost:proxyport

SOCKS parameter*    ==  SOCKS=host[:[port][/socksOpt][:dstHostList[:srcHostList]]]
          socksOpt  ==  [ -4 | -r ]*
                    --  default: none

Specify to use Socks server on host. The server is expected to recognize Socks version 5 protocol. If the server supports only version 4, specify "-4" option like "SOCKS=host:port/-4".
The "-r" option controls which of DeleGate or Socks server does the name resolution (from the host name of a target host to its IP address). With a SocksV4 server, name resolution is done by DeleGate by default. "-r" option make the resolution be delegated to the server (This is applicable if the server supports extended Socks4A protocol). With a SocksV5 server, name resolution is delegated to the server by default, and "-r" option make the resolution be done locally by DeleGate.
By default, the connection establishment via Socks will be tried after all of other trials failed, but you can control the order by the CONNECT parameter.
If the dstHostList part is omitted, the default value for it is "!.localnet". This default value can be changed by redefining the named HostList ".socksdst" which is predefined as HOSTLIST=".socksdst:!.localnet"

Example:

CONNECT=s,d SOCKS="sockshost:1080:!.localnet,!*.my.domain"

SSLTUNNEL parameter ==  SSLTUNNEL=host:port
                    --  default: none

Use a HTTP proxy with the standard SSL tunneling feature (on HTTP with CONNECT method) running at host:port as a circuit level proxy for target servers of arbitrary protocols.

VSAP parameter      ==  VSAP=host:port
                    --  default: none

Specify a VSAP server to be used for accepting from clients or for connecting to clients. VSAP is a remote socket mapping server which enables servers to accept a TCP connection via a remote host as well as to connect via a remote host.

Example:

// VSAP server
firewall% delegated -P8000 SERVER=vsap PORT=8080-8090
// accept via VSAP to provide internal servers for external clients
internal% delegated -P8080@firewall:8000 ...
// connect via VSAP, working as a proxy server for internal clients
internal% delegated -P8080 CONNECT="{vsap/firewall:8000}" ...
// accept and connect via VSAP server
internal% delegated -P8080 VSAP=firewall:8000 ...

YYMUX parameter*    ==  YYMUX=host[:port][:connMap]
           connMap  ==  ProtoList[:dstHostList[:srcHostList]]
                    --  default: none

This parameter specifies a YYMUX server to be used as an upstream proxy server of this DeleGate. The connection established to the YYMUX server, to be used to tunnel and multiplex TCP/IP connections over it, is retained as if it is persistent. If the tunnel is broken before the disconnection of the tunneled TCP/IP connections, for example when the host of this DeleGate changed its IP-address, the YYMUX tunnel is reconnected and restored based on the resumption protocol of the YYMUX protocol.

YYCONF parameter*   ==  YYCONF=name[:value]
                    --  default: none

Example:
YYMUX="HOME:/user/xxxx"
YYMUX="SHELL:/bin/csh -l"

CONNECT parameter*  ==  CONNECT=connSeq[:connMap]
           connSeq  ==  connType[,connType]*
          connType  ==  cache|icp|proxy|master|https|vsap|direct|socks|udp
           connMap  ==  ProtoList[:dstHostList[:srcHostList]]
                    --  default: CONNECT="c,i,m,h,y,v,s,d:*:*:*"

This parameter controls the order of trials for connection to the target server using several connection method as followings:

connType:

cache	-- CACHE search (without connection)
icp	-- via a PROXY hinted by ICP server
proxy	-- via a PROXY server
master	-- via a PROXY or a MASTER-DeleGate server
https	-- via a SSLTUNNEL (SSL tunnel on HTTP)
yymux	-- via a YYMUX server
vsap	-- via a VSAP server
direct	-- direct connection to the target server
socks	-- via SOCKS servers
udp	-- by UDP
None	-- don't connect

Each connection type can be abbreviated by the first character as {c,i,m,d,v,s,u} respectively.
If ProtoList and dstHostList are given, this control is applied only to the protocols and hosts included in the lists. For example, to use cached data in a host which is not connected to external networks, specify as CONNECT="cache:*:!./@".

Note: In current implementation, "cache" will be tried first anyway if it is included in the connSeq.

A combination of -Pport with CONNECT=udp relays from TCP client to UDP server, and -Pport/udp with non-udp CONNECT relays from UDP client to TCP server.

SRCIF parameter*    ==  SRCIF=host[:[port][:connMap]]
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: SRCIF="*:*:*:*:*"

This parameter is useful for DeleGate running on a multi-homed host or on a host behind a firewall with packet filtering.

This parameter specifies the source address (of a network interface) of each connection to a server. This can be useful when the host of DeleGate has multiple network interfaces. Also it can be used to specify the port to be used for accepting a client connection by a SOCKS-DeleGate or a FTP-DeleGate.

In most cases, a special pattern "*" as host or port specifies the wild-card IP address or port number. In some cases, the special pattern "*" is used for the desired address and number which is specified by a protocol, like a port for FTP data connection (by PORT or PASV) or a port for SOCKS (BIND and UDP-ASSOCIATE). To explicitly specify the wild-card as an IP address and port number, use "0.0.0.0" as host and "0" as port respectively.

Example:

SRCIF="*:0:ftp-data" // use a random port number for FTP data connection
SRCIF="*:8020-8120:ftp-data" // use a port number in the specified range
SRCIF="150.29.202.120:*:tcpbind" // use the specified address to accept via SOCKS
SRCIF="150.29.202.120:*:udpbind" // use the specified address to relay UDP on SOCKS


The port for "ftp-data" connection which is assigned on demand and notified to the peer, that is from client to server by PORT or from server to client by PASV, can be controlled separately by "ftp-data-port" or "ftp-data-pasv" respectively. The source port for data connection, which is established from server to client for PORT or from client to server for PASV, can be controlled by "ftp-data-src".

TUNNEL parameter    ==  TUNNEL=tunnelType:script
        tunnelType  ==  tty7
                    --  default: none

If specified, communication with an upstream DeleGate will be tunneled via the standard input/output of the command. The tunnel can be made of any kind of channel, a raw serial line for example, as long as it provides bi-directional transmission on it. Possibly it may be the channel to the DeleGate which will be invoked from inetd at remote host.

Currently, the tunnelType must be "tty7" which means transmission between DeleGates is done in 7bits stream. When the type is "tty7", how the TUNNEL is established is described in the specified SHIO-script file. See "src/sample.shio" in the distribution package. The name of a script file must be specified either in absolute path, or in relative file name which will be retrieved in LIBPATH. The upstream DeleGate for TUNNEL must be invoked with SERVER="tunnel1".

Example: make a tunnel without login dialogue

TUNNEL=tty7:tunnel.shio
[content of tunnel.shio]
o rsh host delegated SERVER=tunnel1\n
i READY\r\n
=

Example: make a tunnel with login dialogue
TUNNEL=tty7:tunnel.shio
[content of tunnel.shio]
o telnet hostname\n
i login:
o username\n
i Password:
o password\n
i %
o delegated SERVER=tunnel1 \n
i READY\r
i \n
=

As shown in above examples, the first line in a SHIO-script file is expected to be a shell command like "o command\n" to establish a connection to a remote server. Another way to establish a connection is putting "c host:port" on the first line. No shell nor shell command is invoked in this case.

PERMIT parameter*   ==  PERMIT=connMap
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none

A PERMIT parameter specifies what kind of accesses should be permitted by this DeleGate. An access will be permitted if the access is from a client host included in srcHostList, and to a server host included in dstHostList, and with a protocol included in ProtoList.

If multiple PERMIT parameters are given, an access will be permitted if at least one of those PERMITs indicates permission. If no PERMIT parameter is given, access permission is controlled by REMITTABLE, REACHABLE and RELIABLE parameters which can be defined explicitly or implicitly depending on SERVER parameter.

Example: unlimited permission to hosts on local net while only http://www to others

PERMIT="*:*:.localnet"
PERMIT="http:www:*"


The special pattern "*" in ProtoList (dstHostList) means all of permitted protocols (servers), which may be explicitly defined with REMITTABLE (REACHABLE) parameters. These parameters limits the widest possible permission. A protocol (server) is not permitted if it is not permitted in REMITTABLE (REACHABLE) parameters defined implicitly or explicitly. Similarly, if more than one RELIABLE parameters are given explicitly, they limit the widest acceptable clients in srcHostList of PERMIT.

The host specifications in the dstHostList can be further restricted with port number like "host:portNumList". For example, PERMIT="telnet:{*:23}:*" means permitting telnet to any host but only on the standard port number (23).

A protocol name in the ProtoList can be modified with port number and method like "protocolName/portNumList/methodList" to restrict accessible ports and methods in the protocol. For example, a series of PERMIT parameters, PERMIT="ftp//readonly:Servers:Clients" PERMIT="ftp:*:*" means inhibiting uploading to Servers from Clients while allowing uploading among other combinations of servers and clients.

When multiple DeleGate servers are chained using MASTER or PROXY parameter, the original client identification information got at the first DeleGate server (at the entrance of the chain) can be forwarded to the upstream DeleGate server using RIDENT parameter and will be examined using PERMIT parameter.

REJECT parameter*   ==  REJECT=connMap
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none

REJECT parameter specifies what kind of access is to be rejected in the same syntax with PERMIT. It can be more convenient than PERMIT when cases to be rejected are exceptional and are easier to describe than cases to be permitted.

Example: forbid mail-clients to remove message on mail-servers

REJECT="pop//DELE:mail-server:mail-client"
REJECT="imap//EXPUNGE:mail-server:mail-client"

REMITTABLE parameter == REMITTABLE=ProtoList
                    --  default: REMITTABLE="*" for generalist
                    --  default: REMITTABLE="." for specialist

Only protocols (to the server) listed in ProtoList will be permitted by this DeleGate.
For generalist (a DeleGate with SERVER="delegate" parameter) any protocols are permitted by default. For specialist, only the protocol specified in the SERVER parameter (which can be represented by ".") is permitted by default.

If a protocol name is followed by "/portNumList", only ports listed in the PortList is permitted. A PortList can be followed by "/methodList" which restricts available methods in the protocol. A pseudo method "readonly" is used to prohibit methods for modification. For example, REMITTABLE="ftp//readonly" make a FTP-DeleGate be "read only" which inhibits uploading to FTP servers.

Protocol Specific Default:

generalist-DeleGate

REMITTABLE="*" -- any protocol is remittable

HTTP-DeleGate

REMITTABLE="http,https/{80,443},gopher,ftp,wais,cgi,ssi" -- usual protocols expected to be relayed by HTTP-proxies

Telnet-DeleGate

REMITTABLE="telnet/23" -- restricted to be accessible only toward standard Telnet port (23). This restriction can be disarmed by specifying like REMITTABLE="telnet".

Exception:

When the current destination server is determined by a MOUNT parameter like MOUNT="Path1 Proto://Server/Path2", the protocol Proto is automatically allowed as a destination protocol with Server, regardless of REMITTABLE restriction.

If the first member of a list is "+", it means the default list of permitted protocols. For example, REMITTABLE="+,-https/80,-wais,file" with SERVER=http means REMITTABLE="http,https/443,gopher,ftp,file".
Note that "https" implies that non-HTTPS protocol on the SSLtunnel may be detected and rejected. If arbitrary protocol is to be relayed on the SSLtunnel, specify "ssltunnel" instead of "https" like REMITTABLE="+,ssltunnel".

REACHABLE parameter* ==  REACHABLE=dstHostList
                    --  default: REACHABLE="*" (any host is reachable)

Only requests directed to the servers on the hosts (or networks) listed in dstHostList will be accepted by the DeleGate. When you use multiple REACHABLE parameters, you must be certain of the meaning.

RELIABLE parameter* ==  RELIABLE=srcHostList
                    --  default: RELIABLE=".localnet"

Only requests sent from clients on hosts (or networks) listed in srcHostList will be accepted by the DeleGate. By default, only accesses from client hosts on networks local to the host of the DeleGate (.localnet) are permitted.

Note that multiple RELIABLE parameters like RELIABLE=Hosts1 RELIABLE=Hosts2 will be interpreted being simply concatenated into a single RELIABLE="Hosts1,Hosts2", which will NOT mean "Hosts1 or Hosts2" if Hosts1 or Hosts2 includes some negation or composite operators. You are recommended to use multiple PERMIT parameters instead if you are not sure what does these mean.

RELAY parameter*    ==  RELAY=relayTypeList[:connMap]
     relayTypeList  ==  relayType[,relayType]*
         relayType  ==  proxy | delegate | vhost | no | nojava | noapplet
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: RELAY="delegate,nojava:*:*:.localnet"
                                 RELAY="vhost,nojava:http:{*:80}:.localnet"
                                 RELAY="proxy:*:*:*"

This parameter controls in which way the DeleGate works as a HTTP server. DeleGate as a HTTP proxy server works in two ways (proxying modes): as a standard (CERN compatible) HTTP proxy which accepts full URL in a request ("proxy" relayType), and as a DeleGate original proxy which accepts /-_-URL in a request and rewrites URLs in the response ("delegate" relayType). In a full specification format with ":connMap", available proxying modes can be classified by combination of server protocol, server host and client host.

RELAY="no" means working as an origin HTTP server without relaying (Origin HTTP server is a usual server which accepts requests in usual format, not in format for proxies, that is URL in request is neither in full format nor in "/-_-" format, but in absolute format).

So called "transparent-proxy" ability is enabled by "RELAY=vhost". RELAY="vhost" can be used for origin HTTP server with relaying to arbitrary virtual hosts. This option enables a HTTP request to be forwarded to arbitrary destination server, indicated in "Host:" field in request header, without explicit MOUNT. This automatic relaying is done only when the request URL is not MOUNTed, thus is not so likely because most DeleGate working as origin server have MOUNT parameter for the root URL ("/*").

With "nojava" combined with other relayType, <APPLET>, <EMBED> and <OBJECT> tags relayed in the relayType will be disabled (being replaced with <killed-TagName>). With "noapplet", only <APPLET> tags are disabled. When the relayType "delegate" is enabled by a RELAY parameter, using "nojava" like the default shown above is strongly recommended.

Example:

RELAY=no ... do not work as a proxy (origin server only)
RELAY=proxy ... CERN compatible mode only
RELAY=delegate ... DeleGate mode only (/-_-URL)
RELAY=proxy,delegate ... both CERN and DeleGate mode
RELAY=proxy,noapplet ... inhibit <APPLET> tag to be relayed by proxy

Default:

Both "proxy" and "delegate" modes are allowed to users on ".localnet", while only "proxy" mode is allowed to other users.

SCREEN parameter ==  SCREEN={reject|accept}
                    --  default: none

This parameter enables dynamically updating the black/white list for screening clients without restarting DeleGate. SCREEN overrides other access control specified by RELIABLE or PERMIT. In combination with "-Eri" option, the screening is done without starting the interpritation of the application layer protocol. "reject" indicates forbidding only client hosts listed in the list, while "accept" indicates allowing only client hosts listed in the list. The list is given as a text file including an IP-address or a MAC-address per line. With SCREEN="reject", the text file DGROOT/etc/hosts.d/reject.txt is seen. With SCREEN="accept", the text file DGROOT/etc/hosts.d/accept.txt is seen.
Note: the arp command must be available by your DeleGate to use MAC-address based screening.

AUTH parameter*     ==  AUTH=what:authProto:who
                    --  default: none

Authorize who to do what. Authentication of user will be done using protocol specified in authProto. Identification about "who the client's user is" is done based on Identification protocol to the client host if it supports the protocol. Otherwise FTP-server may be used as an authentication server.

In HTTP-DeleGate, user declares "who am i" giving an Authorization header (in request message), which consists of Username:Password, where Username can be in a form of User@Host.
Given a set of User, Host and Password, DeleGate tries to login to the (FTP) server on Host with User and Password. If succeed, then the client is authenticated to be User@Host.

Currently following categories of authentication/authorization are supported:

-- in any protocol DeleGate --

AUTH="admin[:authServ[:[listOfUsers][:listOfHosts]]]"

Enables the remote configuration and administration of DeleGate via HTTP (or HTTPS) at "http://delegateHost:Port/-/admin/". It allows a user to do remote administration if the user is authenticated with authServ, and if the user is in listOfUsers. For example, AUTH=admin:-pam:user authorizes the user if authenticated with PAM. AUTH=admin is the abbreviation of AUTH="admin:-pam:%O" where "%O" represents the owner of this DeleGate process. Empty authServ as AUTH=admin::user:pass means authorizing the username user with password pass. If ":listOfHosts" is specified, users to be authorized must access from a client hosts in the list.
A DeleGate of arbitrary protocol (regardless of SERVER=protocol) can have a port for remote administration by specifying a port devoted to administration with "/admin" modifier like "-PuserPort,adminPort/admin" option.
Example:

SERVER=pop -P110,9110/admin AUTH=admin::admin:password
The URL for remote administration of this DeleGate (as a POP proxy) is "https://delegateHost:9110/-/admin/"

-- in FTP server and FTP/HTTP gateway --

AUTH="anonftp:*:passWord"

If specified, A DeleGate forwards E-mail address of a client's user (which is declared by the user) to the target FTP server as an anonymous password. Without this AUTH, HTTP-DeleGate will send ADMIN's E-mail address by default.
The E-mail address must be in the form of user@host, otherwise (if the host part is not given) the FTP login is rejected by DeleGate.
HTTP-DeleGate asks anonymous users to declare his/her E-mail address as Username part in Authorization. If passWord field is specified as "*" (i.e. AUTH="anonftp:*:*"), then any Password in the Authorization will be acceptable.
In FTP-DeleGate, the E-mail address must be given as a password (in PASS command) for the anonymous user, and the password is used for matching with passWord too.
The second field must be "*" in current implementation.

AUTH="anonftp:smtp-vrfy:*"

If specified, DeleGate verifies (using the SMTP protocol) the validity of E-mail address given by anonymous users. In HTTP-DeleGate, the E-mail address must be given as Username part in Authorization. In FTP-Delegate, it must be given as a password for the anonymous user. With this AUTH, invalid E-mail addresses can be rejected. When the address is valid but is in a format like "user@host", it will be expanded automatically to a FQDN format like "user@host.domain".
If the third field is "-" (i.e. AUTH="anonftp:smtp-vrfy:-@*") only the connectivity to mail server at "host.domain" is checked.

-- in proxy and origin HTTP server --

AUTH=proxy:{ident|auth|pauth}

Specify identification/authorization protocols for the DeleGate as a HTTP proxy server. This parameter is checked only when access control for user is specified in PERMIT or RELIABLE.

ident	-- Identification protocol [default]
pauth	-- Use Proxy-Authorization field "user@host:password"
auth	-- Use Authorization field "user@host:password"

Example:

AUTH=proxy:auth PERMIT="*:*:{*,!?}@*"
// Any user at any host is allowed as long as he/she is identified.

Note:

When the client does not support Proxy-Authentication, you are obliged to use "proxy:auth" for Authentication. In such case, note that the client cannot access resources which requires Authentication.

In the case where the FTP-server based authentication is used, a recommended user name of the authorization information is e-mail address like "user@host.domain" so that it can be commonly used for both AUTH="anonftp" and AUTH="proxy".

AUTHORIZER parameter* ==  AUTHORIZER=authServList[@realmValue][:connMap]
       authServList  ==  [authForw,]authServ[,authServ]* | & | *
           authForw  ==  -map{inPat}{localPat}{fwdPat} | -strip | -fwd
           authServ  ==  authHost[/portNum][(reprUser)]
           authHost  ==  hostName | hostAddr
         realmValue  ==  word | {words separated with space}
            connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none
                    --  restriction: applicable to Telnet, FTP, NNTP, SMTP, IMAP,
                                     Socks, SockMux, and HTTP

Specify the server for authentication and authorization ("auth-server"). If specified, an access by a client is not permitted without authenticated successfully by the auth-server, sending an appropriate pair of user-name and pass-word over the application protocol. Two special authServ "-none" and "-never" are exceptions to make authentication unnecessary. If authServ is followed by "(reprUser)", the users successfully authenticated in the authServ are represented by reprUser as a representative user.

Note that even a client authorized by an auth-server is not permitted if the client's host does not pass other access controls (RELIABLE and PERMIT). To permit any authorized client regardless of its host, specify as RELIABLE="-a/*". Also RELIABLE="*" works for this purpose but is not safe on modifications of configuration and DeleGate.

Adding connMap, an auth-server can be selected conditionally on a combination of destination protocol, server host and client host. The authServList is a host name of authentication server, or a list of host names of authentication servers. If authServList is followed with "@realmValue", the value is used to define the realm of protection space in HTTP-DeleGate. It can be overridden by MountOption "realm=realmValue" for each MOUNT point.

Currently, the default protocol of remote authentication/authorization server is that of FTP protocol with USER and PASS commands. Thus any real FTP server can be used as an authentication/authorization server of DeleGate. Another way of maintaining DeleGate's own lists for authentication/authorization is using -Fauth function.

There are built-in auth-servers to be used as authServ as follows:

-none -- allow without caring if authentication is given or not

-never -- disallow without careing if authentication is given or not

-any -- any combination of username + password is acceptable

-anonftp -- username is "ftp" or "anonymous" and password includes "@"

-dgauth[.realm] -- password is sent safely as a digest (HTTP and APOP)

-pam/service -- username + password is checked by PAM

-list{user:pass,...} -- the pair of username and password is in the list

-userpass/user/pass -- equivalent to -list{user:pass}

-hostlist/ListName -- client's host is in the HOSTLIST=ListName:HostList

-fail.badpass -- disallow if the username exists but password is wrong

-fail.nopass -- disallow if password is not given or empty

-cmd{cmd arg ...}{ENV=val ...} -- external command for authentication

-ntht -- NTLM over HTTP (Win32 only)

-login -- logon to the local host (Win32 only)

-man -- manual authentication on demand

DGAuth: -dgauth[.realm][{user:pass,...}]


Authentication scheme based on digested password, specific to each application protocol, is enabled with "AUTHORIZER=-dgauth". This kind of authentication scheme, at least APOP proxy or HTTP Digest/Basic gateway does, requires the original cleartext of password. A simple way to do so is giving directly a list of pairs of username and password as -dgauth{user1:pass1,user2:pass2,...}. Another way is storing passwords by DeleGate with "-Fauth -a username:password -dgauth". Since passwords for -dgauth is stored in encrypted form, a keyword is required for the encryption. Specify the keyword as CRYPT=pass:keyword or answer it interactively afterwards. Otherwise, DGAuth can be delegated to a remote DGAuth server. DGAuth generates a session identifier which is retained identically during the session started by an authentication, then passed to CFI/CGI programs in environment variable "X_DIGEST_SESSION" and can be logged into PROTOLOG.

Example:

// a HTTP proxy or server with the Digest authentication with clients.
SERVER=http AUTHORIZER=-dgauth
// a POP proxy which uses APOP authentication with clients.
SERVER=pop MOUNT="* pop://server/*" AUTHORIZER=-dgauth


PAM: -pam[/service]


On platforms where PAM (Pluggable Authentication Modules) is available, it can be used for authentication with the syntax AUTHORIZER="-pam/service", for example as AUTHORIZER="-pam/passwd", AUTHORIZER="-pam/ftp" and so on.
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 DeleGate with superuser privilege by installing external program "dgpam" under DGROOT/subin/. Also PAM authentication can be delegated to a remote PAM server.

LIST: -list{user[:pass],...}


An element of the list can be user only without ":pass" which means matching user name only and don't care the password. In the "-list{user:pass,...}", substitution by "[date+format]" can be used in user and pass. For example, AUTHORIZER="-list{guest:[date+%y%m]}" means accepting usrename "guest" with password "0405" in May 2004.

Example:

AUTHORIZER="-list{u1:p1,u2:p2}(local),-pam,-none(anonymous)"
// a user may be authenticated as "local" or as some user name in PAM,
// or "anonymous" otherwise


CMD: -cmd{cmd arg ...}[{ENV=val ...}[{input-pattern}]]

Do the authentication with an external command cmd. Values to be used the authentication to be passed to the command is specified with the format as "%format" like %U for username and %P for password. A parameter can be passed in command-line argument, in environment variable or in the standard input of the command. If the environment and input-pattern is omitted as AUTHORIZER="-cmd{cmd}, the pair of user name and password is passed by default as if implicitly specified as AUTHORIZER="-cmd{cmd}{DG_USER=%U DG_PASS=%P}{USER %U\nPASS %P\n}".

The result of the authentication by the command is shown in its output string or by its exit code. The command may puts a string to its standard output to show the result in the form of a status response of the FTP protocol, that is, "230" for success and "530" for failure. Otherwise the exit code of the process is used, the value zero for success and non-zero values for failure.

Example: passing username in argument while password in environment variable

AUTHORIZER="-cmd{myauth %U}{MYPASS=%P}"

[the content of the myauth command]
#!/bin/sh
if [ "$1" = "user1" -a "$MYPASS" = "pass1" ]; then
  echo "230 SUCCESS"
else
  echo "530 FAILURE"
fi


AUTHFORW: -map{inPat}{localPat}{fwdPat} | -strip | -fwd


(available only in FTP and POP currently)
The "-map" prefix is used to split incoming authentication information of USER and PASS (in inPat pattern) into a pair of authentications, the one to be used locally by authServList (in localPat) and another to be forwarded to the server (in fwdPat). Each authentication information to be matched or generated is represented by a string of a pair of a user name and a password as "username:password". If the username string generated by fwdPat ends with a substring as "@Host" then it is striped and the Host is used as the destination server. The string is matched and generated by the pattern specification format common to the one used for pattern matching in the MOUNT parameter.
Example: -strip

1A) AUTHORIZER="-map{%S@%S:%S@%S}{%(0):%(2)}{%(1):%(3)},-list{u1:p1},-pam"


1B) AUTHORIZER="-strip,-list{u1:p1},-pam" ## equiv. to the above


incoming auth. <-- USER user1@user2@host2 + PASS pass1@pass2
local auth. by u1 or PAM <-- USER user1 + PASS pass1
outgoing to the server h2 <-- USER user2 + PASS pass2

Example: -fwd

2A) AUTHORIZER="-map{%S:%S}{%S:%S}{%S:%S},-list{u1:p1},-pam"


2B) AUTHORIZER="-fwd,-list{u1:p1},-pam" ## equiv. to the above


Example:

3A) AUTHORIZER="-map{%S}{%S}{},-list{u1:p1},-pam"


3B) AUTHORIZER="-list{u1:p1},-pam" ## equiv. to the above


As shown in the above example 1), "-strip" is used to support a nested username and password as USER "u1@u2@u3@h3@h2@h1" and PASS "p1@p2@p3". It strips the first element before '@' in the USER and PASS to be used for local authentication, strips the last element after '@' in USER as the destination server, then forwards remaining string to the destination server. "-fwd" specifies to use the same USER and PASS both for the local authentication and the authentication with a server.

If only authentication of user is necessary without authorization, the following special name will be useful as a authServList.

"&" -- the client host (user name on the client host is required)
"*" -- any authHost specified by the client as "user@authHost"

Example:

// clients from outside of local.domain is required authentication
SERVER=telnet AUTHORIZER="&:::!*.local.domain"
// any clients is allowed if the user is authenticated with localhost
SERVER=telnet AUTHORIZER="localhost" RELIABLE="*"
// using DeleGate's own list of "-socksusers" maintained with "-Fauth"
SERVER=socks AUTHORIZER=-socks.users

MYAUTH parameter*   ==  MYAUTH=username:password[:connMap]
                    --  default: none
                    --  restriction: applicable to Socks, VSAP, SMTP, and HTTP

Specify authorization information to be sent to an upstream server/proxy. Special characters in username or password must be escaped with "%XX" where XX is hexadecimal representation of a character code (see ascii(7)). Special characters to be escaped are: TAB ("%09"), SPACE ("%20"), '"' ("%22"), '%' ("%25"), ':' ("%3A"), '{' ("%7B"), and '}' ("%7D").

The pair of username+password which is sent from a client can be forwarded to the server by MYAUTH="%U:%P" (supported in HTTP and FTP only).

NOTE: For authentication with proxies, it is strongly recommended to use FORWARD with a gateway-URL including authentication information instead of MYAUTH. For example, SOCKS=host:port with MYAUTH=user:pass can be represented as FORWARD=socks://user:pass@host:port.

Example:

MYAUTH=userS:passS:socks
MYAUTH=userV:passV:vsap
MYAUTH=userM:passM:smtp:smtpserverM
MYAUTH=userH:passH:http:httpserverH
MYAUTH=userP:passP:http-proxy:httpproxyP

RIDENT parameter    ==  RIDENT=ridentType[,ridentType]*
       ridentType   ==  client | server
                    --  default: none

If RIDENT="server" is specified, identification information about the client socket got by getsockname(2) and getpeername(2) will be forwarded to the PROXY or MASTER-DeleGate which will receive the information by RIDENT="client", and will use it for access control. A DeleGate server with RIDENT="client" can accept both from DeleGate with RIDENT="server" and other proxy servers with no RIDENT support. An intermediate DeleGate in a chain of cascaded DeleGate servers should be given RIDENT="client,server".

Example:

host1# delegated -P8080 RIDENT=server MASTER=host2:8080
host2# delegated -P8080 RIDENT=client

MAXIMA parameter*   ==  MAXIMA=what:number,...
                    --  default: MAXIMA=listen:20,ftpcc:2,...

Specify the maximum number of resource usage, processes, connections, etc.

randstack	--	randomization range of stack base for security [32]
randenv	--	randomization range of environment variables base [1024]
randfd	--	randomization range of client socket file-descriptor [32]
listen	--	max. size of the queue for entrance port [20]
delegated	--	max. number of DeleGate processes runnable at a time [64]
service	--	max. number of services per delegated process [unlimited]
standby	--	max. number of standby process [32]
conpch	--	max. number of connections at a time per client host [unlimited]
ftpcc	--	max. number of FTP connection cache servers to a host [16]
nntpcc	--	max. number of NNTP connection cache processes to a host[16]
http-cka	--	(replaced by HTTPCONF=max-cka)
http-ckapch	--	(replaced by HTTPCONF=max-ckapch)
udprelay	--	max. number of parallel UDPrelay client [32]
winmtu	--	max. unit of send() on Win32 [1024]

TIMEOUT parameter*  ==  TIMEOUT=what:seconds,...
                    --  default: TIMEOUT=dns:10,acc:10,con:10,lin:30,...

Specify timeout period (in seconds by default) of what. The timeout value "0" means "never timeout" (unlimited). The unit of period is second by default, but can be changed like 1d(day), 1h(hour), 1m(minute).

shutout	--	disarming emergent shutout set on fatal error [1800]
dns	--	for DNS lookup [10]
dnsinv	--	for DNS inverse lookup [6]
nis	--	for NIS lookup [3]
acc	--	for accept from client (include FTP data connection) [10]
con	--	for connection to the server [10]
lin	--	LINGER for output [30]
authorizer	--	expiration of authorization by AUTHORIZER [unlimited]
dgnonce	--	for AUTHORIZER=-dgauth (lifetime of "nonce") [60]
ident	--	for connection to Ident server [1]
rident	--	for receiving RIDENT=client info. [1.0]
io	--	general I/O (no data transmission) [600]
silence	--	no data transmission either from client or server [0] (applicable only to tcprelay)
hello	--	for HELLO negotiation with the MASTER [30]
login	--	for login to proxy (Telnet,FTP,SOCKS) [60]
daemon	--	delegated [unlimited]
restart	--	cause restart at every specified period [unlimited]
standby	--	keep the delegated alive on standby for next client [30]
takeover	--	taking over a downloading to cache after client's disconnection [5] (after the disconnection of the client which initiated the downloading)
ftpcc	--	for keeping alive FTP Connection Cache [120]
nntpcc	--	for keeping alive NNTP Connection Cache [300]
http-cka	--	(replaced by HTTPCONF=tout-cka)
cfistat	--	for status information from -s,filter [1.0]

DELAY parameter*    ==  DELAY=what:seconds
                    --  default: DELAY=reject:60,unknown:60,...

Delay for specified seconds before doing what.

reject	--	continuous Reject resp. from self or MOUNTed servers [60]
unknown	--	continuous Unknown resp. from self or MOUNTed servers [60]
reject_p	--	continuous Reject resp. from origin server [0]
unknown_p	--	continuous Unknown resp. from origin server [0]

Each value specifies the maximum delay time and delay time increases according as the error count increases.

CHOKE parameter*    ==  CHOKE=Choking:Client:Ua:Referer:Url:Server:Protocol
                    --  default: none

This parameter integrates clients-choking functions scattered around parameters and options including DELAY, MAXIMA, MOUNT, RELIABLE, SCREEN, and -Eri. It is mainly intended to choke robots, spammers and attackers, but can be applied generally to any clients.
At the first field, Choking specifies restriction to be applied to a request. Following fields specifies a set of conditions to detect requests to which the Choking is applied. A Choking is applied when all of conditions match the specified conditions (to be combined by AND operation). All of condition fields can be empty and an empty filed is regarded as matched. A series of empty conditions to the end can be omitted.
Multiple CHOKE parameters can be specified and are combined by OR operation. CHOKE parameters are scanned in the specified order and the scanning stops at the firstly matched CHOKE.

To test if CHOKE parameters work as intended, an option "-Fchoke" is provided. It is applied to PROTOLOG file in an extended common logfile format (extended by "%X" to record Referer and User-Agent). For example it is used as bellow:

% delegated CHOKE=... -Fchoke < 80.http



At the beginning of each line in output, "-Fchoke" inserts the result of robot detection and access control.


"-Fchoke" with "-sa" option simulates access control parameters including CHOKE, RELIABLE, REACHABLE, REMITTABLE, PERMIT, REJECT, and SCREEN.

% delegated RELIABLE=... REACHABLE=... CHOKE=... -Fchoke -sa < 80.http

MOUNT parameter*    ==  MOUNT="vURL rURL [MountOptions]"
                    --  default: MOUNT="/* SERVER_URL*"

Map vURL to/from the rURL. URLs matches with vURL in a request message from a client are rewritten to rURL and forwarded to a server, and URLs matches with rURL in a response message from the server is rewritten to vURL and forwarded to the client. What is rewritten by MOUNT in each protocol is like follows:

HTTP -- URL or part of it appeared in header or HTML body (tags)

FTP -- file name in command and status response

NNTP -- newsgroup name in command, status response, and user data (header)

POP -- user and host name in USER,PASS,APOP command

IMAP -- user and host name in LOGIN command

SMTP -- mail address in the RCPT command

Telnet -- hostname and port number of destination server

LDAP -- base object name in requests/responses

If a vURL is terminated with "*" then partially matched path is also rewritten. If a rURL is terminated with "*" then remaining part in the partially matched path will be copied after the rURL.

Example: a MOUNT for HTTP-DeleGate

MOUNT="/abc/* http://host/*"
// rewrites "/abc/def" to/from "http://host/def"

If "=" is specified as vURL or rURL, it means mount as is without rewriting for the vURL in a request, or rewriting for rURL in a response.

The port number of the destination server (in rURL) can be prefixed with "-" or "+" to be determined dynamically by offsetting from the port number of the entransport, as in SERVER parameter.

A special host name "odst.-" in rURL (or in the SERVER parameter) represents the original destination host of the TCP connection from the client via NAT (provided by iptables on Linux). It can be used to configure a transparent proxy (or gateway) for arbitrary protocols. The original destination port number can be referred with "-" as "odst.-:-". The number can be mapped with an offset value as "-8000" or "+8000" for example. The name "odst.-" can be used in the "rserv" MountOption too.

If the rURL is of "file:path" and the path is a relative one, then the data file is searched under the DGROOT directory or directories listed in DATAPATH.

If a rURL is prefixed as "vurl:rURL", the rewritten URL (in a request message) from vURL to rURL will be rewritten by another MOUNT again. This recursive MOUNT is not applied to the rewriting a URL in response data from rURL to vURL, therefore it does not work as expected in HTTP where such reverse rewriting of URL in response is expected too.

Example: recursive MOUNT

MOUNT="/x/* vurl:/f/x/*"
MOUNT="/y/* vurl:/f/y/*"
MOUNT="/f/* ftp://server/*"
// "/x/path" is rewritten to "ftp://server/x/path"
// "ftp://server/x/path" is rewritten to "/f/x/path"


Abbreviations

To make configurations be simple and reusable, special abbreviated formats of URL can be used in MOUNT parameter. If "=" is specified as protocol-name, host-name or port-number in rURL which consists of protocol-name://host-name:port-number/url-path, then it represents that of the DeleGate itself (i.e. that of vURL). URLs beginning with "//" represents further abbreviations, "///path" for "=://=:=/path" (in the same protocol,host and port) and "//serv..." for "=://serv..." (in the same protocol).

Abbreviated host-name and port-number is substituted by that of the virtual host (given in HTTP Host: field) if exists, or by that of the real interface with the client. To explicitly specify the real interface, use "-P" for "host-name:port-number part like "http://-P/path".

Example: abbreviation in rURL of MOUNT parameter

// DeleGate's parameters: SERVER=http -Pdhost:9080 ...
// Requested URL: http://vhost:9080/x/
MOUNT="/x/* =://=:=/y/*" -> http://vhost:9080/y/
MOUNT="/x/* ///y/*" -> (the abbreviation of the above)
MOUNT="/x/* //-P/y/*" -> http://dhost:9080/y/
MOUNT="/x/* =://serv/y/*" -> http://serv:80/y/
MOUNT="/x/* //serv/y/*" -> (the abbreviation of the above)
MOUNT="/x/* //serv:=/y/*" -> http://serv:9080/y/
MOUNT="/x/* //=:9088/y/*" -> http://vhost:9088/y/
MOUNT="/x/* https://=/y/*" -> https://vhost:443/y/


Complex Matching and Rewriting

A pattern following "*%" in vURL and rURL represents a pattern for complex matching specified in the format like that of scanf(3). Each format specification consists of a specification following "%", like "%c", "%[a-z]" and so on. The extended format "%S" has variable meanings determined by its adjacent character, i.e. "%Sx" means "%[^x]x": ex. "%S." for "%[^.]." and "%S/" for "%[^/]/". "%(N)" in rURL means copying Nth element in vURL. If a vURL pattern ends with "$" character, then complete matching to the end of URL string is required.

Example: complex matching and rewriting

// Requested URL: http://dhost/x/abc/def
MOUNT="/x/*%S/%S ///y/*%S.%S" -> http://dhost/y/abc.def
MOUNT="/x/*%S/%S ///y/*%(1)/%(0)" -> http://dhost/y/def/abc
MOUNT="/x/*%1[a-z]%S http://w/*%S/%S" -> http://w/a/bc/def

MountOptions == option[,option]*

MountOptions is a list of options, to make MOUNT be conditional, or to apply some functions only to MOUNTed URLs. Some of them are common to any protocol and others are specific to a protocol ( HTTP, NNTP ).

CONDITIONS:
The first group of options are to make MOUNT be conditional depending on source and destination (client and server). When a MOUNT parameter have a MountOption including one or more conditions, the MOUNT will be ignored without all of conditions are true.

from={HostList} -- from the client.

true if the client is included in the HostList.

via={HostList} -- via the host.

true if at least one host passed through on the way is included in the HostList.

path={HostList} -- through the hosts.

true if all of hosts passed through is included in the HostList.

auth={HostList} -- authorized by the host.

true if a password based authentication succeeded with a AUTHORIZER host listed in the HostList.

withssl

true if the client-side connection is encrypted with SSL or TLS

sni={HostList} -- name based virtual hosting based on SNI/TLS

true if the TLS client connected to the DeleGate with the hostname (server name indicated in TLS protocol) included in HostList.

host={HostList} -- interface host with the client.

true if the client has connected to the DeleGate via the specified network interface included in the HostList.
Note that this option is applicable to any client side protocol, that is, not only HTTP-DeleGate but also DeleGate for FTP, POP, NNTP, etc. can switch destination server based on the client side interface if its has an IP address distinguishable from others.
When the DeleGate is acting as an origin HTTP server and a virtual host name is shown in "Host: host" field in the request message, the virtual name is examined prior to the real host name. If multiple virtual names are bound to the same IP-address, prefix "-" to the virtual hostname like "host=-hostname" to distinguish among virtual names.

odst={HostList} -- NAT based virtual hosting

true if the original destination of the TCP connection from the client is included in the HostList. This option is available on Linux with NAT (by iptables) on Linux. The original destination can be used as the real destination with a special host name "odst.-".

dst={HostList} -- to the server.

true if the destination host is included in the HostList. This option will be useful when "=" is used as the right hand of MOUNT.

udst={HostList}

true if the host in the site part of a full-URL (as http://site/path) is included in the HostList. This option will be used with the "referer" MountOption to rewrite URL in the "Referer" field.

direction=Direction -- request or response

true when the MOUNT parameter is applied to specified Direction which is one of followings:

fo -- apply forward (request rewriting) only

bo -- apply backward (response rewriting) only

bif -- apply backward if it was applied forward

-f,conditionList -- conditions applied only in request rewriting

-b,conditionList -- conditions applied only in response rewriting

-f.condition -- a condition applied only in request rewriting

-b.condition -- a condition applied only in response rewriting

-x.condition -- a condition to be applied to both directions

"avhost" and "nvhost" are conditions tested only in request rewriting by default. These conditions come to be tested also in response rewriting by prefixing "-x." as "-x.nvhost=host".

pri=signedFloatNumber -- priority of this MOUNT parameter

a MOUNT parameter with larger priority value is tested prior to another with lower priority. The default priority value is zero.

nocase -- ignore character case in URL path matching

These HostList should be a list of host:port, where :port part can be omitted when it is not to be cared. The host part can be represented as "*" when the difference of network interface is not to be cared.

Example:

// switch MOUNT depending on from which interface the client is
MOUNT="* URL1 host=this-host"
MOUNT="* URL2 host=localhost"
// switch MOUNT depending on from which port the client is
-P70,80
MOUNT="* URL1 host=*:70"
MOUNT="* URL2 host=*:80"


CONTROLS:
The second group of options are to control the behaviors of DeleGate which are local to the MOUNT point.

public -- allow public access

do not apply any access restriction (by PERMIT etc.) to this MOUNT point.

rident[=no] -- forward RIDENT information to server

forward (or stop forwarding) RIDENT information to the MOUNTed server regardless of the RIDENT=server parameter.

ro -- allow read only.

applicable to NNTP (inhibit POST command) and origin FTP (default).

rw -- allow both read and write.

allow origin FTP-DeleGate to write to its local files.

cache=no -- disable cache.

disable any usage of cache for the server of this MOUNT point.

expire=period -- validity of cache

expire period of the MOUNT point, overriding the global EXPIRE parameter.

expires=period -- validity of each response

if specified, "Expires:" field is added into each HTTP response message. If the period begins with '+' or '-', like "expire=+1d", and if the original message has "Expires:" header, then the expire date is relative to the original expiration date.

ftocl=filterCommand -- apply external filter

apply the filter to the MOUNT point, overriding the global FTOCL parameter.

charcode=charCode -- code conversion.

code conversion specific to this mount point, overriding the global CHARCODE parameter.

proxy=host:port -- upstream proxy server

master=host:port -- upstream MASTER-DeleGate

use an upstream proxy server for the MOUNT point, instead of the one specified in the global MASTER or PROXY parameter.

MAXIMA=bps:speed -- maximum transmission speed

choke the speed of the date transmission (HTTP and FTP) as MAXIMA=bps:128k for example.

URICONV parameter*  ==  URICONV={convSpec|defElem|defAttr}
          convSpec  ==  convList:attrList
           defElem  ==  defelem:+,elemnameList
           defAttr  ==  defattr:+,attrnameList
                    --  default: it will be shown by URICONV=dump

Specify which kind of URI rewriting should be applied to which kind of attributes of tags in HTML document. The convList is a list of following items.

mount	--	rewriting by MOUNT
normal	--	normalize MOUNTed URL if it includes "../" in URL-path
partial	--	represent (MOUNTed) URLs as partial URLs if possible
full	--	convert all of URLs to full URLs

The special convList URICONV="+" means loading the default URICONV configuration (no attrList in this case in the current implementation). The attrList is a list of attributes names each may be postfixed with an element name. A special attributes name "+" means the default set of attributes. An attribute prefixed with "-" character is excluded from the calculated set of attributes.

Another special convList URICONV="where:any" enables searching URL to be rewritten not only in HTML tags but also in XML, JavaScript, CSS (Cascading Style Sheets) and SWF (Shockwave Flush).

Example:

URICONV=mount,normal,partial:+ -- might be the default after Ver.6
URICONV=full:+,-HREF/BASE -- rewrite everything except HREF/BASE
URICONV=dump -- show the current URICONV config.
URICONV=+ URICONV=mount:-SRC/IMG URICONV=full:SRC/IMG

BASEURL parameter   ==  BASEURL=URL
                    --  default: none

The base of (virtual) URL of this server which will be embedded in each absolute URL generated by the DeleGate: ex. icon URLs in HTML pages generated by NNTP/HTTP gateway DeleGate.

When an origin/gateway HTTP-DeleGate received "Host:vhost1" in a request header, it overrides BASEURL="http://vhost0" parameter to have "vhost1" be the base URL of the DeleGate. To override the "Host:" header by BASEURL, prefix "-" to a host name as BASEURL="http://-vhost0".

Example:

MOUNT='/* nntp://newsserver/*" BASEURL="http://wwwserver/news"
// this will be useful when a HTTP server "http://wwwserver" is mapping
// its path "/news" to the root of this HTTP-DeleGate.

DELEGATE parameter  ==  DELEGATE=gwHost:Port[:ProtoList]
                    --  default: DELEGATE=currentHost:currentPort

This parameter seems to be almost superseded by BASEURL, RELAY, and URICONV parameters.

Originally, this parameter is introduced to control proxying mode for non-CERN HTTP type proxy (including gopher proxy) by rewriting a URL (or pointer) with gateway-_-URL or proto://gwHost:Port/-_-URL notation, where the gwHost:Port part is generated and embedded by DeleGate.
This parameter is introduced to customize the representation of the gwHost:Port part. It is a representation of the entrance port of this DeleGate which must be resolvable and reachable from clients. To make it be most usable, the default value of gwHost is that of current network interface of the host of this DeleGate through which the current client reached to this DeleGate, and it is represented in raw IP address number so that clients can reach the DeleGate even if they don't know how to resolve the host name of the DeleGate.
Exceptionally, if the entrance port is specified with with an explicit network interface like "-Phost:port, the default value of DELEGATE is set to the host:port.
By specifying an optional ProtoList, you can limit to which protocols this proxying is applied. URLs (or pointers) in a response message are rewritten prefixed with "proto://gwHost:Port/-_-" so that the request to it is directed again to this DeleGate (at gwHost:Port), if the protocol is included in the ProtoList.

Thus you can disable the proxying mode specifying non existing entrance port and an empty ProtoList like DELEGATE="-:0:-all". But this can be done more simply by RELAY parameter and it is disabled by default in recent versions.

COUNTER parameter   ==  COUNTER=listOfCounterControl
    counterControl  ==  do | total | acc | ssi | ref | err | ro | no | mntpV
                    --  default: COUNTER=no
                    --  restriction: applicable to HTTP, SMTP, FTP and DNS

Specify the usage of access counters.
(CAUTION: the current implementation of the counter in DeleGate/9.X is tentative thus the location and the format of the counter file might be modified and become incompatible in future)

do -- enable all counters including "total,acc,ssi,ref,err"

total -- enable the total hit counter of this server

acc -- enable access counters for each access to each URL

ssi -- enable access counters for SSI (by PAGE_COUNT in .shtml)

ref -- enable referrer counters for HTTP "Referer:"

err -- enable error counters (for SMTP)

ro -- enable counters in read-only

no -- disable counters [default]

mntpV -- use the counter of the MOUNT point (vURL) instead of each URL

If enabled with COUNTER="do", all access counters for any requests, referrers, and errors are incremented. If enabled with "total", the access counter for any requests to this server is incremented. If enabled with "acc", access counters for any requests to each target URL is incremented. If enabled with "ssi", only the access counter for the URL of a SHTML page including a SSI PAGE_COUNT reference is incremented when the page is accessed. If enabled with "ref", the referrer counter of the URL in the HTTP "Referer:" fields is incremented.

Each access counter is stored in a file at "ADMDIR/counts/access/URL#count". Each counter file starts with a line consists of the numbers of accesses in ASCII decimal format so that it can be initialized or modified manually. The line can contain three numbers; the first one is the total count, the second one is the count excluding repetitive accesses from the same client, and the third one is the count excluding repetitive access from one of recent ten clients. Each count are represented as %T, %U and %V respectively in the format string described below.

The counter can be displayed in a specified format using SSI as the PAGE_COUNT or COUNTER value. If no "url" attribute is specified in a tag, the URL of the SHTML file containing the tag is implied. Counter values are converted to a printable character string following to the format string given in the "fmt=..." attribute. The default format is "%T".

Format Specifiers:

%T -- total count

%U -- the count excluding repetitive accesses form a client

%V -- the count excluding repetitive accesses from recent 10 clients

%N -- the number of networks [ 0 - 1023 ]

%M -- the map of networks

%L -- the list of the last ten clients

%mT %mU %mV -- mean counts per day

%mHT %mHU %mHV -- mean counts per hour

%tC -- the time of the first count (counter creation)

%tT %tU %tV -- the time of update of each count

The specifier %N represents the number of networks of clients where each network is with net-mask of 10 bits (0xFFC00000 255.192.0.0/10). This means that the whole IPv4 address space is divided into 1024 networks. So the %N represents the distribution of clients onto networks over the address space as a coverage value in per-mill. %M shows the distribution of clients as a visual map.

Example:

<!--#echo var=PAGE_COUNT -->

<!--#echo var=COUNTER -->

<!--#echo var=COUNTER fmt="%T hits since %tC" -->

<!--#echo var=COUNTER url="URL" -->

<!--#echo var=COUNTER fmt="%U/%T hits" -->

<!--#echo var=COUNTER url="URL" fmt="%U/%T hits" -->

The total count is displayed by TOTAL_HITS tag or by COUNTER tag with "sel=total". The referrer counter of a URL is incremented when the URL is in "Referer:" header in a HTTP request. Each referrer counter is stored in a file at "ADMDIR/counts/referer/URL#count-ref". The referrer counter can be displayed with "sel=ref" attribute in the COUNTER tag.

Example:

<!--#echo var=TOTAL_HITS -->

<!--#echo var=COUNTER sel=total -->

<!--#echo var=COUNTER url="URL" fmt="%U/%T refs" sel=ref -->

Enabling all counters for each URL can be expensive and/or unnecessary. You can reduce counters by using the counter of a MOUNT point as the representative, or using only total access counters of the server. In the following example, counters for all URLs is enabled by default (with COUNTER=do), while counters for URLs under /srv1/ is represented by the counter of /srv1/, and only the server's total counter and SSI counters are enabled for URLs under /mine/. As shown in this example, COUNTER can be specified as a MountOption of which initial value is inherited from the COUNTER parameter.

Example:

    COUNTER=do
    MOUNT="/srv1/* http://srv1/*  COUNTER=mntpV"
    MOUNT="/mine/* file:dirpath/* COUNTER=no,total,ssi"

COUNTERDIR parameter  ==  COUNTERDIR=dirPath
                    --  default: COUNTERDIR='${ADMDIR}/counts[date+/year%y/week%W]'

Specify the base directory under which counter files are placed, if the COUNTER paramer is specified to enable counters (as COUNTER=do). Note that the directory is aged weekly by default (by "%W" in the aging notation). It can consume too many files for counters (the size will not be so much but the number of files can be too many). You can stop the aging as in DeleGate/9.X in which the directory was not aged as if sepecified like COUNTERDIR='${ADMDIR}/counts' (hard coded in the program thus was not configurable). Or you can age the files yearly as COUNTERDIR='${ADMDIR}/counts[date+/year%y]'.

CACHE parameter*    ==  CACHE=cacheControl[,cacheControl]*[:connMap]
      cacheControl  ==  do | no | ro
           connMap  ==  ProtoList[:[dstHostList][:srcHostList]]
                    --  default: none
                    --  restriction: applicable to HTTP, FTP, NNTP and Gopher

Specify a restriction of cache usage.

do -- create CACHEDIR if not exist (to enable cache)

no -- disable cache

ro -- use cache in read-only

Cache is enabled by default. Cache will be disabled if the CACHEDIR directory does not exist, or it is not readable and writable by the DeleGate, or CACHE="no" is specified, or "cache" is not included in CONNECT.

EXPIRE parameter*   ==  EXPIRE=validity[/custody][:connMap]
           connMap  ==  ProtoList:dstHostList:srcHostList
          validity  ==  period
           custody  ==  period
            period  ==  Num[d|h|m|s]
                    --  default: EXPIRE=1h

EXPIRE specifies the term of validity of cached data, in unit of days, hours, minutes, or seconds. Validity does not mean active removal of cached data by DeleGate; DeleGate merely ignores cached data if it is older than the specified term.

CACHEFILE parameter ==  CACHEFILE=fileNameSpec
                    --  default: CACHEFILE='$[server:%P/%L/%p]'

CACHEFILE specifies how the file name of a cache file is formed. The name is derived mainly from informations about server host and requested URL. Those informations are specified in the format "$[server:format]" where the format is a sequence of symbols each refers a part of an URL scheme://host.d2.d1:port/path as follows:

%P	--	scheme	Protocol name part
%L	--	host.d2.d1:port	Login (or site) part
%H	--	host.d2.d1	Host name
%T	--	port	Port number
%h	--	d1/d2/host	hierarchical host name directory
%d	--	d1/d2	hierarchical domain name directory
%1	--	d1	top level domain
%2	--	d2	second level domain
%p	--	path	URL-path part
%Q	--	host.d2.d1.d0	use FQDN of a host name (like %Q%L or %Q%H)

Another formatting pattern is "$[hash:format]" which hashes a string generated by format into hexadecimal value ranging from "00" to "1f". This will be useful to divide a single huge directory containing all servers into 32 small directories, which can be on physically different disks.
Example:

CACHEFILE='$[server:%P]/$[hash:%H]/$[server:%L/%p]'

ICP parameter*      ==  ICP=icpServerList[:icpServerSpec[:connMap]]
     icpServerList  ==  icpServer[,icpServer]*
         icpServer  ==  icpHost[/icpType/proxyPort/icpPort]
     icpServerSpec  ==  icpOptions:proxyPort:icpPort
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none
                    --  restriction: applicable to {HTTP,FTP}-DeleGate

If specified, and if "icp" is included in the CONNECT sequence, a HTTP-DeleGate will try to get a requested resource from specified ICP server. The meaning and default value of each field is as follows:

icpHost:

The host name or IP address of the ICP server [localhost]

icpType:

s	-- the ICP server is a "sibling" [default]
p	-- the ICP server is a "parent"
l	-- the ICP server is a "listener" which never respond
n	-- the ICP server is a navigation proxy
o	-- require HIT_OBJ response
H	-- the object server is a HTTP proxy [default]
D	-- the object server is a MASTER-DeleGate.
O	-- the object server is an origin server.

proxyPort:

The port number of the corresponding object server [8080].

icpPort:

The port number of ICP protocol [3130].

icpOptions:

timeout/N	-- period to wait response as an ICP client (in seconds)[2.0]
parent	-- mark the default type of icpServers as "parent"
listener	-- mark the default type of icpServers as "listener"
hitobj	-- enable HIT_OBJ for all icpServers by default
Origin	-- object servers are origin server
DeleGate	-- object servers are DeleGate

Example:

ICP=icphost
// This is the simplest usage which is the abbreviation of
// ICP="icphost/sH/8080/3130:timeout/2.0:8080:3130:*:*:*"


ICP="host0"
ICP="host0//8080/3130"
ICP="host0::8080:3130"
ICP="host1:timeout/1.0:::http,ftp:!*.my.domain:*.my.domain"
ICP="host1,host2/O/80/13130:timeout/2.0:8080:3130"

CHARCODE parameter* ==  CHARCODE=[inputCode/]outputCode[:[tosv][:connMap]]
        outputCode  ==  charCode
          charCode  ==  iso-2022-jp | euc-jp | shift_jis | utf-8 | us-ascii |
                               JIS | EUC | SJIS | UTF8 | ASCII | guess
           connMap  ==  [ProtoList][:[dstHostList][:[srcHostList]]]
                    --  restriction: applicable to HTTP, FTP, SMTP, POP,
                                     NNTP, Telnet, Tcprelay
                    --  default: none

If specified, DeleGate will convert the JIS code in text type response message into the specified character code. When UTF8 is specified, a mapping table necessary for conversion between Unicode and JIS code is downloaded automatically from the server at Unicode.Org via DeleGate.ORG.

The pseudo code name "guess" means not doing conversion but supplement the "charset" attribute in "Content-Type" header in a message when it is lacking, guessing it from the body of the message. This is useful when a viewer program (ex. a web browser) of the message is not localized to Japanese thus non-ASCII codes like EUC-JP are guessed as European or so by the viewer.

If "tosv" is specified, the conversion is applied to the request message (or a message toward a server). The conversion is also applied to fragments of Japanese text in a HTTP request message encoded in "%XX" in its request URL or in the body of a POST message (when it is encoded in Content-Type: application/x-www-form-urlencoded). The set of values of Content-Type to which the conversion is applied can be specified with HTTPCONF=post-ccx-type.

The application of the conversion can be limited only to a specified set of protocols, servers and clients specified with connMap. In the connMap, the default value of ProtoList, dstHostList and srcHostList is "*" which matches any protocols or hosts.

Example: send response in UTF8 to clients and send request in Shift_JIS to HTTP servers

CHARCODE=UTF8 CHARCODE=SJIS:tosv:http


For the FTP protocol, the conversion is applied only to the data of the ASCII type relayed on the data-connections by default. It is applied also to binary data or data on the control-connection with FTPCONF="ccx:any".

To enable this parameter for internet-mail/news protocols (SMTP, POP and NNTP), also MIMECONV parameter must be specified so that it enables character conversion (enabled by default).

A HTTP client can override this specification by sending its choice in "Accept-Language" field in a request message, which may be configurable in each client (WWW browser). For example, if "Accept-Language: (charcode=EUC)" is sent in a request from client, the response text will be converted into EUC regardless of CHARCODE specification of the DeleGate. If "Accept-Language: (charcode=THRU)" is specified, any conversion specified by the administrator of this DeleGate is disabled.

CHARMAP parameter*  ==  CHARMAP=mapType:charMap[,charMap]*[:tosv]
           mapType  ==  ascii | ucs | jis | ucsjis | jisucs
           charMap  ==  inCharCode1[-inCharCode2]/outCharCode2[-[outCharCode2]]
          charCode  ==  hexa-decimal code | single ASCII character
                    --  default: none

If specified, a character in texts relayed in a message of an application protocol is mapped to another character. By default, the mapping is applied to the response data to client. It can be applied to the request data to server specifying ":tosv".

A character to be mapped is represented in a hexa-decimal value of it (represented in more than 2 columns), or a direct character in a single columns. The characters in the JIS X 0208 character set encoded in the variants of its encoding (ISO-2022-JP, EUC-JP, and Shift_JIS) are represented in its JIS code value without the most significant bits (8080) as "2121". The characters in the JIS X 0212 character set are represented in its JIS code value prefixed with "1" as "1222F".
If inCharCode2 and outCharCode2 is specified, each character in the range is mapped to the corresponding character. If no -outCharCode2 is given, any input characters in the range is mapped to outCharCode1.

The mapType is one of followings:

ascii -- ASCII to ASCII mapping

ucs -- UCS to UCS mapping when the input is coded in UTF-8

jis -- JIS to JIS mapping when the character set of input is JIS X 0208

ucsjis -- UCS to JIS mapping in the conversion by CHARCODE=JIS or SJIS or EUC

jisucs -- JIS to UCS mapping in the conversion by CHARCODE=UTF8

Example: reverse lowercase and upper case

CHARMAP=ascii:a-z/A-Z,A-Z/a-z


Example: "rot13" encoding

CHARMAP=ascii:a-m/n-z,n-z/a-m,A-M/N-Z,N-Z/A-M


Example: replace any Japanese character in JIS X 0208 with "GETA MARK"

CHARMAP=jis:0100-7F7F/222E


Example: replace any Japanese character in JIS X 0212 with "GETA MARK"

CHARMAP=jis:10000-1FFFF/222E


Example: represents unknown characters by "WHITE SQUARE" instead of "GETA MARK"

CHARMAP=jis:0000/2222

HTMLCONV parameter  ==  HTMLCONV=convList
          convList  ==  conv[,conv]*
              conv  ==  deent | enent | fullurl
                    --  default: HTMLCONV=deent

Specify a list of flags to control conversion for HTML text in a HTTP response message.

deent	--	decode entity symbol
enent	--	encode entity symbol
fullurl	--	convert all of URLs to full URLs (equals to URICONV="full:+,-HREF/BASE")

"deent" and "enent" control encoding and decoding of special characters between HTML and plain text ("&lt;" to/from "<" for example) when such characters appear in a text of multi-byte charset (like ISO-2022-JP). If "deent" is specified, encoded entity symbol appearing in multi-byte charset text will be decoded. This may be useful to recover a text including characters indiscriminately encoded by encoder which does not care multi-byte characters.
If "enent" is specified then entity symbols appearing out of multi-byte charset text will be encoded. This may be useful in case of NNTP-DeleGate to be accessed by WWW client. If empty list is specified, any conversion is disabled.

MIMECONV parameter  ==  MIMECONV=mimeConv[,mimeConv]
          mimeConv  ==  thru | charcode | nospenc
                                    | textonly | alt:first | alt:plain
                    --  default: none
                    --  MIMECONV="" if CHARCODE parameter is given

Control MIME encoding/decoding in NNTP/POP/SMTP DeleGate. MIMECONV=thru disables any MIME encoding/decoding, and MIMECONV=charcode enables only character code conversion. MIMECONV=nospenc disables a special encoding of space character in non-ASCII (ISO-2022-JP) text in MIME header.

Here is a group of options for filtering a "multipart/*" message to convert it into a plain message by selecting or unfolding the list of parts as follows:

textonly -- only the first text/* part in multipart/*

alt:first -- only the first alternative in multipart/alternative

alt:unfold -- all of alternatives in multipart/alternative

FCL parameter       ==  FCL=filterCommand
FTOCL parameter     ==  FTOCL=filterCommand
FFROMCL parameter   ==  FFROMCL=filterCommand
FSV parameter       ==  FSV=filterCommand
FTOSV parameter     ==  FTOSV=filterCommand
FFROMSV parameter   ==  FFROMSV=filterCommand
FMD parameter       ==  FMD=filterCommand
FTOMD parameter     ==  FTOMD=filterCommand
FFROMMD parameter   ==  FFROMMD=filterCommand
filterCommand       ==  [-s,][-p,][-w,]command
                    --  default: none

Specify a filter command to be applied to data transmitted between DeleGate and clients, or between DeleGate and servers. When a filterCommand is specified in relative path name, it is searched in LIBPATH.

Filters can be applied conditionally using CMAP based on circuit level information, or using CFI script based on application level information.

FILTER CONTROL OPTIONS: options to get status information from, or control synchronization with filter program.

-s -- get status information (ex. authentication) from filter
-w -- wait the filter process to exit before starting relay
-p -- detach the filter when it exits then continue relaying


BUILT-IN FILTERS: if a filterCommand is prefixed with "-", then it is a filter built-in to DeleGate.

credhyFilter == -credhy ... encryption/decryption filter

teeFilter == -tee[teeOpt]*[SPACE filePath] ... filter like tee(1) command

catFilter == -cat[teeOpt] ... filter like cat(1) command

teeOpt == -h | -n | -t | -v | -l | -e

-h -- output header part only
-n -- number the output lines
-t -- time stamp for each output line
-v -- visualize invisible characters
-l -- (with -tee) output to LOGFILE instead of stderr (default)
-e -- (with -tee) output to stderr


codeconvFilter == -charCode ... char code conversion as CHARCODE

charCode == jis | sjis | euc | utf8

Example:
FTOCL=-tee-h-n FTOSV=-tee

XCOM parameter      ==  XCOM=filterCommand
XFIL parameter      ==  XFIL=filterCommand
                    --  default: none

XCOM and XFIL is used together with SERVER="exec" parameter. A special protocol name "exec" means executing some local command rather than connecting to a server. With "exec", DeleGate will work like simple inetd or wrapper. What will be executed is specified with either XCOM or XFIL parameter. Commands executed as XCOM will be given standard I/O which are bound for a socket connected to the client. Commands executed as XFIL will be given standard I/O which are redirected to a pair of pipes bound for DeleGate, which relays it to and from the client.

On WindowsNT and OS/2, commands executed as XCOM will be given a environment variable "SOCKHANDLE_CLIENT" which have the handle value of the inherited socket connected to the client.

CHROOT parameter    ==  CHROOT=dirPath
                    --  default:  none
                    --  restriction: super-user only on most of Unix

Change the root of file system to dirPath at the start using chroot(2) system call, restricting accessible (visible) files to ones under dirPath. This is effective to isolate the DeleGate from the whole file system of the host machine preventing DeleGate from possible destruction of them by its bug or by intrusion. DGROOT is interpreted after the root is changed.
A special case CHROOT="/" means using the value of (default or specified) DGROOT as CHROOT and set DGROOT="/". That is, DGROOT="/path" with CHROOT="/" are equal to DGROOT="/" with CHROOT="/path".

DGROOT parameter    ==  DGROOT=dirPath
                    --  default: if ${STARTDIR}/DGROOT exists then use it, or
                                  on Unix: '/' if CHROOT is set or
                                           '${HOME}/delegate' or
                                           '/var/spool/delegate-${OWNER}' or
                                           '/tmp/delegate-${OWNER}'
                               on Windows: '/Program Files/DeleGate'

All of sub-directories (LOGDIR, ADMDIR, CACHEDIR, WORKDIR, ETCDIR, ACTDIR and TMPDIR) will be located under the DGROOT by default.
At the start up time (on Unix), DeleGate searches an available DGROOT which is both readable and writable by the OWNER. When a candidate directory does not exist, DeleGate tries to make the directory by itself. If DGROOT is specified explicitly, it is tried first. If it failed or no DGROOT is given, default candidates will be tried in order until an available directory is found.

SHARE parameter     ==  SHARE=dirPatternList
                    --  default: empty

If specified, created directories or files which has name matches with given pattern will be set with mode 0777(rwxrwxrwx) or 0666(rw-rw-rw-) respectively, to be sharable among arbitrary users. When a pattern is specified in non-absolute form, it is regarded as relative to DGROOT. By default, directories or files will be created with mode 0755(rwxr-xr-x) or 0666(rw-rw-rw-), as modified by UMASK which is 022 typically.

Example:

// make everything sharable
SHARE=""
// share cache and log under DGROOT
SHARE="cache/*,log/*"
// share directories with older versions
SHARE='${CACHEDIR}/*' CACHEDIR='/var/spool/delegate-anybody'
SHARE='${VARDIR}/*' VARDIR='/var/spool/delegate'

UMASK parameter     ==  UMASK=mask
                    --  default: the value of umask(2)

Set mask for file creation mode, using umask(2) system call.

VARDIR parameter    ==  VARDIR=dirPath
                    --  default: VARDIR='${DGROOT?&:/var/spool/delegate}'

This parameter seems be obsolete after DGROOT has become standard in DeleGate/6.0. It specifies the default base of sub directories like DGROOT except for ACTDIR and TMPDIR. The default value of VARDIR is the value of DGROOT.

CACHEDIR parameter  ==  CACHEDIR=dirPath
                    --  default: CACHEDIR='${VARDIR}/cache'

To enable cache, the directory CACHEDIR must exist and is both readable and writable by the DeleGate. It will be automatically created with CACHE="do" with necessary permissions.

ETCDIR parameter    ==  ETCDIR=dirPath
                    --  default: ETCDIR='${VARDIR}/etc'

The directory to hold persistent files for configuration and administration of DeleGate. Configuration files for origin SMTP-DeleGate(SMTPGATE) and origin NNTP-DeleGate (NNTP) are placed hear.

ADMDIR parameter    ==  ADMDIR=dirPath
                    --  default: ADMDIR='${VARDIR}/adm'

The directory to hold genarated files for administration of DeleGate, including files for shutout defense, password repository of -Fauth, identification code of executalbe file of DeleGate, server's statistics file, and COUNTER.

LOGDIR parameter    ==  LOGDIR=dirPath
                    --  default: LOGDIR='${VARDIR}/log'
                    --  v10-default: LOGDIR='log[date+/y%y/m%m/%d]'

The default directory where log files are placed. From the version 10, by default, log files became devided by year, month and day, as 'DGROOT/log/y14/m08/20/80.http' for example.

LOGFILE parameter   ==  LOGFILE=[LogFilename]
PROTOLOG parameter  ==  PROTOLOG=[LogFilename][:logFormat]
ERRORLOG parameter  ==  ERRORLOG=LogFilename
TRACELOG parameter  ==  TRACELOG=LogFilename
                    --  default: LOGFILE='${LOGDIR}/${PORT}'
                    --  default: PROTOLOG='${LOGDIR}/${PORT}.${PROTO}'
                    --  default: ERRORLOG='${LOGDIR}/errors.log'
                    --  default: TRACELOG='${LOGDIR}/ptrace.log'

If LogFilenames are specified in a relative path then they are placed under ${LOGDIR}. If those names start with "./" then they are placed under ${WORKDIR}.

The patterns ${PROTO} and ${PORT} will be substituted with the protocol name and the port number of this DeleGate respectively. These files and directories will be created automatically by DeleGate if possible. You can stop logging by specifying null file name like LOGFILE="" or PROTOLOG="".

The format of PROTOLOG for HTTP is compatible with the common logfile format and is customizable. The format of PROTOLOG for FTP is compatible with xferlog.

SYSLOG parameter*   ==  SYSLOG=[syslogOpts,][syslogServ]
        syslogOpts  ==  syslogOpt[,syslogOpts]
         syslogOpt  ==  -vt | -vs | -vS | -vH | -fname
                    --  default: none

This parameter specifies recording log data via the "syslog" service (RFC3164). The "facility.priority" pair of logged data of LOGFILE is "daemon.debug" for usual data and "daemon.err" for errors. (It will be divided into more detailed levels in the future.) The log data of PROTOLOG is sent with "daemon.notice". The facility name can be changed with a "-fname" option.

Multiple SYSLOG parameters can be specified to send a log data to multiple different destinations each specified by a syslogServ. A syslogServ is a URL of a syslog server or a local file. The default syslogServ is the local logger to which log is sent via the standard "syslog()" function. For each destination, the log format or detailness can be specified by prefixing a list of syslogOpt as follows:

-vt	-- terse LOGFILE
-vs	-- without LOGFILE
-vS	-- without PROTOLOG
-vH	-- without the syslog header
-fname	-- use the facility name instead of "daemon"

Example:

SYSLOG=	-- to the local syslog
SYSLOG=syslog://host	-- to a remote syslog server
SYSLOG=syslog://host:port	-- on a non-standard port
SYSLOG=/dev/tty	-- to the console
SYSLOG=file:path	-- to a local file
SYSLOG=-vH,file:path	-- without the syslog header
SYSLOG=-fdaemon	-- as the "daemon" facility (default)
SYSLOG=-flocal1	-- as the "local1" facility

The source port (and the address) of syslog UDP packets to a remote syslog server can be specified as SRCIF=":8514:syslog" (or SRCIF="xx.xx.xx.xx:8514:syslog") for example.
Switching syslog servers based on each client and server of the application protocol is not (yet) supported.

If the pattern "[date+format]" is included in the file name, the format string is evaluated by strftime(3) compatible function with the current time, and will be substituted with the evaluated value. This means that a log directory (or file) specified will be divided into a granularity of specified time period, thus it is aged. Formats to represent typical time periods are as follows:
%Y -- year (like 2000)
%y -- year without century [00-99]
%m -- month number [01-12]
%d -- day of month [01-31]
%W -- week number of year [00-53]
%w -- weekday number [0-6, Sunday=0]
%H -- hour [00-23]


Example: aging a log file day by day and rotate by a month

LOGFILE='${PORT}[date+.%d]'

Example: make log directory hierarchical by date

LOGDIR='log[date+/aged/%y/%m/%d]'

The latest LOGFILE will be pointed with another file name (hard link to it) which name is made by omitting "[date+format]" parts from LOGFILE specification. For example, by the LOGFILE specification in the above example, logfile will be named like "log/aged/00/12/31/80.http" while the latest one is given another name "log/80.http".

Another pattern for aging is "[start+format]" which will be evaluated in the same way with "date+" except that it will be substituted by the time when the DeleGate started (or restarted by SIGHUP or specified TIMEOUT=restart).

EXPIRELOG parameter ==  EXPIRELOG=LogFilename
                    --  default: EXPIRELOG='${LOGDIR}/expire.log'

The log-file for expiration by "-Fexpire" function or "-expire" action in CRON.

WORKDIR parameter   ==  WORKDIR=dirPath
                    --  default: WORKDIR='${VARDIR}/work/${PORT}'

If WORKDIR is not accessible, or if WORKDIR is not explicitly specified when -vv option is given, then current directory (of invoker of this DeleGate) will be used as WORKDIR.

ACTDIR parameter    ==  ACTDIR=dirPath
TMPDIR parameter    ==  TMPDIR=dirPath
PIDFILE parameter   ==  PIDFILE=fileName
                    --  default: ACTDIR='${DGROOT}/act'
                    --  default: TMPDIR=system dependent
                    --  default: PIDFILE='${ACTDIR}/pid/${PORT}'

Information about currently active servers are placed at ACTDIR. Those are temporary files which are made on invocation of a DeleGate server and are removed at its termination.

HOSTS parameter*    ==  HOSTS=nameList[/addrList]
          nameList  ==  name | {name[,name]*}
          addrList  ==  addr | {addr[,addr]*}
                    --  default: HOSTS=localhost/127.0.0.1

List of domain-names/IP-addresses pairs which will override DNS (or NIS or /etc/hosts table) data. This could be used for speed-up of resolution for frequently referred hosts, aliasing, or relief of unknown hosts by any resolvers. Multiple names or addresses could be specified in the form {name1,name2,...}/{addr1,addr2,...}. If only {name1,name2,...} is given without addr part, it makes name1,name2,... be regarded as a single host.

RESOLV parameter    ==  RESOLV=[resolver[,resolver]*]
          resolver  ==  resType[:[resParam][:[queryHostList][:clientHostList]]]
           resType  ==  cache | file | nis | dns | sys
                    --  default: RESOLV=cache,file,nis,dns,sys

Specify which name resolver should be used in what order.

cache	-- means cached result from following resolvers
file	-- means local hosts(5) file usually located at /etc/hosts,
nis	-- means hosts map on NIS or YP(4) service,
dns	-- means DNS service, and
sys	-- means using gethostbyname(2) and gethostbyaddr(2) which usually call system's standard resolver of the host.

If RESOLV is not specified, "sys" is disabled if the IP-address of the host of DeleGate is resolvable by "dns".
If empty value is specified as RESOLV="" then only hosts listed in HOSTS parameter can be resolved (this could be useful when you must hide hosts table for security consideration). Each resolver can be specified with optional argument like follows:

cache:/path	-- path name of cache directory [$TMPDIR/resolvy]
file:/path	-- path name of host-name file [/etc/hosts]
nis:nisDomain	-- NIS domain name [default domain]
dns:dnsHost	-- (a list of) DNS server

DNS Routing: A resolver can be applied to specific queries from specific clients. The optional queryHostList specifies for which hosts or addresses the resolver is applied. The optional clientHostList specifies for which client hosts the resolver is applied.

Example: selecting DNS servers depending on the inquired host/address

RESOLV="cache,dns:{192.168.1.2:8053}:{192.168.*,*.localdomain},dns:192.168.1.1"
// resolve local hosts with DNS sever at 192.168.1.2:8053
// and resolve others with 192.168.1.1:53
// this can be decomposed into a set of parameters like follows:
RESOLV="cache,dns:local-dns:local-hosts,dns:192.168.1.1"
HOSTLIST=local-dns:192.168.1.2:8053
HOSTLIST=local-hosts:192.168.*,*.localdomain


Example: selecting resolvers depending on the inquiring (client) DNS host

RESOLV="file:/etc/hosts:localHosts:192.168.*,dns:xx.xx.xx.xx"
HOSTLIST="localHosts:192.168.*,*.localdomain,*.mydomain"
// queries from local hosts (192.168.*) for "localHosts" are resolved
// with the file "/etc/hosts", others are resolved with the DNS server "xx.xx.xx.xx".

By default, a connection to a host which has multiple IP addresses is tried for each address in the order they are defined in each resolver. A special parameter HOSTS="*/*/RR" can be added to specify "Round Robin" where those IP addresses are tried in round robin order.

RES_WAIT parameter  ==  RES_WAIT=seconds:hostname
                    --  default: RES_WAIT="10:WWW.DeleGate.ORG"

Wait the resolver(s) to be ready before the DeleGate starts the initialization procedure. In the initialization, the result value of host-name resolution can be used as an important configuration parameter like ones for access control. The resolver of the host system may take time to be ready after the system's reboot, and could be unstable typically when the host address is assigned by DHCP. Therefore it might be not yet ready when the DeleGate started.
By default, DeleGate waits for 10 seconds until it can resolve a host name "WWW.DeleGate.ORG" by the given set of resolvers which is specified by the RESOLV parameter. You can specify a more appropriate host name or IP address to be used to detect the readiness of the resolvers. This feature can be disabled with RES_WAIT=0.

RES_CONF parameter  ==  RES_CONF=URL
                    --  default: RES_CONF="file:/etc/resolv.conf"
                        or from registry (on Windows)

Specify where the "resolv.conf" file is. The file is interpreted by the DeleGate original resolver named Resolvy. Resolvy recognizes "nameserver", "domain", "ndots", "search", and "sortlist" in it.

RES_NS parameter    ==  RES_NS=nsList
            nsList  ==  dnsServ[,nsList]
           dnsServ  ==  dnsServer[//socksV5Host] | END.
                    --  default: depend on RES_CONF

Specify a DNS server to be used: dnsServer is a host name or an IP-address of the host name DNS server, which may optionally be followed by port number, like "host:8053" when the port number is not standard port(53). With "dnsServer//socksV5Host", a DNS server beyond a firewall can be referred through the specified Socks V5 server. The Socks server is specified by its IP address with an optional port number like "192.168.1.1:2080".

By default, name servers listed in "resolv.conf" are added to the list of DNS servers to be used. A special dnsServ name ".END" disables to adding such name servers. For example, RES_NS="192.168.1.1,END." means using 192.168.1.1 only regardless of "resolv.conf".

RES_AF parameter    ==  RES_AF=afOrder
            afOrder ==  46 | 64 | 4 | 6
                    --  default: 46

Specify the ordered set of address families (IPv4 or IPv6) of the address of the host to be retrieved. The default value "46" means retrieving IPv4 address first, and if not found, then IPv6 address next.

RES_RR parameter    ==  RES_RR=HostList
                    --  default: RES_RR="*"

Round robin IP-address-list for the hosts included in the HostList. Currently, only RES_RR="*" and RES_RR="" are supported.

RES_VRFY parameter  ==  RES_VRFY=""
                    --  default: none

With "RES_VRFY=", results of reverse look-up of DNS server is verified. When an IPaddress1 is resolved to Hostname, and when the Hostname is resolved to IPaddress-list which does not include the IPaddress1, the verification fail and the result is ignored.

RES_DEBUG parameter ==  RES_DEBUG=number
                    --  default: none

The level of logging for debugging of the built-in resolver.

       ProtoList  ==  [!]protoSpec[,ProtoList]
       protoSpec  ==  protocolName[/[portNumList][/methodList]]

        HostList  ==  [!][-iType]hostSpec[,HostList]
           iType  ==  {h|a|c|*}/[iType]
        hostSpec  ==  [{userList}@]hostSpec[/netMask]
        userList  ==  userNamePattern[,userNamePattern]*
        hostSpec  ==  hostNamePattern | hostAddrPattern
 userNamePattern  ==  [*]uname[*]
 hostNamePattern  ==  [*]hname[*]
 hostAddrPattern  ==  IPaddressPattern | IPrange
         netMask  ==  IPaddress | maskLength

A HostList is a list of hosts (by name or address) to be used for matching to examine whether a certain host is included in the list or not. Each host (hostSpec) is optionally prefixed with a list of users (userList), and optionally followed by a netMask.

TYPE OF IDENTITY

A hostSpec "person@place" represents following identities:

[-h/] [Ident@]peerHost -- peer host's identity (client, server or proxy)

The name or address of the host matches with peerHost, and if Ident@ part is specified, the name of the owner of the connection, detected automatically by the Identification protocol, matches with Ident.

[-a/] authUser@authHost -- authenticated identity

The user of the client is authenticated as authUser (showing the name with an appropriate password) by an authentication server authHost (specified as AUTHORIZER=authHost)

[-c/] person@domain -- certificated identity

The E-mail address of the client's user is given as /Email=person@domain/ in a client's certificate (which is passed over SSL).

Implicitly, A hostSpec like "host" without "user@" part matches only with peer host's identity while "user@host" matches with any kind of identities. By prefixing -iType before hostSpec, identities to be matched can be specified explicitly. for example:

user@host -- matches if at least one of identities is "user@host"
-h/user@host -- matches if peer host's identity is "user@host"
host -- matches if peer host's identity is "host"
-*/host -- matches if at least one of identities is "*@host"
-a/host -- matches if authenticated identity is "*@host"
-a/c/host -- matches if authenticated or certificated identity is "*@host"
-a/* -- matches if authenticated successfully


WILDCARD ( * )

A set of hosts belonging to a domain or a network can be represented as a single hostSpec with wild-card notation. You can prefix or postfix wild-card character "*" to a hostname like "*.com" or "*.delegate.org" or "www.*". As a special case, hostSpec which begins with "*." like "*.domain" matches with "domain" as a hostname as well as ordinary hostnames like "xx.domain" or "yy.xx.domain" (since DeleGate/6.1.18). IP-address range, which may represent a network, can be specified like 192.168.[0-255], 192.168.1.[32-63]. These range can be written as 192.168.0.0/16 and 192.168.1.32/27. In IP-address notation, wild-card character "*" means [0-255], thus "192.168.*" is equals to 192.168.[0-255].

NEGATION ( ! )

If "!" is prefixed to a host, it means that the host is excluded from the list. All of elements in the list are scanned from the first one to the last one. Thus once included (excluded) name may be excluded (included) in succeeding list. For example, for a HostList like follows:

"*.dom,!*.xx.dom,*.yy.xx.dom"

a host named "host.yy.xx.dom" matches with the first hostSpec, but excluded by the second one, but included again by the third one. If the first host in a HostList is with "!", it means exclusion from the universe ("*", that is any host), that is, "!host, ..." is regarded as "*,!host, ..."

NETMASK ( host/mask )

Specifying a netMask, you can check only a part of address, the network address part typically. The netMask can be specified in one of following formats;

/24, /28, ... length of mask bits

/FFFFFF00, /FFFFFFF0, ... hexadecimal notation

/255.255.255.0, /255.255.240.0, ... dot notation

/@A, /@B or /@C ... address class mask.

@A, @B and @C represent /8, /16 and /24 respectively. This notation can be followed by the number of bits for subnets; for example /@B4 means class B network divided into sixteen subnets.

@ ... the default network mask

represents one of /@A, /@B or /@C depending on the class of IP-address of the host to be masked

. ... narrower default network mask

similar to "@" but represents "/24" when it is applied to class-A IP-addresses. For an IPv6 address, the default mask is "ffff_ffff_ffff_ffff__" which represents a mask of 64bits "FFFF:FFFF:FFFF:FFFF::".

USER LIST ( {userList}@host )

For a srcHostList (i.e. HostList concerning client hosts), list of user names (userList) can be prefixed to a host name like {user1,user2,...}@host. The negate symbol "!" have the same meaning with that in a HostList. Note that !user@host is different from {!user}@host; the former excludes user@host, but the latter means {*,!user}@host thus includes *@host except user@host. The special user name "?" matches with users whos names are not IDENTified with identd.

Example: inhibit access from unknown hosts or from unknown users

RELIABLE="{!?,!?@*}"

PORT LIST ( host:{portList} )

For a dstHostList (i.e. HostList concerning server hosts), a list of port numbers (postList) can be postfixed to a host, to make matching by port number as well as host name/address.

Example: conditional filtering using CMAP

CMAP="sslway:FSV:*:{*:{563,636,990,992,995}}:*" which is similar to
CMAP="sslway:FSV:nntps,ldaps,ftps,telnets,pop3s:*:*"

SPECIAL HOST NAMES

There are special host names which are substituted with real host names at runtime.

"."

the host where the DeleGate is running.

"-"

identical to "." if the host has unique IP address (network interface), but if it have multiple IP addresses, it will be the IP address from which the client connected to this DeleGate.

".o"

identical to "." if the host has unique IP address, but if it have multiple network interface, outgoing network interface

".localnet"

represents "localhost,./.,-/.,.o/." by default. It can be redefined by the HOSTLIST parameter as HOSTLIST=.localnet:HostList.

".C" or "-C"

the client host which may be useful to restrict access from a client only to the client (network).

"?"

matches any "unknown hosts" of which name or address is not known by resolvers (listed in RESOLV).

DISABLING NAME RESOLUTION ( -host )

If a hostname (or a IP-address) is prefixed with "-" like "-hostname" ("-192.168.1.1"), then no name resolution (reverse resolution) will be tried for the hostname (IP-address). This will avoid wasting time in resolution trial for a never resolvable hostname (IP-address).

ADDRESS TYPE ( _4. | _6. )

"_4.*" matches any IPv4 addresses while "_6.*" matches any IPv6 addresses. These can be used for routing or access control based on address types.

AGENT CONDITION ( -A/agentNamePattern )

A pseudo host name pattern with prefix "-A/" at the top of it is used to specify the User Agent of the client.

Example:

RELIABLE="-A/Mozilla/4,!-A/MSIE 5" ... which is similar to
RELIABLE=.realmozi4 HOSTLIST=".realmozi4/A:Mozilla/4,!MSIE 5"


TIME CONDITION ( -T.period )

A pseudo host name pattern with prefix "-T." at the top of it is used to specify a time period in a day.


"-T.period" matches if the current time is in the specified time period, where period is represented as "hour1-hour2" which means "from hour1:00:00 to hour2:59:59".


Example:

PERMIT="*:-T.9-16:hostList1" PERMIT="*:-T.17-8:hostList2"
// hostList1 is permitted during office hours whereas
// hostList2 is permitted non-office hours.

The complete format of period is like this: [wW]HH[MM][-HH[MM]]. A time period in a week is represented with "wW" where W expresses a day in a week ranging from "0" to "6" according to Sunday through Saturday. Sunday can be expressed as "7" too for convenience.

Example:

-T.w5-0 // Friday through Sunday
-T.w5-7 // Friday through Sunday
-T.w51730-10830 // from 5:30pm on Friday to 8:30am on Monday

COMPOSITE OPERATORS ( &, |, ! )

As explained above, the meaning of a comma (,) in HostList like "A,B" is not AND nor OR. Operators like AND, OR and NOT operators are provided as a special member of a list.

"&"

AND operator used as "hostList=A,&,B" where when A turn to be false, the hostList as a whole turns to be false without evaluating B. Otherwise B must be true to be true as a whole.

"|"

OR operator used as "hostList=A,|,B" where when A turns to be true, the hostList as a whole turns to be true without evaluating B. Otherwise B must be true to be true as a whole.

"!"

NOT operator used as "A,!,B" where the result of A is negated, and succeed evaluation of B if it exists.

Example:

PERMIT="*:*:-T.9-16,&,hostList1" PERMIT="*:*:-T.17-8,&,hostList2"
// the same meaning with the above example.

There is no format of configuration file with some syntax sugar for DeleGate (yet), but there is a simple recursive substitution mechanism instead, to assemble hierarchical and possibly distributed parts of parameters into a single list of parameters (or options).

Options and parameters can be loaded from external "substitution resources". An option like "+=file" is substituted by a list of options enumerated in the resource named "file". An option like "name=+=file" is substituted by a list of "name=value" where the "value" is enumerated in the "file". Similarly an option like "name=xxx:+=file" is substituted by a list of "name=xxx:value".

A substitution resource can be given in an encrypted format. Encrypted data can be directly represented in the string of format as "+=enc:ext::XXXX:" in which the part of XXXX contains the encrypted data. This format of data is created with "-Fenc" option of DeleGate. When it is named with the suffix ".cdh" as "+=conf.cdh", it is decrypted by "Credhy" using the passphrase for decryption which is specified as the password of the "config" user.

Substitution can be done recursively. In this case, a relative resource name is searched in DGPATH or LIBPATH. By default, DGPATH='+:.:${HOME}/delegate' where "+" stands for the place where the "caller" resource is. For example, if "+=file2" is referred from caller file "/local/etc/file1", the "file2" will be searched first as "/local/etc/file2". A resource name can be specified in full URL like "+={file:/local/etc/file1}" or "+={http://host/file}".

       paramRef ==  +=[URL][?label,[label]*]

      paramList ==  line
                    line
                    ...

  paramListPart ==  CASE label
                         paramList
                    ESAC

Substitution resources are the list of options (or parameters) where each line stands for an option (or a parameter). In each line, strings after sharp character(#) will be ignored as a comment. White space characters (SPACE, TAB, LF and CR) at the beginning or the ending of each line are ignored. Single quote(') and double quote(") are stripped. Back slash character(\) let the succeeding character be as is.

Example: The following five examples have the same meaning with each other.

PERMIT=a:b:c PERMIT=a:b:d PERMIT=a:e:f PERMIT=x:y:z ...

+=parameters

[content of parameters]

PERMIT=a:b:c
PERMIT=a:b:d
PERMIT=a:e:f
PERMIT=x:y:z
...


PERMIT=+=permits

[content of permits]

a:b:c
a:b:d
a:e:f
x:y:z
...

PERMIT=a:b:+=abclients PERMIT=+=others

[content of abclients]

c
d


[content of others]


a:e:f
x:y:z
...

PERMIT=+=permits


[content of permits]


PERMIT=a:b:+=?abclients


PERMIT=+=?others


CASE abclients


c
d


ESAC


CASE others


a:e:f
x:y:z
...


ESAC





Substitution resources will be reloaded when the DeleGate restart receiving a SIGHUP signal or by "-restart" action in CRON parameter.

Another substitution is in the form "name=-=URL" which loads the content of URL into a temporary file on local file system (under ACTDIR), then the parameter is rewritten to "name=/path/of/temporary-file". This will be useful when you wish to pass remote resources to CGI or CFI programs, like "-eCONFIGDATA=-=http://server/configData", then those programs will be given an environment variable named CONFIGDATA of which value is a temporary file name containing the content of "http://server/configData".

CFI AND CFI SCRIPT

Communication between client and DeleGate or between DeleGate and server can be filtered or translated by user defined filter programs attached to DeleGate using a simple scheme named CFI (Common Filter Interface). Existing filter programs, from standard input to standard output, can be used as a CFI program without modification. The usage of CFI is controlled by parameters like following:

filterName="filterSpec"
CMAP="filterSpec":filterName:connMap

  filterName  ==  FCL | FTOCL | FFROMCL |
                  FSV | FTOSV | FFROMSV |
                  FMD | FTOMD | FFROMMD 
  filterSpec  ==  filterCommand | CFIscriptName
                  | tcprelay://host:port

filterName is named as FXX, FTOXX and FFROMXX where XX is one of CL (client), SV (server) and MD (MASTER-DeleGate). Filter commands for FXX are bidirectional filter given file descriptor 0 bound for the client, and file descriptor 1 bound for the DeleGate. Filters commands for FTOXX and FFROMXX getting input from standard input and put output to standard output which is bound for XX. A unidirectional filter at a remote host can be used by connecting it on TCP by "tcprelay://host:port"

A filter can be applied conditionally based on circuit level information, using CMAP parameter like follows:

CMAP=filterSpec:filterName:ProtoList:dstHostList:srcHostList
For example, CMAP="sslway:FSV:telnet:hostA:*" means applying SSLway filter only when connecting to the Telnet server at hostA.

For FTOXX and FFROMXX filters, CFI script enables selecting an appropriate filter to be applied to each data depending on the type of data. Instead of direct usage of a filter program like FTOCL=filterCommand, specify FTOCL=filter.cfi where filter.cfi is a file in the CFI script format. Or a CFI script can be loaded from remote host like FTOCL=URL via HTTP or FTP. When the file name of CFI scripts or a filter command referred in the script is specified in relative path name, it is searched in LIBPATH.

CFI script

The CFI script is a simple script to select an appropriate filter to be applied to a message data relayed on DeleGate, depending on the type of data, the server name, the type of client, and so on. A CFI script is text data which starts with a magic string "#!cfi" and contains more than one filter specifications which are separated by "--" with each other.

  CFI script   == "!#cfi" NL filterUnit [ "--" NL filterUnit ]*
  filterUnit   == filterRule [ filterRule ]*
  filterRule   == matchingRule | rewriteRule | filterSpec
  matchingRule == matchingName ":" ruleBody
  matchingName == MIMEheader | X-header | CGIENV
  MIMEheader   == "Content-Type" | "User-Agent" | ...
  X-header     == "X-Status-Ver" | "X-Status-Code"
                | "X-Request-Method" | "X-Request-Ver"| "X-Request-URL" | ...
  CGIENV       == "REQUEST_METHOD" | "SERVER_PROTOCOL" | "SERVER_NAME"
                | "PATH_INFO" | "PATH_TRANSLATED" | "HTTP_USER_AGENT" | ...
  rewriteRule  == Action "/" MIMEheader : ruleBody
  Action       == "Output" | "Remove"
  filterSpec   == filterType ":" ruleBody
  filterType   == "Body-Filter" | "CGI" | "Header-Filter"
                | "MIME-Filter" | "Message-Filter"
  ruleBody     == string NL [ SP  string NL ]*

Input Format:
The input data to CFI script is a message of application protocol in MIME format preceded with a request or a response status line of the application protocol (HTTP, SMTP, POP, NNTP). A MIME message is composed with a header and a body separated with an empty line.

  CFIinputMessage == statusLine MIMEheader NL MIMEbody

Example: a simple HTTP response message

HTTP/1.0 200 OK           ... response status line
Content-Type: text/html   ... header
Content-Length: 20        ... header
                          ... header/body separator
body of the message       ... body

Matching Rule:
A matchingRule indicates matching the ruleName:ruleBody to the input header. It matches when the input message has a ruleName header with a field body matches with ruleBody. If at least one of matching rules turns to be true, then the filterUnit is adopted. If no matching rule is included in a filterUnit then the filterUnit is adopted unconditionally. Currently, only a limited set of MIME headers (in request or response message) can be used for the matching. Also, some extended headers can be used to match with information not included in the original header (ex. "X-Status-Code" which means status code in response message). Matching with CGI environment variables.

Example: a matching rule

#!cfi
HTTP_USER_AGENT: MSIE
SERVER_HOST: www1.dom1
SERVER_HOST: www2.dom2
X-Status-Code: 200
Content-Type: text/html
Content-Type: text/plain
Body-Filter: ...


Rewriting Rule:
A rewriteRule with a prefix "Action/" to a ruleName:ruleBody specifies some simple rewriting using ruleBody data for relevant ruleName field. "Output/ruleName:ruleBody" indicates appending (or replacing) a ruleName:ruleBody field into the header. "Remove/ruleName:ruleBody" indicates removing header fields with name ruleName and body matches to ruleBody.

Filter Specification:
A filterSpec specifies a filter to be applied to the input data. The whole or a part of input message will be passed to the standard input of the filter program, then the output from the standard output of it will be forwarded to the destination (client or server) instead of the original input message.

  Body-Filter:    filter for MIMEbody
  CGI:            filter for MIMEbody
  Header-Filter:  filter for MIMEheader
  MIME-Filter:    filter for MIMEheader + MIMEbody
  Message-Filter: filter for statusLine + MIMEheader + MIMEbody

For filters of any type, the set of CGI environment variables is passed. In addition, CFI origin environments variables are passed including "SERVER_HOST" (the name of the destination server), "REQUEST_URL" (the URL of the request).

For filters of "Body-Filter" or "CGI", the "Content-Length" header in the forwarded message will be adjusted to indicate the size of the body part after the filtering. The output of "CGI" filter must preceded with the status header of CGI output.

For filters of "Header-Filter", the header part of a message will be passed to and from the filter. The start-line in the HTTP message (Request-Line or Status-Line) will be passed as a header field prefixed with "Request-Line:" or "Status-Line:".

For filters of "MIME-Filter", the whole of the MIME message consists of a header and a body is passed to and from the filter.

For filters of "Message-Filter", the whole message of the application protocol is passed to and from the filter where each message consists of a MIME message prefixed with a line representing request or response status in the application protocol.

Example: rewriting HTTP response messages

SERVER=http FTOCL=test.cfi

[content of test.cfi]
#!cfi
Content-Type: text/html
Body-Filter: sed 's/string1/string2/'
--
Content-Type: image/gif
Output/Content-Type: image/jpeg
Body-Filter: gif2jpeg


Example: dump available headers and environment variables

#!cfi
Header-Filter: -tee-n-v /dev/tty
Body-Filter: env|sort > /dev/tty; cat

PROXYING BY URL REDIRECTION

DeleGate with RELAY="delegate" provides a special proxying without changing "proxy configuration" in browsers. When the URL of such DeleGate is http://delegate/, a user can access target URL via the DeleGate by giving a URL like http://delegate/-_-URL to the browser. A request message for the URL from the client will be in form of /-_-URL which is regarded as a request for URL by DeleGate. Then the DeleGate rewrites a URL included in a response messages to client so that the access to the URL is directed to the DeleGate again. This redirection is achieved by prefixing the URL of DeleGate (http://delegate/) and "-_-" sign before original URL like http://delegate/-_-URL.
U->C: user opens http://delegate/-_-http://www/path1
C->D: GET /-_-http://www/path1
D->S: GET /path1
D<-S: HREF=/path2
C<-D: HREF=http://delegate/-_-http://www/path2
U->C: user clicks the anchor
C->D: GET /-_-http://www/path2
D->S: GET /path2
S->D: HREF=ftp://ftp/path
D->C: HREF=http://delegate/-_-ftp://ftp/path


Originally, this redirection mechanism was implemented for Gopher proxy, and extended to HTTP protocol, then extended to a generic MOUNT mechanism. Now almost the same effect with "-_-" redirection can be emulated with a MOUNT parameter like follows, allowing to replace "-_-" with an arbitrary string.

MOUNT="/-_-* *"

You can write a DeleGate switching table in HTML. Suppose that you have two DeleGate hosts connected to different network provider each other, and you want to select one of them explicitly but without changing configuration of your browser and without typing a lengthy URL prefixed with "http://delegate/-_-". You can write a table in HTML to switch DeleGate like this:

<A HREF="http://proxy1:8080/-_-http://www.w3.org/"> W3C via firewall1 </A>
<A HREF="http://proxy2:8080/-_-http://www.w3.org/"> W3C via firewall2 </A>

This table works independently of if the client is using DeleGate or not, because DeleGate does not do URL redirection in response message described above if the URL is already redirected like above.

Right after the -_- mark, optional "/Modifier/" form can be inserted as follows:

http://delegate/-_-/Modifier/URL
Modifier can be a list of multiple Modifiers separated each other by by comma (,) character.

cc.outCode[.inCode]

the character code of text data toward the client, "cc.JIS" for example.

Fflags

flags is a list of flag characters "C" to disable cache, "N" to force using not name but address overriding DELEGATE parameter, "J" to make JIS (ISO-2022-JP) output overriding CHARCODE parameter, and so on.

DeleGate with a SERVER=tcprelay parameter relays communication between a client and a server on a single TCP connection without interpreting what is transmitted on it. Thus an arbitrary application protocol on TCP, even if it is not in supported protocol list of DeleGate, can be relayed by SERVER=tcprelay. But value added services, including caching, mounting and logging, are not available in this case. Connecting to arbitrary destination servers depending on a request from a client is not possible. Application protocols which dynamically create other connections besides the main connection, like FTP, are not relayable. Application protocols which exchange some kind of name depends on an origin server on the protocol, like a full URL in HTTP, are not relayable too.

Example: two proxies on TCP with similar function

# delegated -P25 SERVER=smtp://mailserver
# delegated -P25 SERVER=tcprelay://mailserver:25

DeleGate with a SERVER=udprelay parameter relays communication between a server and clients on UDP without interpreting what is transmitted on it. It has similar merits/demerits to tcprelay for TCP. Also application protocols on which routing information are exchanged, like CU-SeeMe, are not relayable with udprelay.

Example: two proxies on UDP with similar function

# delegated -P53 SERVER=dns://nameserver
# delegated -P53 SERVER=udprelay://nameserver:53

Example: a gateway between UDP and TCP

// UDP clients and a TCP server
# delegated -P53 SERVER=udprelay://nameserver:53 CONNECT=tcp
// TCP clients and a UDP server
# delegated -P53/tcp SERVER=udprelay://nameserver:53


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 by DeleGate provides Digest Authentication functionality remotely, over an experimental "DGAuth" protocol.

Example: DGAuth-DeleGate server and its client

hostS% delegated SERVER=dgauth -P8787
hostC% delegated SERVER=http -P8080 AUTHORIZER=-dgauth//hostS..8787

Example: DGAuth-DeleGate server and its client on the same host

hostX% delegated SERVER=dgauth
hostX% delegated SERVER=http -P8080 AUTHORIZER=-dgauth

A DGAuth server receives a set of components to be used to calculate digest for each application protocol, then return the digest, as follows.

Request:

HTTP user nonce realm method uri
APOP user nonce [realm] (not used currently)


Response:

200 digest
501 syntax error
502 unknown user

PAM server

PAM server by DeleGate provides PAM (Pluggable Authentication Modules) functionality remotely, over an experimental protocol compatible with HTTP (PAM/HTTP).

Example: PAM-DeleGate server and its client

hostX% delegated -P8686 SERVER=httpam
hostY% delegated -P8023 SERVER=telnet AUTHORIZER=-pam//hostX/passwd

Example: PAM-DeleGate server and its client communicating over SSL

delegated hostX% -P8686 SERVER=httpam FCL=sslway
delegated hostY% -P8023 SERVER=telnet AUTHORIZER=-pam//hostX/passwd CMAP=sslway:FSV:pam

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 server


The 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" is a HTTP server which can be used for tunneling the FTP protocol over HTTP by a (connectionless) sequence of usual HTTP requests (not by CONNECT but by GET and POST). It can be relayed by another HTTP proxy for forwarding, filtering or so.

Example:

hostX% delegated -P8021 SERVER=ftp MOUNT="/* ftpxhttp://hostY:8080/*"
hostY% delegated -P8080 SERVER=ftpxhttp MOUNT="/* ftp://hostZ/*"
client --FTP-- ftp://hostX:8021 --HTTP-- http://hostY:8080 --FTP-- ftp://hostZ

The yysh server provides remote login and remote command execution based on the YYSH and YYMUX protocol.

Example:

hostX% delegated -P6023 SERVER=yysh
hostY% delegated -Fyysh hostX:6023

YYMUX server

Example:
hostX% delegated -P6010 SERVER=yymux
hostY% delegated -P8080 SERVER=http YYMUX=hostX:6010

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.

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:

acc -- accept a SockMux connection at "host:port".
con -- connect a SockMux connection to "host:port".
ssl -- use SSL instead of the "Credhy" encryption.

Example: SOCKS proxies chained over SockMux

hostA% delegated SOCKMUX=hostA:8000:acc SERVER=socks -P2080
hostB% delegated SOCKMUX=hostA:8000:con SERVER=socks -P1080 SOCKS=hostA:8000


Example: SOCKS proxies chained over SockMux connected from the server side

hostA% delegated SOCKMUX=hostB:8000:con SERVER=socks -P2080
hostB% delegated SOCKMUX=hostB:8000:acc SERVER=socks -P1080 SOCKS=hostA:8000


Example: HTTP proxies chained over SockMux

hostA% delegated SOCKMUX=hostA:8000:acc SERVER=http -P9080
hostB% delegated SOCKMUX=hostA:8000:con SERVER=http -P8080 PROXY=hostA:8000


Example: HTTP via SOCKS proxy chained over SockMux

hostA% delegated SOCKMUX=hostA:8000:acc SERVER=socks -P2080
hostB% delegated SOCKMUX=hostA:8000:con SERVER=http -P8080 SOCKS=hostA:8000

SOXCONF parameter*  ==  SOXCONF=confSpec[,confSpec]*
                    --  default: none

crypt:no

disable the encryption of SockMux packets.

packsize:SIZE [16k]

specify the size of a SockMux packet, 128 in minimum and 16k at the maximum.

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.

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

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"


Example: uni-directional SockMux-DeleGate

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

Example: uni-directional to proxy-Telent-DeleGate

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.

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:

DEST=host:port[:srcHostList] for SERVER=tcprelay://host:port,-in[:-:srcHostList]
DEST=host:port/udp[:srcHostList] for SERVER=udprelay://host:port,-in[:-:srcHostList]

Example: tcprelay over SockMux

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.

Example: relaying UDP over SockMux/TCP

hostX% delegated SERVER=sockmux://hostY:9000 PORT=hostX:53/udp
hostY% delegated SERVER=sockmux -PhostY:9000 DEST=hostU:53/udp
// hostX:53/udp is forwarded to the server at hostU:53/udp via hostY.

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

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


Example: use communication port between two hosts (not tested yet)

host1) SERVER=sockmux:comm@com1 ...
host2) SERVER=sockmux:comm@com2 ...


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

% SERVER="sockmux:proc@connectCommand" ...


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

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


NOTE: forwarding FTP data connection is not supported (yet).

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.

CAPSKEY parameter*  ==  CAPSKEY=opaque
                    --  default: none

Some functionalities of DeleGate are disabled by default and need CAPSKEY to be enabled. You can get automatically issued CAPSKEY for evaluation use via mail. Run DeleGate as "delegated -Fcapsreq ADMIN=Email-address" and follow the instruction shown in the output.

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.

Example: Socks-DeleGate

# delegated -P1080 SERVER=socks
Example: forwarding to an upstream Socks server
# delegated -P1080 SERVER=socks SOCKS=sockhost

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.

• SRCIF="host:port:socks-udp-tosv" -- network interface to servers
  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="host:port:socks-udp-tocl" -- network interface to clients
  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: Socks-DeleGate which do caching for HTTP and FTP

% delegated -P1080 SERVER=socks CACHE=do SOCKSTAP=http,ftp

Example: Socks-DeleGate which do caching for HTTP with an upstream proxy

% delegated -P1080 SERVER=socks SOCKSTAP="http:::CACHE=do PROXY=pxserv:8080"

See http://www.delegate.org/delegate/sockstap/> for more details.

HTTP proxy/server

Example: DeleGate as an HTTP proxy
firewall% delegated -P8080 SERVER=http

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

firewall% delegated -P8888 SERVER=delegate RELIABLE=internal
internal% delegated -P8080 SERVER=http MASTER=firewall:8888


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

host# delegated -P80 SERVER=http \

MOUNT="/* /path/of/www/*" RELAY=no RELIABLE="*"

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:
MOUNT="/xxx/* cgi:/path/of/cgi-bin/*"

Example: DeleGate as a CGI program

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


delegated -Fcgi

MOUNT="/-* =" \
MOUNT="/www2/* http://wwwserv2/*" \
MOUNT="/news/* nntp://newsserv/*"


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

HTTP Transfer Log Format

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=":%X %D" in version 10 while it was PROTOLOG=":%C %D" in version 9.

%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 client information part in %C, which records hostname, Ident, and username by default, can be modified by AUTH="log:" parameter.

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:

time.pid.proc#+conn#[+req#].reqnum

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:

11/14 17:30:45 [1234] 5+6/7: NewSession 031114-173045.1234.5+6+7.0

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

welcome:listOfWelcomeFiles

-- default: welcome.{dgp,shtml,html,cgi},index.{dgp,shtml,html,cgi},-dir.html
A list of index files or CGI scripts which should be used for URLs of directories ending with "/" like "/path/". This is a list of candidate file names. The list may be ended with "-dir.html" which means a built-in index generator. If the list is empty, empty data is substituted for index data.

search:pathOfSearchScript

-- default: none
The path of a CGI script to be applied for URLs with search part like "/path?search". This is a global specification applied for all URLs. Also you can specify a local search script for each MOUNT point like

MOUNT="/path2/* /root/of/path2/* search:script2".

This local specification is prior to the global one. A special local specification "search:-" can be used just to ignore the global specification for the MOUNT point.

nvserv:noauto | auto | alias | gen | none

-- default: HTTPCONF=nvserv:noauto
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.

methods:listOfAcceptableMethods

-- default: methods:OPTIONS,GET,HEAD,POST,PUT,...
-- See the output to LOGFILE with HTTPCONF=methods:"+"
Limit or add HTTP methods to be accepted.


Example:

HTTPCONF=methods:GET,HEAD -- accept only GET and HEAD
HTTPCONF=methods:-POST,-PUT -- don't accept POST and PUT
HTTPCONF=methods:+,NEWMETHOD1 -- add NEWMETHOD1 to be accepted
HTTPCONF=methods:* -- accept any methods


rvers:listOfAcceptableResponseVersions

-- default: rvers:HTTP
Add versions in response message from HTTP servers.

Example:

HTTPCONF=rvers:+,ICY
HTTPCONF=rvers:* -- accept any response version

post-ccx-type:listOfTypes

-- default: post-ccx-type:x-www-form-urlencoded
Specify the list of names of Content-Type of request message to which conversion by CHARCODE is applied.

Example:

HTTPCONF=post-ccx-type:+,multipart/form-data

cryptCookie:listOfCookies:cryptKey


listOfCookies == attributes[@domains]
attributes == attribute | {attribute,attribute,...}
domains == domain | {domain,domain,...}
domain == [.]domainName
cryptKey == string | %a | %P

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:

HTTPCONF="cryptCookie:SessionID@host1.dom1,UserID@.dom2:nanjamonja"
HTTPCONF="cryptCookie:UserID@.dom:nanjamonja"
HTTPCONF="cryptCookie:UserID@{host1.dom,host2.dom}:nanjamonja"


kill-[i][qr]head: listOfHeaders

erase header fields listed in listOfHeaders before forwarding a request/response message to server/client. "kill-qhead" is applied only to request message to server and "kill-rhead" is applied only to response message to client. If "i" is prefixed as "kill-iqhead:Pragma,Cache-Control", the specified fields are erased before DeleGate interpret it as the HTTP headers.

Example:

HTTPCONF=kill-qhead:Referer
HTTPCONF=kill-qhead:If-*,Accept-*
HTTPCONF=kill-rhead:Set-Cookie


add-[i][qr]head:name:body

add a header name:body to forwarded request/response message. Client's identity information can be inserted into body string with "%format" notation. If "i" is prefixed as "add-ihead:Pragma:no-cache", then the specified field with the body is added to the input to be interpreted by DeleGate as a HTTP header from the client or the server.

Example:

HTTPCONF="add-qhead:X-Forward-For:%a"


replace-[i][qr]head:name:body

replace headers of "name:" with "name:body" in forwarded request/response message. This is equivalent to the combination of kill-head and add-head.

Example:

HTTPCONF=replace-qhead:Referer:http://x.y.z
HTTPCONF=kill-qhead:Referer HTTPCONF=add-qhead:Referer:http://x.y.z

kill-tag: listOfTags

disable a tag listed in listOfTags when it it used in a text/html response from a server.

Example:

HTTPCONF=kill-tag:SCRIPT,APPLET


ver:1.0

act as a HTTP/1.0 client/server

svver:1.0

act as a HTTP/1.0 client against servers (send request in HTTP/1.0)

clver:1.0

act as a HTTP/1.0 server against clients (do not use chunked encoding in response)

acc-encoding:encoding [-thrugzip]

Accept-Encoding header to be sent to server. This is applied to DeleGate which does some interpretation of content with MOUNT, CHARCODE, CACHE, etc. To do such interpretation, the content (response body) is not to be encoded in a format unknown to DeleGate. "identity" specifies disabling any encoding of content in the server. "-thrugzip" specifies forwarding Accept-Encoding:gzip from client to server. If the program "gzip" is not available on the host of DeleGate (i.e. not found in LIBPATH), "identity" is sent regardlessly.

gen-encoding:encoding [gzip]

The encoding applied to the content sent from DeleGate to client. Only "gzip" is available in the current implementations. "identity" and others disable any encoding.

tout-wait-reqbody:period [30]

max. period to wait the first data in request body.

tout-in-reqbody:period [15]

max. period to wait next data in request body. (adjustable for a slow filter program at the client side)

tout-buff-reqbody:period [5]

max. period to do buffering request message to server

tout-buff-resbody:period [8]

max. period to do buffering response message to client

tout-cka:period [5]

max. period to keep a connection with the client alive. (the timeout is ten times longer for the first connection from each client host)

max-cka:number [50]

max. number of requests to be relayed on a single connection in keep-alive. (ten times larger value is given to the first connection from each client host)
This is applied to the communication over a connection of SSLtunnel by the CONNECT method too. A pair of upstream and downstream data is regarded as a pair of request and response on HTTP, then the maximum number of such pairs is restricted.

max-ckapch:number [8]

max. number of connections in keep-alive at a time for each client host.

max-reqline:length [8k]

max. length of request line to be accepted.

max-reqhead:length [12k]

max. length of request header to be accepted.

max-gw-reqline:length [512]

max. length of request line to be forwarded to another server in another protocol.

max-hops:number [20]

max. number of hops in the chain of HTTP proxies.

tout-resp:period [TIMEOUT=io]

max. period to wait response from server.

tout-pack-intvl

[10.0]

max. interval between packets relayed on SSLtunnel by the CONNECT method.

halfdup

Forbid full-duplex usage of SSLtunnel by the CONNECT method.

urlesc[:escChars] [empty]

the set of characters in request URL to be escaped by "%XX" notation before any processing. As a special case, HTTPCONF="urlesc" means HTTPCONF="urlesc:<>".

mypro.xyz:{forw,thru,stop}

By default, an access to the virtual domain name "http://mypro.xyz" is interpreted as an access to your proxy server. HTTPCONF="mypro.xyz:forw" enables forwarding the request to upstream proxies by prefixing the hop count. HTTPCONF="mypro.xyz:thru" disables this interpretation and forward the request to the upstream proxy if exists. HTTPCONF="mypro.xyz:stop" stops this interpretation and forwarding at all. Another way for restriction of access to mypro.xyz is using AUTHORIZER as AUTHORIZER="-list{User:Pass}:*:*.mypro.xyz:*".

proxycontrol[:{on|off}]

consume substring following "?_?" in request URL as control information for the DeleGate; when DeleGate get request URL?_?proxycontrol, only URL part is forwarded to the server and proxycontrol part is (possibly) used by DeleGate.

cka-cfi

make connection with the client keep-alive even with external filter (FCL, FTOCL).

nolog:listOfCodeType[:connMap]

listOfCodeType == [ respCode / ][ Type [ / subType ] ]
specify response code or Content-Type of response message not to be logged in access log (PROTOLOG).

Example:

HTTPCONF="nolog:302,304,image"


xferlog:ftp

record FTP/HTTP transactions in xferlog format too.

bugs:listOfBugs

listOfBugs is a list of features to be disabled to bypass possible bugs as follows:

no-gzip ... disable Content-Encoding:gzip

no-keepalive ... disable Connection:Keep-Alive

no-keepaliveproxy ... disable Connection:Keep-Alive with client side proxy

no-chunked ... disable Transfer-Encoding:chunked

no-flush-chunk ... disable flushing response after each chunk

kill-contleng ... erase original Content-Length in chunked encoding

add-contleng ... add or update Content-Length even in chunked encoding

do-authconv ... enable Authentication conversion from client's Basic to server's Digest

bugs:thru-304

disable the conversion from "304 Not Modified" to "200 Ok" in the message as the response to a conditional request with the "If-Modified-Since" header. DeleGate with external filters tries to return a HTTP response messages with a body (with the code "200 Ok") when it is filtered (and possibly rewritten) by the filters even if the body should be returned as empty (304 Not Modified) based on the modification date (Last-Modified) of the target data. This is necessary to return data rewritten dynamically by filters, but it disables the merit by the conditional request and the "304" response. "thru-304" turns the above conversion off and let DeleGate pass through "If-Modified-Since" request from clients and the "Last-Modified" and "304 Not Modified" response from servers.

svauth:no-basic

Stop forwarding Basic Authorization (which contains cleartext password) from client to server. If the server supports Digest authentication, then the DeleGate do it by proxy of the client.

svauth:less-basic

Postpone forwarding Basic Authorization from client to server until the server requires the Basic Authentication.

session:cookie

Enable session management based on Cookie. The session identifier is passed to CFI/CGI programs in environment variable "X_COOKIE_SESSION", and can be logged into PROTOLOG.

Example:

HTTPCONF=session PROTOLOG=":%s %X"

Example:

HTTPCONF=search:/path/of/searchScript
MOUNT="/bin/* cgi:/path/of/cgi-bin/* search:-"
MOUNT="/* file:/path/of/data/*"

FILETYPE parameter  ==  FILETYPE=suffix:gopherType:altText:iconName:contentType
                    --  default: FILETYPE=".txt:0:TXT:text:text/plain"
                                 FILETYPE=...

Define file name to content-type mapping.

gopherType:

0 - text, 1 - directory, 4 - BinHex, 6 - uuencode, 9 - binary, g - gif, I - image, ...

altText:

alternative text which should be displayed for the icon image in text only displays (embedded into IMG tag in HTML text like <IMG ALT="altText" ... >)

iconName:

one of binary, binhex, compressed, directory, document, ftp, gzip, image, index, index2, movie, sound, tar, telnet, text, unknown, uu (see http://delegate/-/builtin/icons/)

contentType:

text/plain, image/gif, ... (see RFC2045)

Example:

FILETYPE=".txt:0:TXT:text:text/plain"
FILETYPE=".gif:g:GIF:image:image/gif"

CGIENV parameter    ==  CGIENV=name[,name]*
                    --  default: CGIENV="*"

A list of environment variables to be passed to CGI program.

MountOptions for HTTP-DeleGate

CONDITIONS:

vhost={HostList} -- virtual host matching and rewriting.

true if the value of the "Host:" field in the request message is included in the HostList for request rewriting, and true unconditionally for response rewriting. It supports virtual hosting by a special rewriting for response, that is, any full-URL of a real host in a response message will be rewritten to that of a virtual host.

avhost={HostList} -- address based virtual hosting

equivalent to the "vhost" option.

nvhost={HostList} -- name based virtual hosting

similarly to "vhost" option, "nvhost" is used to configure virtual hosting except that this option is restricted to create name based virtual hosts which are distinguished each other only by their host names. Each virtual host is identified textually by its name (thus no "-" prefix for each host is necessary to force textual-only matching which is necessary with the "vhost" option). For example, the following two MOUNT parameters are equivalent to each other.
 MOUNT="/* http://server/* vhost=-www.domain"
 MOUNT="/* http://server/* nvhost=www.domain"
A special option "nvhost=-thru" can be used to ease forwarding a virtual domain name indicated by a client to a server. The option means matching with virtual domain name to be sent to the target server. By default, the domain name can be specified explicitly with the nvserv or the target server name in the rURL of this MOUNT rule by default. For example, the following three MOUNT parameters are equivalent mutually.
 MOUNT="/* http://domain/* nvhost=-thru,rserv=server"
 MOUNT="/* http://server/* nvhost=-thru,nvserv=domain"
 MOUNT="/* http://server/* nvhost=domain,nvserv=-thru"


qmatch=pattern -- pattern matching in the request header

true if the pattern matches with string in the request header. (ex. qmatch=*User-Agent:*compatible;%20MS*)

dstproto={ProtoList} -- to the server of specified protocol

true if the protocol of the destination server is in the ProtoList.

method={methodList} -- request method

true if the access method of the current request is included in the methodList.

asproxy

true if the DeleGate is called as a proxy server that is the requested URL is in full URL format.

!asproxy

true if the DeleGate is not accessed as a proxy server in the request.

withquery

true if the requested URL has "?query" component

CONTROLS:

authorizer=authServList

the AUTHORIZER which is to be applied to this MOUNT point. If AUTHORIZER is specified in both MountOption and command line option, the one in MountOption is used.

moved[={300|301|302|303}]

don't relay to rURL but return response for redirection as "302 Moved" with "Location:rURL". Redirection within the same server can be eased using the abbreviation of host-name in the rURL like MOUNT="/path1 ///path2 moved".

referer

Apply the rewriting only to the Referer: field to be forwarded. This is an synonym of "where=ref".

useproxy[=proxyURI]

generate "305 Use Proxy" response message. If proxyURI is omitted or given as "direct", the response message is sent with Set-Proxy field as "Set-Proxy: DIRECT". Otherwise the URI is set in the field as "Set-Proxy: SET; proxyURI=proxyURI".

realm=realmString

specify the realm of authentication.

forbidden

reject the request as forbidden (synonym of "rcode=403")

unknown

reject the request as unknown (synonym of "rcode=404")

rcode={300|301|302|303|304|305|306|403|404}

return the response with the specified status code, which can be useful for customizing error messages.

onerror[=listOfCodes]

this MOUNT entry is used to substitute a response message when an error occurred. It is applied If the response status code for the request shows an error (4xx or 5xx), and the status code is in the listOfCodes if it is specified. For example with MOUNT="/path/* file:/tmp/autherr.cgi onerror={401,407}", the output from /tmp/autherr.cgi is sent when authentication error occurred in access to URLs under "/path/".

robots={no|ok}

allow or disallow retrievals from robots. The default value for NNTP and FTP is "no", while it is "ok" for other protocols.

nvserv | nvserv=host -- forwarding to a name based virtual server

specify MOUNTing the target server as a name based virtual hosting server. The virtual host name to be sent to the server can be specified as "nvserv=host" or it is the host name part in the rURL by default. With this option, the target server is MOUNTed only as a virtual server of the host name while other servers, of alias names of the host or IP-addresses of the host, are not MOUNTed. This means that the MOUNT rule will be applied for rewriting of URL in a HTTP response message only if the hostname of a URL matches textually with the virtual host name of the target server. The virtual hostname from the client can be passed through to the server with "nvserv=-thru".

avserv | avserv=host -- forwarding to an IP-address based virtual server

notate that the target server is not a name based virtual hosting server. With this option, all of servers of alias names or IP-addresses of the target server are MOUNTed by this MOUNT rule. It has been the default behavior of MOUNT but it can be changed with the option HTTPCONF="nvserv:auto" to automatically detect virtual servers in a set of MOUNT parameters. This "avserv" option could become necessary to notate a non-virtual server which is automatically guessed as a virtual server.

rserv=host[:port] -- real target server

specify the real host name or IP-address and port number of the target server toward which the HTTP connection is established. This option is used to do MOUNT a virtual hosting server of which virtual host name is specified in the rURL rather than in the "nvserv=host" option. For example, the following two MOUNT rules are equivalent to each other.
 MOUNT="/v/* http://www.domain/* rserv=192.168.1.123"
 MOUNT="/v/* http://192.168.1.123/* nvserv=www.domain"
Specifying the "rserv" option implies that the target server is a virtual server as if notated with the "nvserv" option.

genvhost=host (obsoleted by nvserv and rserv options)

Specify the hostname which will be received by the target server as its virtual hostname. It is set in the "Host: host" field in the request message to be forwarded to the server. When the request is to be forwarded via a HTTP proxy, it is set in the request URL as http://host/... The default Host field sent to the server is derived from the rURL part of the MOUNT parameter which specifies the target server. For example for MOUNT="/* http://hosti:8080/*", "Host: hosti:8080" will be forwarded to the server (which is running at the port hosti:8080). To through pass the Host field in the request from a client to the server, specify as "genvhost=-thru".

ftosv=-cc-charCode

convert charset in HTTP header forwarded to server into charCode (jis|sjis|euc|utf8)

pathext=string

when DeleGate as an origin HTTP server searches a file for requested URL, the path name extended with the specified string is retrieved first. For example with "pathext=-ja", "index-ja.html" is retrieved prior to "index.html". It can be useful in combination with other MOUNT conditions, like MOUNT="/* file:data/www/* nvhost=www.delegate.jp,pathext=-ja"

Example: virtual hosting, acting as multiple HTTP servers

The target server or local directory is switched by with which name the DeleGate is referred (in the "Host:vhost" header field). In this example, requests for "http://dom1.com" and "http://dom2.org" are forwarded to each corresponding server, while requests for "http://dom3.net" or any other name are retrieved in each corresponding local directory.

MOUNT="/* http://wwwA/* nvhost=dom1.com"
MOUNT="/* http://wwwB/* nvhost=dom2.org"
MOUNT="/* file:data/wwwC/* nvhost=dom3.net"
MOUNT="/* file:data/www/*"


Example:

"useproxy", "method", "dst" and "withquery" options are introduced originally to refuse potentially troublesome accesses which may invoke CGI programs in target servers. For example, to refuse any request with POST method, or with URL including "?":

MOUNT="http:* = method=POST,asproxy,useproxy"
MOUNT="http:* = withquery,asproxy,useproxy"

AUTH parameters for HTTP-DeleGate

AUTH=origin:auth

-- default: AUTH=origin:ident
Like AUTH=proxy, specify using the value in "Authorization" field in the HTTP header to authenticate the user, except that accessibility to a DeleGate as a "HTTP origin server" is checked in this case.

Example:

AUTH=origin:auth RELIABLE="*@localhost"
Any user who can login to the localhost of this DeleGate, giving a correct pair of user name and password in Authorization, will be authorized to access.

AUTH=forward[:{by,for,ver,*}]

Put identification information of the source host in the Forwarded field in a HTTP request header like:

Forwarded: by Me (Version) for Client

Currently, if this is specified, it is regarded as AUTH="forward:*:" regardless of the second field. This is useful for a DeleGate on a firewall which relays internal HTTP servers toward outside .

AUTH=viagen[:hostIdentifier]

Specify the identifier of the host of this DeleGate, which is put into the Via field in forwarded HTTP message headers as follows:

Via: protocol-version hostIdentifier ( comment )


If no AUTH=viagen is specified, a default pseudonym is used for hostIdentifier. If empty hostIdentifier is specified, as AUTH="viagen", the hostname of this DeleGate is used. A special specification AUTH="viagen:-" disables the insertion of the Via field.
If '%' character is used in a hostIdentifier, it is interpreted as the format for authString below.

AUTH=authgen:basic:authString

Generate "Authorization: Basic authString" in a HTTP request header to be forwarded to a server, if it does not have an original Authorization field from a client. The authString should be "userName:passWord". The following special string stand for attributes of clients.

%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:

When the firewall have two network interfaces and internal and external hosts access from different interface, then they can be distinguished by the name of interface.
AUTH="authgen:basic:%i:%h"
Otherwise, internal network should be explicitly defined using CMAP as follows.
AUTH="authgen:basic:%A"
CMAP="{internal:passWord}:authgen:*:*:{InternalNetList}"
CMAP="{external:passWord}:authgen:*:*:*"


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

AUTH=pauthgen:basic:authString

Generate "Proxy-Authorization: Basic authString" like AUTH=authgen.
Note: obsoleted by MYAUTH="user:pass:http-proxy".

Example:

Consume Proxy-Authorization in a request message from a client then forward it to an upstream proxy as is (by authString == %U:%P)
AUTH=proxy:pauth AUTH="pauthgen:basic:%U:%P" PROXY=...

AUTH=fromgen:fromString

If specified, "From: fromString" will be put in the HTTP request if the original header does not have an original From field. If fromString is omitted, the default value is "%u@%h".

AUTH=log:remoteHost:identUser:authUser

Specify contents of the client information part in common logfile format of HTTP servers. The default value is AUTH="log:%h:%u:%U".

%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:

To record information about an original client in an internal DeleGate which is forwarded from a firewall DeleGate, generate From field at the firewall DeleGate and record it at the internal DeleGate.

firewall% delegated AUTH="fromgen:%u@%h" ...
internal% delegated AUTH="log:%D/%h:%L/%u:%U" ...

To make configuration of DeleGate be flexible, allowing it not only to the administrator of the DeleGate but also to the users (providers of WWW resources on an origin HTTP-DeleGate), DeleGate supports reading user defined configuration parameters at each request processing time. Such parameters should be given in a files with file name extension ".dgp", in the format of "+=parameters" file, on MOUNTed local file systems. It works like -Fcgi but more efficiently without creating a new process.

Example: MOUNTing news serverN at http://delegate/news/servN/

(1) by a parameter at the start-up time
MOUNT="/news/servN/* nntp://nntpserverN/*"

(2) by a CGI-DeleGate
MOUNT="/news/* cgi:/dirPath/*"

[the contents of file:/dirPath/servN/welcome.cgi]
delegated -Fcgi MOUNT="/* nntp://nntpserverN/*"

(3) by a ".dgp" file
MOUNT="/news/* file:/dirPath/*"

[the contents of file:/dirPath/servN/welcome.dgp]
MOUNT="/* nntp://nntpserverN/*"

(This mechanism should be applied to other protocols like FTP...)

Server Side Include in SHTML files

On an origin HTTP-DeleGate, a local file with suffix ".shtml" is regarded, like a file with ".html", as a HTML file except that it includes special tags for Server Side Include (SSI) and META which are to be interpreted and substituted by the HTTP-DeleGate before it is sent to a client.

SSI tags

<!--#echo var="varName" -->

will be substituted with the value specified by varName. varName can be arbitrary CGI compatible name like "REMOTE_HOST" or "HTTP_SERVER", as well as followings.

DATE_GMT -- current time in GMT

DATE_LOCAL -- current time local to the server host

LAST_MODIFIED -- the last modified time of the .shtml file

REFERER -- equiv. to HTTP_REFERER

DOCUMENT_NAME -- equiv. to SCRIPT_NAME

DOCUMENT_URI -- equiv. to REQUEST_URI

* -- all of variables as name=value pairs

<!--#include virtual="URL" -->

will be substituted with the data specified by "virtual" attribute. "virtual" can be full URL like "proto://server/upath" or partial URL like "/upath" which will be interpreted as http://delegate/upath. Relative URLs like "upath" without leading "/" are interpreted as relative to the base (current) shtml file.

Note that including a resource by SSI is under the access control of DeleGate (as origin or proxy server) common to the access control against client users. That is, if a client user is forbidden to access the included resource, it is also forbidden even via SSI-include.
Especially allowing including a resource out of the DeleGate server, with URL like virtual=http://exserver/dir/fileX can make a security hole made by a user as a SHTML writer. In an origin server, relaying as a proxy must be forbidden by RELAY=no, but it also forbids SSI-include to do from other servers.
A simple workaround in version 9 is adding a limited RELAY as RELAY="proxy:http:exserver:*" that only allows relaying to exserver. Another safer workaround is using MOUNT like MOUNT="/ex/* http://exserver/dir/*" then write SSI-include like virtual="/ex/fileX". But both of these allows client users to access to resources other than the intended virtual URL in the exserver.

To cope with the above problem in version 10, RELAY=ssi is introduced to be used together with RELAY=no. RELAY=ssi allows SHTML writers to do include from other servers, leaving the permission for client users unchanged (as RELAY=no). In other words without RELAY=ssi, you (as the administrator of DeleGate) can forbid SHTML writers to include from other servers. Also you can restrict the includable target server (and protocols or clients) by the generic notation of DeleGate as RELAY=ssi:protocolList:serverList:clientList.
Another (and maybe more important) extension in version 10 is relaying request/response message header (as Cookie or User-Agent) back and forth between client and server via SSI-include.

NOTE: Maybe it is impossible to forbid CGIs to access arbitrary servers in a way independent of platforms and languages. But at least we can forbid CGIs completely with REMITTABLE="+,-cgi".

<!--#fsize virtual="URL" -->

<!--#flastmod virtual="URL" -->

will be substituted with the size or the last modified time of the specified data respectively.

<!--#config timefmt=timeFormat -->

will specify the format of generated time string by "#echo","#flastmod" or so, in strftime(3) compatible format. (default: timefmt="%a, %d %b %Y %H:%M:%S %z")

META tags

<META HTTP-EQUIV=fieldName content="fieldBody">

will generate "fieldName: fieldBody" header in the HTTP response message. The following patterns in fileBody will be substituted as described above.

${varName} or <!--#echo var=varName -->

${flastmod:URL} or <!--#flastmod virtual=URL -->

${fsize:URL} or <!--#fsize virtual=URL -->

${include:URL} or <!--#include virtual=URL -->

Example:

<META HTTP-EQUIV=Status content="200 OK">

<META HTTP-EQUIV=Content-Type content="text/html">

<META HTTP-EQUIV=Pragma content="no-cache">

<META HTTP-EQUIV=Date content="${DATE_GMT}">

<META HTTP-EQUIV=Last-Modified content="${flastmod:URL}">