Permission to use this material for evaluation, copy this material for your own use, and distribute the copies via publicly accessible on-line media, without fee, is hereby granted provided that the above copyright notice and this permission notice appear in all copies. AIST makes no representations about the accuracy or suitability of this material for any purpose. it is provided "as is", without any express or implied warranties.

PERMUTED INDEX

-F -P -f -r -v -d ADMIN AF_LOCAL Aging AUTH AUTHORIZER BASEURL CACHE CACHEFILE CGIENV CHARCODE CHROOT CMAP CONNECT CRON DATAPATH DELAY DELEGATE DGOPTS DGPATH DGROOT DGSIGN DNSCONF DYLIB EXPIRE FCL FFROMCL FFROMMD FFROMSV FMD FSV FTOMD FTOSV FILETYPE FORWARD FTOCL FTPCONF HOSTLIST HOSTS HTMLCONV HTTPCONF ICP ICPCONF INETD LIBPATH LOGDIR LOGFILE MASTER MASTERP MAXIMA MIMECONV MOUNT MYAUTH MountOptions NNTPCONF OWNER PERMIT PORT PROTOLOG PROXY REACHABLE REJECT RELAY RELIABLE REMITTABLE RESOLV RES_AF RES_CONF RES_DEBUG RES_NS RES_RR RES_VRFY RIDENT ROUTE RPORT SERVER SHARE SMTPCONF SMTPGATE SockMux SOCKOPT SOCKS SRCIF SSLTUNNEL STLS TIMEOUT TUNNEL UMASK URICONV VSAP XCOM XFIL

CFI CU-SeeMe DGAuth DNS FTP Gopher HostList HTTP ICP IMAP LDAP NNTP PAM POP ProtoList SMTP SockMux Socks SSI.shtml SSL TCPrelay Telnet UDPrelay Whois X

NAME

SYNOPSIS

DESCRIPTION

OPTIONS ( -P -f -r -v -d -F name=value )

Terminology

Parameters

General

SERVER ADMIN OWNER CRON INETD HOSTLIST CMAP DYLIB LIBPATH DATAPATH DGPATH DGOPTS DGSIGN SOCKOPT PORT

Routing

FORWARD ROUTE MASTER MASTERP PROXY SOCKS SSLTUNNEL VSAP CONNECT SRCIF TUNNEL RPORT

Access control

PERMIT REJECT REMITTABLE REACHABLE RELIABLE RELAY AUTH AUTHORIZER MYAUTH RIDENT

Resource usage restriction

MAXIMA TIMEOUT DELAY

Cache control

CACHE EXPIRE CACHEFILE ICP

Mount

MOUNT MountOptions URICONV BASEURL DELEGATE

Data conversion

CHARCODE HTMLCONV MIMECONV

Filter control

FCL FTOCL FFROMCL FSV FTOSV FFROMSV FMD FTOMD FFROMMD XCOM XFIL

Local file usage

CHROOT DGROOT SHARE UMASK LOGDIR LOGFILE PROTOLOG Aging

Host name resolution

HOSTS RESOLV RES_CONF RES_NS RES_AF RES_RR RES_VRFY RES_DEBUG

Protocol specific

HTTPCONF FILETYPE CGIENV ICPCONF FTPCONF NNTPCONF SMTPCONF SMTPGATE DNSCONF




ProtoList

HostList

Parameter Substitution

CFI and CFI Script

Proxying by URL Redirection

Protocol Specific Issue and Examples

TCPrelay UDPrelay SockMux Socks DGAuth PAM HTTP SSI.shtml ICP FTP Telnet POP IMAP SMTP NNTP LDAP Whois X Gopher SSL DNS CU-SeeMe




Reserved Names

AF_LOCAL Sockets

Customization

Platform Specific Issue ( Unix MS-Windows OS/2 )

Defense Against Attackers

Gentle Restart

Functions

FILES

SEE ALSO

AUTHOR

FEEDBACK

DISTRIBUTION

--------- --------- --------- --------- --------- --------- --------- ---------
DELEGATED(8)                MAINTENANCE COMMANDS                   DELEGATED(8)

delegated -Pport [-f] [-r] [-Ffunc] [-v[vdts]] [+=configfile] [name=value]* [--]

DeleGate is a multipurpose proxy server which relays various application protocols on TCP/IP or UDP/IP, including HTTP, FTP, Telnet, NNTP, SMTP, POP, IMAP, LPR, LDAP, ICP, DNS, SSL, Socks, and more. DeleGate mediates communication between servers and clients where direct communication is impossible, inefficient, or inconvenient.

DeleGate works as an application level proxy which interprets relayed protocol (control sequence and data structure) between a client and a server; various value added services are realized for recognized protocol. Also DeleGate works as a circuit level proxy which literally conveys transmission between a client and a server of arbitrary protocols on TCP or UDP.

DeleGate can be used to enforce access control restricting remittable protocols, reachable servers, and acceptable clients. DeleGate forces delay for penalty on repetition of forbidden access, or make defense shutting down service and sending automatic reports to administrator on suspicion of attack. A basic logging on circuit level common to arbitrary protocol and protocol dependent logging in some common formats are supported for some protocols.

DeleGate can act as a kind of application level router, controlling direct or indirect routes toward a destination server by selecting upstream proxy or Socks server. One of exploitable routes toward a server will be selected or tried in order depending on application protocol, destination host and source client.

As an application level proxy, DeleGate interpretively relays various application protocols, providing various value added services including caching or conversion for relayed data, of which structure depends on each application protocol. Based on interpretation of application protocols, DeleGate can be used as a protocol gateway which translates between client-side protocol and server-side protocol.

As a circuit level proxy, a DeleGate server literally conveys transmission bound to a specified server of a specified application protocol on TCP or UDP, or toward arbitrary servers based on Socks protocol.

As an application level proxy, DeleGate provides virtual view for resources in other servers, by aliasing, merging, and hiding real names (like URL which identifies a resource or a service) in real servers. It is like a generalized mechanism of NFS file mount, but unlikely it is realized by rewriting content of data. In other words, this is a mapping (rewriting) of virtual names in client to/from real names in server, where names are embedded in a protocol dependent data structure on request/response messages between a client and a server. With this function named mounting, for example, a resource http://hostiN/ is shown to client as if it is http://hostx/iN/. MOUNT can be used to customize built-in icons and messages of DeleGate too.

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. Besides filtering by external programs, some of frequently used filtering operations are built-in to DeleGate, including HTTP header removal and generation.

All of local files of DeleGate, including log files and cache files, are placed under an individual root directory (DGROOT) as private files belong to the owner of the DeleGate by default. But to share them among different users, the path name, owner, and access permission of each file can be customized. Also log file name can be parameterized with date value for aging, and cache file name can be parameterized with hash value to distribute cache disks.

Although DeleGate can be controlled by a lot of options, only -Pport option and SERVER=protocol parameter are mandatory to operate in most case. The -P option specifies on which port DeleGate receives requests from clients. SERVER parameter specifies in which protocol DeleGate communicates with clients, and optionally to which destination server it will relay the communication.

Options can be loaded from local or remote resources with "+=URL" notation, typically from a local file like "+=/path/of/parameters" (see Parameter Substitution)

OPTIONS

   -P option  --  entrance port(s) to the DeleGate
              ==  -Pport[,port]*
        port  ==  [host:]portNum[/udp]
     portNum  ==  number[-number]

This option specifies on which entrance port DeleGate receives requests from clients. As a typical example, "-P8080" means it accepts request on TCP port numbered 8080 on any network interface belong to the host machine. When the host has multiple interfaces or multiple IP addresses assigned to a single physical interface, you can select one of them with the specification format -Phost:portNum, like "-Plocalhost:8080" for example. A DeleGate server can accept from multiple ports or (limited) multiple network interfaces by -Pport,port,...
When no host is specified, only IPv4 addresses are accepted. That is, -P8080 is the abbreviation of "-P0.0.0.0:8080". To specify IPv6 address here, substitute each colon symbol in the IPv6 address notation with an under score symbol. Fore example, "-P__:8080" means accepting at port 8080 with the wild card address of IPv6 "::". If necessary, a scope-ID can be specified with "%" symbol, like "-Pfe80__12_34%en0:8080" for example.
Note: See SRCIF as to selection of a source address of an outgoing connection.

An entrance port is made as a TCP port by default except UDP based application protocol (dns, icp, cuseeme, udprelay) is specified in SERVER=protocol parameter. And regardless of the protocol specified in SERVER, it can be made as a UDP port with postfix "/udp" like -Pport/udp.

This option MUST be specified except in following cases. It is ignored when the DeleGate is invoked from inetd(8), or in most case of -Ffunction option, or when running as a tunnel server with SERVER="tunnel1".

   -f option  --  foreground execution

If specified, DeleGate runs in foreground keeping connected with current control tty so that it can be killed with SIGINT from the tty, and staying at (without changing work directory from) the current directory.

   -r option  --  restart

If specified, currently running DeleGate on the same entrance port if exist is finalized before starting this DeleGate. It has the same effect as doing -Fkill before start.

   -v option  --  logging level control
              ==  -v[vdtsau]

If specified, DeleGate will run in foreground like -f and log will be put on the control tty, not to LOGFILE and PROTOLOG. More detailed log than that of -v can be got using -vv option. Similarly you can control the detailness of log to be written into logfile by -vd, -vt or -vs options; -vd makes logs detailed with debug information whereas -vt makes it terse and -vs makes logging stop and be silent; this option has similar effect with LOGFILE="". Another option -va makes hidden log in the most detailed level (that of -vd) which is output only when some kind of ABORT occurred to cause emergency shutout. -vu puts logging level back to usual one.

   -d option  --  debugging of sub components
              ==  -d[hs]

-dh enables detailed logging of HostList matching. -ds enables logging of socket manipulation including bind(), accept() and connect().

   -S option  --  watch SIGCHLD signal

   -T option  --  trace system calls
              ==  -T[xsdt]*

   -F option  --  extra function
              ==  -Ffunction

If specified, DeleGate will work as a program of specified function rather than a DeleGate server. For example, "delegated -Fkill -Pport" means to kill the DeleGate running on the port. With -Fcgi, DeleGate act as a cgi program which is invoked form a HTTP server. A list of available functions will be shown with -Fhelp.

   -- option  --  hiding command line arguments

   parameter  ==  name=value

   conditional parameter == (condition)parameter

Some parameters and -v option can be restricted to be applied conditionally, by prefixing "(condition)" to a parameter. Currently, condition is a list of client host which is described in HostList. For example, "(.localnet)-vs" specifies to suppress logging when the client is from local networks. Parameters which can be conditional with this prefixion are: BASEURL, DELAY, DELEGATE, FCL, FSV, FFROMCL, FFROMSV, FTOCL, FTOSV, LOGFILE, MAXIMA, RIDENT and TIMEOUT. This mechanism does not work for UDP sockets.

   -e option  ==  -ename=value

delegated

A server process of DeleGate and the standard file name of a DeleGate program; the trailing "d" implies "daemon" or server (by convention on Unix)

specialist

A DeleGate configured to talk a specified client-side protocol (with SERVER=proto)

generalist

Also called MASTER-DeleGate which can talk arbitrary client-side protocol which will be determined at run-time (with SERVER="delegate") where clients are DeleGate which use this DeleGate as an upstream proxy (pointing by a MASTER parameter).

bound DeleGate

DeleGate bound to a specified destination server (with SERVER=proto://host)

unbound DeleGate

DeleGate not bound to any destination server (without SERVER=proto://host)

P-DeleGate (ex. HTTP-DeleGate)

DeleGate communicate with clients in protocol P

Q/P-DeleGate (ex. FTP/HTTP-DeleGate)

DeleGate communicate with clients in protocol P and communicate with servers in protocol Q

P proxy (ex. HTTP proxy)

A proxy server which communicates with clients in protocol P

ProtoList

a list of protocols

HostList

a list of hosts or networks

dstHostList

a HostList of destination (servers)

srcHostList

a HostList of source (clients)

item(N) (ex. gethostbyname(2))

reference to item described in the section N of Unix online manuals

General

Parameters in this category are used to control common attributes of DeleGate independently of the purpose of usage or target application protocol.

	name	value format	functionality
--	----------	------------------	----------------------------------
	SERVER	proto://host:port	client-side protocol and default server
	ADMIN	user@host.domain	E-mail addr. of the admin. of this DeleGate
+	OWNER	user[/group]	with who's access right this DeleGate runs
*	CRON	crontab-spec	cron compatible scheduler of actions
*	INETD	inetd-conf	inetd like server configuration notation
*	HOSTLIST	name:hostList	define a named HostList
*	CMAP	map-spec	mapping table about the current connection
	DYLIB	patternList	file-name patterns of dynamic libraries
	LIBPATH	dir:dir:...	search path for library files
	DATAPATH	dir:dir:...	search path for data files
	DGPATH	dir:dir:...	search path for SUBSTITUTION resources
	DGOPTS	option;option;...	list of command line options
	PORT	portList	reserve entrance ports like -P option

These parameters control the indirect routing toward the target server exploiting upstream proxies or Socks servers on the way to servers. If any target hosts are directly reachable on IP level from your DeleGate's host, these parameters may not necessary. Besides these parameters, ICP and MOUNT have something to do with routing based on application protocols.

--	----------	------------------	----------------------------------
*	FORWARD	proxy-_-proto:dst:src	forward to proxy when from src to dst in proto
*	ROUTE	proxy-_-dst:src	forward to proxy when from src to dst
*	MASTER	host:port	connect via the upstream DeleGate
	MASTERP	[host:port]	invoke a MASTER private to this DeleGate
*	PROXY	host:port	connect via the upstream proxy
*	SOCKS	host[:port]	connect via the socks server
	SSLTUNNEL	host:port	connect via the SSL tunnel for HTTPS
	VSAP	host:port	accept/connect via a remote host
*	CONNECT	ca,ma,di,so,...	the order of trials of connection types
*	SRCIF	host[:port]	source address of connection to server
	TUNNEL	type:scriptPath	connect via the tunnel on serial line
	RPORT	{tcp|udp}[:host]	return port from the MASTER-DeleGate

These parameters control who (client) can access to what (server) and how (protocol). The basic policy of default access control is designed so that clients on networks local to the host of DeleGate are permitted to access to any server. Note that the default value of REMITTABLE depends on SERVER, and IP-level reachability to DeleGate on a multi-homed host may be restricted by -Phost:port option.
You must most carefully configure these parameters so that this DeleGate does not introduce a security hole, especially when it is running on a host which is directly accessible to/from the internet.

--	----------	------------------	----------------------------------
*	PERMIT	proto:dst:src	protocols/servers/clients to be permitted
*	REJECT	proto:dst:src	protocols/servers/clients to be rejected
	REMITTABLE	ProtoList	protocols remittable to the server
*	REACHABLE	dstHostList	only specified server hosts are reachable
*	RELIABLE	srcHostList	accept only from the specified client hosts
*	RELAY	proxy|delegate|no	restrict proxying modes
*	AUTH	what:aproto:users	authorized users for remote administration
*	AUTHORIZER	serv:proto:dst:src	authentication server
*	MYAUTH	user:pass:proto:dst:src	authentication client
	RIDENT	client|server	forward socket addr. to upstream DeleGate

Enable or disable cache and specify validity of cached data. Usage of cache is controlled in context of routing by CONNECT too. Removing stale cache file can be done periodically using CRON.

--	----------	------------------	----------------------------------
	CACHE	do|no|ro	control to do cache or not
*	EXPIRE	days|hours|secs	expiration of the cached data
	CACHEFILE	fileNameSpec	in which file cache data are stored
*	ICP	icpClientConfig	configuration as an ICP client

Provide virtual view for other server(s) by URL mapping, filtering and aliasing resource names, to merge multiple servers, to translate between different protocols, to export internal servers, and so on. Also MOUNT can be used to customize or replace built-in icons and messages.

--	----------	------------------	----------------------------------
*	MOUNT	"vURL rURL opt"	map virtual URL to/from real URL
*	URICONV	convList:attrList	control URI rewriting with MOUNT
	BASEURL	URL	the base of (virtual) URL of this server
	DELEGATE	host:port	limited form of BASEURL

Local file usage

All of local files are integrated under DGROOT by default. You should not change nor specify these parameters if not necessary.

--	----------	------------------	----------------------------------
+	CHROOT	dirPath	change the root of file system at start
+	DGROOT	dirPath	root directory of all of DeleGate files
*+	SHARE	dirPatternList	files to be shared among users
+	UMASK	mask	umask value in octal
	VARDIR	dirPath	default base of log and cache
	CACHEDIR	dirPath	where cache files are placed
	ETCDIR	dirPath	where persistent management files are
	LOGDIR	dirPath	where DeleGate logs are
	LOGFILE	LogFilename	where DeleGate makes logging
	PROTOLOG	LogFilename	httpd or wu-ftp compatible log file
	ERRORLOG	LogFilename	where DeleGate make error logging
	TRACELOG	LogFilename	where signal trace (by -T) is put
	EXPIRELOG	LogFilename	file which records expire log
	WORKDIR	dirPath	where DeleGate should dump core (-_-;
	ACTDIR	dirPath	where temporary files are placed
	TMPDIR	dirPath	where invisible temporary files are placed
	PIDFILE	fileName	where the DeleGate's PID is recorded

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 omitable 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". 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:-/

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

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

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="*:*@*".

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"

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.

STLS parameter*     ==  STLS=stlsSpecs[,sslwayCom][:connMap]
         stlsSpecs  ==  [-]stlsSpec[/ssl][,stlsSpecs]
          stlsSpec  ==  fsv | fcl | imimSec
         sslwayCom  ==  sslway [-Vrfy] [-CApath dir] ...
           connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none
                    --  restriction: applicable to HTTP, FTP, SMTP, POP, IMAP
                    --  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 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

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

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

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

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

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

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

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

FORWARD parameter*  ==  FORWARD=gatewayURL[-_-connMap]
        gatewayURL  ==  gwproto://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.
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 and SOCKS as follows.

delegate

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

http, ftp, telnet

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

socks

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

If multiple routes to the destination server are available, the route defined by FORWARD is tryed in precedence defined by "proxy" or "master" in CONNECT.

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

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

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

PROXY parameter*    ==  PROXY=host:port[:dstHostList]
                    --  default: none

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

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

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

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" -- 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,vhost,nojava:*:*:.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.

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:*:user@host"

Permit a user who is authenticated as user@host to perform remote administration of this DeleGate from HTTP clients, at "http://delegateHost:Port/-/admin/", including server restarting and logging control. A DeleGate of arbitrary protocol (regardless of SERVER=protocol except SERVER=tcprelay) is controllable with this.
The second field should be "*" in current implementation.

-- 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  ==  authServ[,authServ]* | & | *
           authServ  ==  authHost[/portNum][(reprUser)]
           authHost  ==  hostName | hostAddr
            connMap  ==  ProtoList:dstHostList:srcHostList
                    --  default: none
                    --  restriction: applicable to Telnet, FTP, NNTP, SMTP, Socks, 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

DGAuth: 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. To store a password to be used in such way, run 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: On platforms where PAM (Pluggable Authentication Modules) is available, it can be used for authentication with the syntax AUTHORZIER="-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: 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


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

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

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

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]
acc	--	for accept from client (include FTP data connection) [10]
con	--	for connection to the server [10]
lin	--	LINGER for output [30]
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) [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,...

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.

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.

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.

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.

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.

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

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.

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

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

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.

CACHE parameter*    ==  CACHE=cacheControl[,cacheControl]*
      cacheControl  ==  do | no | ro
                    --  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

CACHEFILE parameter ==  CACHEFILE=fileNameSpec
                    --  default: CACHEFILE='$[server:%P/%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

CHARCODE parameter  ==  CHARCODE=[inputCode/]outputCode
        outputCode  ==  charCode
          charCode  ==  iso-2022-jp | euc-jp | shift_jis | JIS | EUC | SJIS | UTF8
                    --  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 UTF8 and JIS is downloaded automatically from the server at Unicode.Org. The full specification format of the parameter value is inputCode/output-code. CHARCODE=JIS is the abbreviation of CHARCODE=JP/JIS where JP means Japanese text encoding {JIS,EUC,SJIS,UTF8}.

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.

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

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

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

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

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

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

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

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.

LOGDIR parameter    ==  LOGDIR=dirPath
                    --  default: LOGDIR='${VARDIR}/log'

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.

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

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

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}'

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

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

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

RES_NS parameter    ==  RES_NS=nsList
                    --  nsList=dnsServ[,nsList]
                    --  dnsServ=dnsServer[//socksV5Host]
                    --  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

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

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

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

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

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

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.

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 == [ Action "/" ] ruleName ":" ruleBody
Action == "Output" | "Remove"
ruleName == "Body-Filter" | "CGI" | "Header-Filter" | "Message-Filter" | MIMEhdr | X-hdr
MIMEhdr == "Content-Type" | "User-Agent" | ...
X-hdr == "X-Status-Ver" | "X-Status-Code"
| "X-Request-Method" | "X-Request-Ver"| "X-Request-URL" | ...
ruleBody == string NL [ SP string NL ]*


If no Action is specified, it 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)

When the header ruleName is "Body-Filter", "CGI", "Header-Filter", or "Message-Filter", exceptionally they specifies an action (or filtering) to be applied to the input data. For filters of "Body-Filter" or "CGI", the body part of the 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. The "Content-Length" header in the forwarded message will be adjusted to indicate the size of the body part to be forwarded. 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 "Message-Filter", whole message consists of header and body is passed to and from the filter.

With a prefixed "Action/" to a ruleName:ruleBody, some simple rewriting using ruleBody data for relevant ruleName field will be done. "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.

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

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

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 remotel can be selected depending on which remote 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).

Socks-DeleGate accepts both SocksV4 and V5. 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.

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

The format of PROTOLOG for HTTP protocol can be modified with a optional format specification postfixed after the LogFilename as PROTOLOG="LogFilename:format". In this case, default file name can be omitted. For example, PROTOLOG=":%X" specifies making a NCSA like extended common logfile format. The default format is PROTOLOG=":%C %D".

%C	-- common logfile format of CERN-HTTPD
%c	-- same as %C except the date is recorded in millisecond precision
%D	-- extension by DeleGate (connTime+relayTime:status)
%X	== '%C "%r" "%u"' common logfile format with Referer and User-Agent
%r	-- Referer field in the request message
%u	-- User-Agent field in the request message
%S	-- status of CONNECTion to the server (c,m,p,d,s,v)
%s	-- session Id by HTTPCONF=session
%As	-- session Id in Digest Authorization
%{field}	-- arbitrary field in the request message

The 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  ==  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.

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

kill-[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.

Example:

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


add-[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.

Example:

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


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-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 [10]

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 [4k]

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

[0.25]

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

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

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

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  ==  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="*"

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.

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.

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

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.

genvhost=host

Set "Host: host" field in the request message to be forwarded to the server. 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/* vhost=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/* vhost=-dom1.com"
MOUNT="/* http://wwwB/* vhost=-dom2.org"
MOUNT="/* file:data/wwwC/* vhost=-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=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...)

ICP-DeleGate provides remote clients with ICP service about local CACHEDIR, independently of contents server like HTTP-DeleGate but sharing the same CACHEDIR. See http://www.delegate.org/delegate/icp/ for more details.

Example: a couple of ICP and HTTP DeleGates sharing a CACHEDIR

% delegated -P3130 SERVER=icp
% delegated -P8180 SERVER=http

Example: an ICP proxy merging multiple upstream ICP servers

% delegated -P3130 SERVER=icp ICP=icpHost1,icpHost2,...

ICPCONF parameter*  ==  ICPCONF={icpMaxima|icpConf}
         icpMaxima  ==  para:N|hitage:N|hitobjage:N|hitobjsize:N|timeout:N
           icpConf  ==  icpOptions:ProtoList:dstHostList:srcHostList
                    --  default: ICPCONF=para:2,hitage:1d,...

Existing FTP clients without any proxying feature can use DeleGate as a FTP proxy in two ways:

USER user@host

at login time, enter the host name of a FTP server after user name.

CWD //host[/path]

at any time, enter the host name of a FTP server after "//" as if it is a directory

A user name can be followed by an account name as follows.
USER user~account@host

Also the complete format user:pass@host[:port] as the generic server specification in URL is usable both for USER and CWD like follows.

USER ftp:foo%40bar@server
CWD //ftp:foo%40bar@server/path


On a multi-homed host, or on a host behind a firewall, the IP address or port number used for data connections might have to be controlled by SRCIF.

Example: proxy FTP-DeleGate

firewall% delegated -P8021 SERVER=ftp


Then you can connect to arbitrary FTP servers (which may be outside of firewall) via this FTP-proxy.

internal% ftp
ftp> open firewall 8021
220- firewall PROXY-FTP server (DeleGate/6.1.0) ready.
220-   @ @
220-  ( - ) { DeleGate/6.1.0 (February 3, 2000) }
...
220- --
220- You can connect to a SERVER by `user' command:
220-    ftp> user username@SERVER
220- or by `cd' command (after logged in as an anonymous user):
220-    ftp> cd //SERVER
220- Cache is enabled by default and can be disabled by `cd .' (toggle)
220- This (proxy) service is maintained by 'admin@your.domain'
220  
Name (yourhost:yourname): ftp@ftp1
331-- USER for ftp@ftp1.
220- ftp1 FTP server ready.
331- Guest login ok, send your complete e-mail address as password.
331--  @ @  
331  \( - )/ -- { connected to `ftp' }
Password: me@my.domain
230 Guest login ok, access restrictions apply.
ftp> cd //ftp2
250-- CWD for ftp@ftp2
220- ftp2 FTP server ready.
230- Guest login ok, access restrictions apply.
250--  @ @  
250  \( - )/ -- { connected to `ftp2' }
ftp> 

Note: The majority of ftp clients can allow to specify the port number of FTP at command line like:
internal% ftp firewall 8021

Example: cascaded FTP-Proxy

firewall# delegated -P21 SERVER=ftp PERMIT="ftp:*:internal"
internal# delegated -P21 SERVER=ftp PROXY=firewall:21


Example: FTP MOUNT with filtering, merging and aliasing

firewall# delegated -P21 SERVER=ftp://serv1/ \


MOUNT="/pub2/* ftp://serv2/pub/*"

This DeleGate relays the whole contents of serv1 except for "/pub2/*" which is replaced by that of "ftp://serv2/pub/*"

Example: FTP to LPR (Line Printer Daemon Protocol) gateway

MOUNT="/* lpr://printer0/queue0/*"
MOUNT="/pr1/* lpr://printer1/queue1/*"
MOUNT="/pr2/* lpr://printer2/queue2/*"


A LPR/FTP-DeleGate allows FTP clients to access to remote printers; printing a file by FTP file uploading and showing a printer status by FTP directory listing. MountOption "readonly" will inhibits listing the status.

Example: origin FTP-DeleGate

host# delegated -P21 SERVER=ftp MOUNT="/* /path/of/root/*" RELAY=no


"RELAY=no" prohibits the DeleGate to work as a proxy FTP server. Writing to the file is disabled by default in origin FTP-DeleGate. You need to specify "rw" (read/write) as a mount option to MOUNT points to be writable, like MOUNT="/xxx/* /yyy/* rw".
Retrieving the whole contents under a specified directory and returning it as a single file in tar format by "RETR directory.tar" command is supported to be enabled by adding "tar" to the REMITTABLE list like REMITTABLE="+,tar".

FTPCONF parameter*  ==  FTPCONF=ftpControl[:{sv|cl}]
           ftpControl  ==  nopasv | noport | noxdc | rawxdc
                    --  default: none

The format of PROTOLOG for FTP protocol is so called xferlog(5) which is compatible with that of "wu-ftp". Each line of xferlog consists of following elements (in a single line).

currentTime transferTime clientHost


fileSize fileName transferType specialActionFlag direction accessMode
userName serviceName authenticationMethod authenticatedUserID DeleGateStatus

transferTime is the total time in seconds for the transfer. transferType is either "a" (ascii) or "b" (binary). specialActionFlag is always "_" (none) in the current implementation. direction is either "o" (outgoing) or "i" (incoming). accessMode is either "a" (anonymous) or "r" (real user). userName is e-mail address with accessMode "a", or a real user name with accessMode "r". serviceName is always "ftp" in the current implementation. authenticationMethod is either "0" (none) or "1" (RFC1413 Authentication). authenticatedUserID is the user id got via the authenticationMethod or "*" without authentication. DeleGateStatus is one of "L" (local file), "H" (cache hit), "N" (cache miss).

Example:

Mon Feb 28 15:32:15 2000 13 proxy.xyz.co.jp

182558 /ftp/pub/DeleGate/Manual.htm a _ o a
webmaster@xyz.co.jp ftp 0 * L

Telnet-DeleGate can relay X Window protocol as well as Telnet protocol in similar way to FWTK.

Example: proxy Telnet-DeleGate

firewall% delegated -P8023 SERVER=telnet TIMEOUT=io:1h

Then you can connect to arbitrary Telnet server via this Telnet-proxy.

internal% telnet firewall 8023
...
--  @ @  firewall PROXY-telnet server DeleGate/6.1.0
-- ( - ) { Hit '?' or enter `help' for help. }
...
-- -- -- This (proxy) service is maintained by 'admin@your.domain'
>> Host name: exthost
-- Connected to exthost.

SunOS UNIX (exthost)
login: 

Example: origin Telnet-like server

C:\> delegated -P23 SERVER=exec XFIL=command.com WORKDIR="/"
// Use command.com of Windows95/98 as a simple telnet server.

SMTPCONF parameter  ==  SMTPCONF=what:conf
                    --  default: SMTPCONF=bgdatasize:64K

SMTPGATE parameter  ==  SMTPGATE=dirPath
                    --  default: SMTPGATE='${ETCDIR}/smtpgate'

Specify the configuration directory for SMTPGATE, a SMTP to {SMTP,NNTP} gateway. To accept and relay SMTP messages bound to "recipient@the-host-of-DeleGate", create a configuration directory at "SMTPGATE/users/recipient" for each recipient, to hold files for configuration, log, counter, and spool. Then create a configuration file named "SMTPGATE/users/recipient/conf".

Example: SMTP to SMTP forwarding

// forward messages accepted at "feedback@delegate.org"
// toward "delegate-en@smtpgate.etl.go.jp"


delegate.org# delegated -P25 SERVER=smtp

[the contents of SMTPGATE/users/feedback/conf]

INHERIT: sendmail
SERVER-HOST: mail.etl.go.jp
RECIPIENT: delegate-en@smtpgate.etl.go.jp
ACCEPT/From: !%, !MAILER_DAEMON@, !hotmail.com, ...

Example: SMTP to NNTP forwarding

[the contents of SMTPGATE/users/feedback/conf]
INHERIT: postnews
SERVER-HOST: news.delegate.org
OUTPUT/Newsgroups: mail-lists.delegate-en
OUTPUT/Distribution: world
OUTPUT/Reply-To: feedback@delegate.org
OUTPUT/Subject: [DeleGate-En] ${subject:hc}
OUTPUT/Header: X-Seqno: ${seqno}
OUTPUT/Header: UNIX-From: ${unixfrom}
CONTROL/Errors-To: mladmin@delegate.org
ACCEPT/User-Text: delegate ## reject if a word "delegate" is not in body
ACCEPT/Max-Bytes: 50000 ## reject larger 50KB header+body
ACCEPT/Min-Body-Bytes: 64 ## reject smaller 64B body
OPTION: isn,rni,res,reb


A SMTPGATE configuration file consists of a series of lines of directives, each looks like a message header of the internet message. Comment string after sharp (#) character in each line is ignored. Directives are categorized into three groups; CONTROL, ACCEPT and OUTPUT.

CONTROL

Specify the function of the gateway, the destination server, and the destination address in the envelope. Note that you can inherit a configuration from another recipient as well as "sendmail" and "postnews" in the INHERIT directive.

INHERIT: {sendmail | postnews | recipient}

SERVER-HOST: host

SERVER-PORT: portNumber

RECIPIENT: EmailAddressForm (used with "sendmail")

CONTROL/SENDER: EmailAddressForm (envelope's From in SMTP)

CONTROL/BCC: EmailAddressForm (a copy is sent to the address on success)

CONTROL/Errors-To: EmailAddress (a copy is sent to the address on error or rejection)

ARCHIVE: archiveFileNameForm

MYAUTH: username:password (AUTHINFO for NNTP server)

OPTION: OptionList

isn -- Increment Sequence Number (to be referred by ${seqno})
rni -- Reject No message-Id
res -- Reject Empty Subject
reb -- Reject Empty Body
axo -- Append X-Original headers
rxo -- Remove X-Original headers
gwt -- GateWay Trace
ntr -- Do NOT add trace field (Received:)

ACCEPT

If specified, only messages which have fields matching with specified patterns are accepted.

ACCEPT/Sender: ListOfEmailAddressPattern

ACCEPT/Recipient: ListOfEmailAddressPattern

ACCEPT/From: ListOfEmailAddressPattern

ACCEPT/To: ListOfEmailAddressPattern

ACCEPT/Max-Bytes: messageSize

ACCEPT/Min-Body-Bytes: bodySize

ACCEPT/Max-Exclams: theNumberOfExclamationMarks

ACCEPT/User-Text: listOfWords (in Subject or body)

REJECT/User-Text: listOfWords (in Subject or body)

ACCEPT/Content-Type: listOfTypesOrCharsets

ACCEPT/Client-Host: srcHostList

OUTPUT

Header fields to be put into the output messages replacing the original fields in the input message.

Newsgroups: fieldBodyForm (to be used with "postnews")

Distribution: fieldBodyForm (to be used with "postnews")

Reply-To: fieldBodyForm

To: fieldBodyForm

Subject: fieldBodyForm

Header: fieldName: fieldBodyForm

FILTER: filterCommand

Substitution

The following patterns appearing in ...Form in field body part of directives are substituted with the values in the header or the envelope of the input message.

${sender} -- sender in the envelope (in RCPT To)

${recipient} -- recipient in the envelope (in MAIL From)

${recipient.name} -- local name part of the recipient

${recipient.mx} -- Mail eXchanger of the recipient

${header.field} -- body of header field in the input message

${from} -- From field in the input message

${unixfrom} -- Unix-From string for the recipient

${subject} -- Subject field in the input message

${subject:hc} -- head-cleaned Subject field

${seqno} -- sequence number

${seqno/10} -- sequence number / 10 (used with ARCHIVE)

${seqno/100} -- sequence number / 100 (used with ARCHIVE)

${date+format} -- formatted string of current time (used with ARCHIVE)

When a SMTP-DeleGate received a message bound for a recipient, with an address formed as recipient@mailhost, it retrieves the configuration file for the recipient in the following two directories in the order.

SMTPGATE/users/recipient/

SMTPGATE/admin/recipient/

If no configuration for the recipient is found, then the default configuration is used if it exists at the following directory.

SMTPGATE/admin/@default/

Otherwise the built-in default configuration is used. The default is at "/-/builtin/config/smtpgate/@default/conf" which can be customized with MOUNT option. The contents of the default is like follows which means just delivering the input message to the address of the recipient via the mail exchanger of the recipient.

CONTROL/INHERIT: sendmail
CONTROL/RECIPIENT: ${recipient}
CONTROL/SERVER-HOST: ${recipient.mx}


The directory for each recipient contains following files.

recipient/conf -- configuration file

recipient/log -- log file

recipient/count -- counter file for ${seqno} (optional)

recipient/spool/ -- archive directory of relayed messages (optional)

recipient/rejected/ -- archive directory of rejected ones (optional)

Optional ones will be enabled by manually creating the file or the directory. Instead of the default archive file, user can define the file name and the unit of archive by ARCHIVE directive.

Example:

ARCHIVE: spool/%05${seqno}-${date+%Y%m%d-%H%M%S}-%05${pid}


## default archive enabled if spool/ exists


ARCHIVE: arc-${seqno} ## archive with sequence number


ARCHIVE: arc-%4${seqno/10} ## an archive file per every 10 messages


ARCHIVE: arc-${date+%Y-%m} ## an archive file per month

MOUNT can be applied to NNTP-DeleGate, for filtering and aliasing of newsgroups, and for merging multiple NNTP severs. For example, MOUNT="alias-group. nntp://server/group." specifies to passing newsgroups "group.*" and aliases them into "alias-group.*". A simple filtering specification is SERVER="nntp://server/group." which is equivalent to MOUNT="= nntp://server/group.". If multiple MOUNT for multiple NNTP servers, then the DeleGate merges the newsgroups on the servers, and serves the newsgroups to a client as if they are on a single server.

Example: Filtering

# delegated -P119 SERVER=nntp://nntpServer/group.

relays only newsgroups which have name pattern "group.*". A list of groups can be specified for a nntpServer like "nntp://nntpServer/group1.,group2.,..."

Example: merge multiple NNTP servers

# delegated -P119 SERVER=nntp \


MOUNT="= nntp://server1/"
MOUNT="= nntp://server2/"

Example: merge multiple NNTP servers with authentication (by AUTHINFO)

# delegated -P119 SERVER=nntp \


MOUNT="= nntp://user1:pass1@server1/"
MOUNT="= nntp://user2:pass2@server2/"

Example: mount selected group(s)

// mounts groups of group.* with it original names.
MOUNT="= nntp://server1/group."
// mounts groups of group.* with aliased names "alias-group.*"
MOUNT="alias-group. nntp://server1/group."

Example: POP server to NNTP client

// mounts a mail spool as if it is a newsgroup named "+pop.user.host".
# delegated -P119 SERVER=nntp MOUNT="= pop://user:pass@host/"

Example: NNTP server to HTTP client

# delegated -P80 MOUNT="/news/* nntp://nntpServer/*"

Example: origin NNTP-DeleGate

# delegated -P119 SERVER=nntp://-.-/

Specifying "-.-" as the destination server in SERVER parameter of NNTP-DeleGate means using the DeleGate as an origin NNTP server which has its own spools to be retrieved and posted. To make a new newsgroup named newsGroup, make an empty file

'${ETCDIR}/news/groups/newsGroup'
To relay an existing "/path/of/MH-folder" as newsGroup, make a file like above and fill it with content like
0 0 0 0 /path/of/MH-folder
(four zeros followed by a path name of a MH-folder)

When a posted article has Unix-From like "From user date" as the first line or has a "Unix-From: user date" header, the article number for the article is set to the one indicated in "X-Seqno" (or "X-Sequence") header if exists, and the creation date of the spool file will be set to the date in the Unix-From.

MountOptions for NNTP

NNTPCONF parameter* ==  what:conf
                    --  default: NNTPCONF=upact:600/300/120

Example: proxy LDAP-DeleGate

# delegated -P389 SERVER=ldap

Specify this DeleGate server as your client's LDAP server and append "@host.of.ldap-server" after root directory name (i.e. name of baseObject for search).

% ldapsearch -x -h localhost -p 389 -b o=netcenter.com@memberdir.netscape.com

Example: LDAP gateway

# delegated -P389 SERVER=ldap \

MOUNT="o=xxx* ldap://aaa.domain nocase" \

MOUNT="o=yyy* ldap://bbb.domain nocase"

Search requests on base directory named "o=xxx..." sent to this LDAP-DeleGate is forwarded to the LDAP-server "ldap://aaa.domain".

Using a filter program "sslway" in FCL, FSV, or CMAP parameter, client-side and/or server-side communication can be wrapped with SSL protocol. To use this filter, you need sslway and relevant PEM files placed at some directories in LIBPATH, typically at DGROOT/lib. See http://www.delegate.org/delegate/ssl/ for more details.

Example: relay between non-SSL client and SSL server

# delegated -P80 SERVER=http FSV=sslway MOUNT="/* https://server/*"
Example: relay between SSL client and non-SSL server
# delegated -P443 SERVER=https FCL=sslway MOUNT="/* http://server/*"

A DNS-DeleGate server relays host name data gathered from multiple sources including DNS, NIS and local file. It can provide limited type of resource records only; A, PTR, SOA and simplified MX. SOA record is composed with information of DNSCONF configuration.

Example: {NIS,FILE,DNS}/DNS gateway

# delegated -P53 SERVER=dns \


RESOLV=cache,file,nis DNSCONF=domain:my.domain

MX record for hostname is generated from -MX.hostname if it is given (like the example below), or the A record for hostname is used. Priorities among multiple MX records can not be represented in the current implementation.

Example: hosts table to use hostA as the MX of hostB

10.1.2.3 hostA
10.4.5.6 hostB, -MX.hostA

DNSCONF parameter*  ==  what:value

CUSTOMIZATION

The source of built-in data of DeleGate including icons and messages are at the source code directory "src/builtin/*". They are compiled into the executable file of DeleGate and are accessible as resources on a run-time DeleGate with URL "http://delegate/-/builtin/*". Those data can be replaced without recompiling DeleGate but by defining MOUNT for them. For example, the error message returned on forbidden access is at "http://delegate/-/builtin/mssgs/403-forbidden.dhtml", and it can be replaced by a MOUNT parameter like this:
MOUNT="/-/builtin/mssgs/403-forbidden.dhtml /tmp/forbidden.dhtml"

In this example, the MOUNT replaces only the forbidden message and the alternative data is a local file under "/tmp". But in general, a group of builtin-data can be replaced using wild-card (*) notation and alternative data can be placed at remote host which can be accessible via HTTP or FTP. For example, copy the whole of "src/builtin/" into "http://yourwww/delegate/builtin/" and MOUNT it like this:

MOUNT="/-/builtin/* http://yourwww/delegate/builtin/*"

Loading remote data will not suffer from overhead as long as cache is enabled, since MOUNTed built-in data are cached and reused like usual data.

Immediately after an occurrence of fatal signal, like SIGSEGV or SIGBUS, DeleGate stops serving to the client host which caused the fatal error, since the error could be a sign of a failed trial of intrusion. At the same time, to notify the incident, DeleGate will send a report mail to the administrator named in the ADMIN parameter.

Since the most typical method of attackers is buffer overflow on stack, expecting a target buffer resides at a certain address, randomizing stack address will be effective to decrease the probability of successful attack. And a failure of attack will cause a fatal error to be caught by DeleGate.

A suspicious client host will be shut out until a relevant file (under ADMDIR/shutout/) is removed, or the file is expired by TIMEOUT=shutout (30 minutes by default). For safety, TIMEOUT="shutout:0" (never timeout) is desirable not to give a second chance to the attacker. But as fatal errors are highly provably caused by usual bugs in DeleGate itself, it may be troublesome to be the default value...

Anyway you should be aware of following options if you are aware of preventing this kind of attacks, as well as access control configurations.

TIMEOUT=shutout:N [30m] ... shortest attack retrial interval

MAXIMA=randstack:N [32] ... randomize stack address

MAXIMA=randenv:N [1024] ... randomize enrironment variable

MAXIMA=randfd:N [32] ... randomize client's socket descriptor

CHROOT=dirPath ... restrict accessible file space

OWNER=user [nobody] ... restrict the ability of the DeleGate process

ADMIN=E-mail-address ... must be correct and SMTP-deliverable

-Tx [off] ... disable execve() system call

At the start up time, the original environment variables and command line arguments on stack area are moved to heap area and cleared not to be utilized for intrusion code by attackers. At the same time, a dummy environment variable named RANDENV with a value of random length (with maximum MAXIMA=randenv) is inserted to randomize addresses of environment variables to be inherited to child processes like filter programs and CGI programs.

Unix

Invocation from Inetd

Both "nowait" and "wait" status can be specified in inetd.conf. In "nowait" status, the DeleGate will processes just one request (session) and exits, thus is ineffective. In "wait" status, the DeleGate will process multiple requests; maximum count of request may be limited to N by "MAXIMA=service:N".

Privileged operations without being superuser

Some operations of DeleGate needs the privilege of super-user, but running whole DeleGate process under super-user's ability is not desirable for security. To solve the problem, you can execute DeleGate by normal user while executing a privileged operation by a small external program with "set user ID on execution" flag. Those external subsidiary programs are placed at DGROOT/subin/ by optional installation.

dgpam -- to do PAM authentication (AUTHORIZER)

dgchroot -- to do chroot(2) (CHROOT)

dgbind -- to do bind(2) to privileged ports (-P, SRCIF, FTP data, SOCKS server)

Windows

Starting as a service

On WindowsNT/2000, DeleGate automatically starts to run as a service (as a background process) by default, when invoked from the command prompt without -v or -f option. To stop and/or remove a DeleGate running as a service with -Pxxxx option, enter "delegated -Pxxxx" at the command prompt and answer to the simple query from the DeleGate. On Windows95/98, DeleGate runs as a foreground process only.

CYGWIN

Seems to have to be invoked by the Administrator.

OS/2

The optional loopback device (localhost) is necessary to be installed.

To make DeleGate restart gently without aborting ongoing sessions in child processes, and without changing the process ID of the DeleGate and holding its resources like entrance ports, send SIGHUP signal to the DeleGate process. This can be done in a platform independent way using -Fkill function like this:
delegated -Fkill-hup -Pport

Also restarting with SIGHUP can be done by remote HTTP clients at "http://delegate/-/admin/" using AUTH=admin parameter.

Restarting will be done after a configuration of DeleGate is changed. Parameters to be reloaded on restart must be given with +=parameters notation for parameter substitution. Other options (parameters) given as command line arguments will be inherited as is to the restarted DeleGate process.

Another purpose of restarting can be cleaning up of possible garbage or leaked resources like heap memory and file descriptors. For this purpose, DeleGate can be restarted periodically by TIMEOUT=restart or at each scheduled time by -restart action in CRON parameter.

Given a -Ffunction option, DeleGate runs to do the specified function which typically is a client-side action of a certain protocol. You can omit entering lengthy "delegated -F" by giving a file name "function" to an DeleGate executable file and just call it as function. The matching of function name is case-insensitive.

Command line options before -Ffunction and after "--" option is regarded as options for DeleGate rather than for the function, as delegated dgopt ... dgopt -Ffunc fopt ... fopt -- dgopt ... dgopt. As an exception, parameter option, in name=value format, is recognized as a parameter for DeleGate even if it appeared at fopt position.

Example: using DeleGate as a resolver

% delegated -Fresolvy www.delegate.org
% ln -s delegated Resolvy
% Resolvy www.delegate.org

The following is a list of major functions.

-Fhelp

put a list of available functions

-Fkill[-hup] -Pport

terminate (or restart) the DeleGate sending SIGTERM (or SIGHUP)

-Fcgi [DeleGateOptions]

run as a CGI program of an arbitrary HTTP server

-Fconnect host port[/udp] [XCOM=clientCommand]

like a telnet client, connect to the specified host:port and relay the standard I/O to/from it.

-Fresolvy {[-MX.]hostname | IPaddress[-num]}

like nslookup(8), resolve a given host name or IP address (can be a range as 10.10.10.1-128)

-Ffindu [-atime N] [-ls] [-du] [-rm] ... [dir]*

like find(1), find a file to apply a specified action. Usage will be shown by "delegated -Ffindu".
Example: doing "find . -ls" together with "du(1)"

delegated -Ffindu -ls -du

-Fdget [-h] [-o] [-eencoding] [PROXY=host:port] [MYAUTH=user:pass] URL

download a resource specified by URL, and put to standard output with "-o" option. With "-h" option, the header part of a HTTP response message will be put together.

-Ficp [-h server] URL

work as an ICP client. Usage will be shown by "delegated -Ficp".

-Fsched {"crontabSpec" | crontabFile | schedSpec}*

like cron(8), cause specified actions at specified timing.
Example: cause an action every 15 minutes

delegated -Fsched "0,15,30,45 * * * * /bin/date"

schedSpec is the canonical format of scheduling specification.

schedSpec == Wday:year:month:mday:Hour:Min:Sec:action

Example: cause an action every 15 seconds

delegated -Fsched "*:*:*:*:*:*:0,15,30,45:/bin/date"

-Fmd5 [infile]

output the MD5 digest of input data

-Fauth -{a|d|v} username[:password] hostname[:portnumber] [expire]

Add, delete or view predefined (or cached) authorization information for hostname as a server for AUTHORIZER. If hostname is prefixed with "-", it is regarded as a virtual name without a real server.
Example:

delegated -Fauth -a ken:blahblah -smtp.users.local
// and refer this as AUTHORIZER=-smtp.users.local

${DGROOT}/etc	-- persistent files mainly for configuration
${DGROOT}/lib	-- library files and scripts
${DGROOT}/adm	-- important log relevant to administration
${DGROOT}/log	-- log files which will grow up
${DGROOT}/work	-- for core dump
${DGROOT}/cache	-- for cached data
${DGROOT}/act	-- control info. of currently active DeleGate processes
${DGROOT}/tmp	-- volatile files which should be erased on shutdown

See the description of DGROOT parameter and Local file usage for more information.

du(1), ps(1), tee(1), cat(1), find(1), chroot(2), execve(2), getpeername(2), getsockname(2), pstat(2), ptrace(2), setgid(2), setuid(2), umask(2), scanf(3), strftime(3), system(3), YP(4), crontab(5), hosts(5), inetd.conf(5), cron(8), inetd(8), nslookup(8),
DNS(RFC1034), FTP(RFC959), Gopher(RFC1436), HTML(RFC1866), HTTP(RFC2068), ICP(RFC2186), Ident(RFC1413), IMAP(RFC2060), LDAP(RFC1777), LPR(RFC1179), MIME(RFC2045), NNTP(RFC977), POP(RFC1460), Socks(RFC1928), SMTP(RFC821), Telnet(RFC854), URI(RFC2396), URL(RFC1738), Wais(RFC1625), X(RFC1013)

Comments about DeleGate are expected to be directed to mailto:feedback@delegate.org to be open and shared at http://www.delegate.org/feedback/.

The latest version of DeleGate is available at the following location. <URL:ftp://ftp.delegate.org/pub/DeleGate/> in a tar+gzip format file named "delegate*.tar.gz".

Release 9.0.3             Last change: June 7, 2005

--------- --------- --------- --------- --------- --------- --------- ---------