Permission to use, copy, and distribute (via publically accessible on-line media) this material for any purpose and without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies. ETL 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.
--------- --------- --------- --------- --------- --------- --------- --------- DELEGATED(8) MAINTENANCE COMMANDS DELEGATED(8)
NAME
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.
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)
-P option -- entrance port(s) to the DeleGate
== -Pport[,port]*
port == [host:]portNum[/udp]
portNum == number[-number]
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
-v option -- logging level control
== -v[vdts]
-S option -- watch SIGCHLD signal
-T option -- trace system calls
== -T[xsdt]*
-F option -- extra function
== -Ffunction
-- option -- hiding command line arguments
parameter == name=value
-e option == -ename=value
In the following list, parameters marked with "*" are repeatable like name=value1 name=value2 ... name=valueN. If the same parameter is defined both in environment and command line, the one in command line precedes to the one in environment. If other non-repeatable names are repeated, the lastly given value is taken. Parameters marked with "+" can NOT be given in "+=parameters" scripts.
| 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
|
| * | CMAP | map-spec | mapping table about the current connection
|
| LIBPATH | dir:dir:... | search path for library 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
|
| -- | ---------- | ------------------ | ---------------------------------- |
| * | ROUTE | gateway-_-dst:src | forward to gateway 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 |
| TUNNEL | type:scriptPath | connect via the tunnel on serial line | |
| RPORT | {tcp|udp}[:host] | return port from the MASTER-DeleGate |
| -- | ---------- | ---------------- | ---------------------------------- |
| * | PERMIT | proto:dst:src | protocols/servers/clients to be permitted |
| 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 |
| RIDENT | client|server | forward socket addr. to upstream DeleGate |
| -- | ---------- | ------------------ | ---------------------------------- |
| * | MAXIMA | what:number | maxima of parallel sessions and etc. |
| * | TIMEOUT | what:seconds | timeout of connection and etc. |
| * | DELAY | what:seconds | delay for penalty |
| -- | ---------- | ------------------ | ---------------------------------- |
| 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 |
| -- | ---------- | ------------------ | ---------------------------------- |
| * | 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 |
| -- | ---------- | ------------------ | ---------------------------------- |
| * | CHARCODE | JIS|EUC|SJIS|UTF8 | character conversion for Japanese text |
| HTMLCONV | deent|enent|pre | decode/encode between HTML & plain text | |
| MIMECONV | thru|charcode | control MIME encoder/decoder |
| -- | ---------- | ------------------ | ---------------------------------- |
| FCL | filterCommand | filter between client and DeleGate | |
| FTOCL | filterCommand | filter from DeleGate to client | |
| FFROMCL | filterCommand | filter from client to DeleGate | |
| FSV | filterCommand | filter between server and DeleGate | |
| FTOSV | filterCommand | filter from DeleGate to server | |
| FFROMSV | filterCommand | filter from server to DeleGate | |
| FMD | filterCommand | filter between MASTER and this DeleGate | |
| FTOMD | filterCommand | filter from this DeleGate to MASTER | |
| FFROMMD | filterCommand | filter from MASTER to this DeleGate | |
| XCOM | filterCommand | execute a command as a server | |
| XFIL | filterCommand | execute a filter as a server |
| -- | ---------- | ------------------ | ---------------------------------- |
| + | 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 |
| -- | ---------- | ------------------ | ---------------------------------- |
| * | HOSTS | host/addr,... | private host/address mapping |
| RESOLV | file,nis,dns,sys | the order of resolvers to be used | |
| RES_CONF | URL | where resolv.conf is | |
| RES_NS | host[:port] | DNS server to be used | |
| RES_RR | HostList | enable Round Robin of IP-addresses | |
| RES_VRFY | "" | enable double check of reverse resolution | |
| RES_DEBUG | number | debugging level of name resolution |
| -- | ---------- | ------------------ | ---------------------------------- |
| * | HTTPCONF | what:conf | HTTP specific configuration |
| FILETYPE | suffix:fileType | mapping from filename to data type & etc. | |
| CGIENV | name,name,... | environment variables to be passed to CGI | |
| * | ICPCONF | icpServerConfig | configuration as an ICP server |
| * | NNTPCONF | what:conf | NNTP specific configuration |
| SMTPGATE | dirPath | SMTP to SMTP/NNTP g.w. configuration | |
| * | DNSCONF | what:conf | configuration as a DNS server |
SERVER parameter* == SERVER=protocol[://host[:portNum]][:-:MountOptions]
portNum == [+|-]number
-- default: none (act as generalist)
Example: a SERVER parameter for unbound Telnet-DeleGate
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.
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
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
Example: {NNTP,SMTP,POP}-DeleGate as a single server
ADMIN parameter == ADMIN=user@host.domain
-- default: built in at compile time
| - Shown in (error) messages to clients, as the name of
the administrator of this DeleGate
(HTTP, etc.). |
| - Shown in opening messages or in a help message to clients,
as the name of the administrator (FTP, NNTP, Telnet). |
| - Sent as a default user name (in PASS command)
on anonymous access to FTP servers. |
| - Sent as sender name (in FROM command)
in access to remote SMTP server on verification
by AUTH=anonftp:smtp-vrfy. |
| - Report messages are sent to the address on occurrence of fatal signals |
OWNER parameter* == OWNER=user[/group][:srcHostList]
-- default: OWNER="nobody/nogroup"
-- restriction: super-user only on most of Unix
Example: run with the user ID corresponding to the user name of the client
CRON parameter* == CRON="crontab-spec"
crontab-spec == minute hour day month dayOfWeek action
-- default: none
| -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
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)
CMAP parameter* == CMAP=resultStr:mapName:connMap
connMap == ProtoList:dstHostList:srcHostList
-- default: none
LIBPATH parameter == LIBPATH=dirPath[:dirPath]*
-- default: LIBPATH='.:${STARTDIR}:${LIBDIR}:${EXECDIR}'
DGPATH parameter == DGPATH=dirPath[:dirPath]*
-- default: DGPATH='+:.:${HOME}/delegate'
DGOPTS parameter == DGOPTS=opt[,opt]*
-- default: none
PORT parameter == PORT=port[,port]*
port == [host:]portNum[/udp]
portNum == number[-number]
-- default: none
ROUTE parameter* == ROUTE=proto://host:port/-_-dstHostList:srcHostList
-- default: none
A host specification in the dstHostList may be prefixed with "proto://" to restrict the protocol to be forwarded. For example, ROUTE="http://host:port/-_-{ftp://*}:*" means that only access to FTP servers are forwarded to the HTTP-proxy at "http://host:port/".
A host specification in the dstHostList can be restricted further with port number. For example, ROUTE="http://host:port/-_-{*:21}:*" means that only accesses to the port number 21 (FTP service) is forwarded to the proxy.
MASTER parameter* == MASTER=host:port[/masterControl][:dstHostList]
-- default: none
Optional "/masterControl" can be:
MASTERP parameter == MASTERP=[host:port]
-- default: none
RPORT parameter == RPORT={tcp|udp}[:host]
-- default: none
PROXY parameter* == PROXY=host:port[:dstHostList]
-- default: none
Example:
SOCKS parameter* == SOCKS=host[:[port][/-4][:dstHostList[:srcHostList]]]
-- default: none
Example:
SSLTUNNEL parameter == SSLTUNNEL=host:port
-- default: none
VSAP parameter == VSAP=host:port
-- default: none
Example:
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,d,v,s:*:*"
connType:
| cache | -- CACHE search (without connection) |
| icp | -- via a PROXY hinted by ICP server |
| master | -- via a MASTER-DeleGate server |
| https | -- via a SSLTUNNEL (SSL tunnel on HTTP) |
| vsap | -- via a VSAP server |
| direct | -- direct connection to the target server |
| socks | -- via SOCKS servers |
| udp | -- by UDP |
Each connection type can be abbreviated by the first character as
{c,i,m,d,v,s,u} respectively.
If ProtoList and dstHostList are given, this control is applyed only
to the protocols and hosts included in the lists. For example,
to use cached data in a host which is not connected to external networks,
specify as CONNECT="cache:*:!./@".
Note:
TUNNEL parameter == TUNNEL=tunnelType:script
tunnelType == tty7
-- default: none
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
PERMIT parameter* == PERMIT=connMap
connMap == ProtoList:dstHostList:srcHostList
-- default: none
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
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.
REMITTABLE parameter == REMITTABLE=ProtoList
-- default: REMITTABLE="*" for generalist
-- default: REMITTABLE="." for specialist
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. Currently, only "readonly" is supported as a method. For example, REMITTABLE="ftp//readonly" make a FTP-DeleGate be "read only" which inhibits uploading to FTP servers.
Protocol Specific Default:
Exception:
If the first member of a list is "+", it means the default list of permitted protocols. For example, REMITTABLE="+,-https/563,-wais,file" with SERVER=http means REMITTABLE="http,https/443,gopher,ftp,file".
REACHABLE parameter* == REACHABLE=dstHostList
-- default: REACHABLE="*" (any host is reachable)
RELIABLE parameter* == RELIABLE=srcHostList
-- default: RELIABLE=".localnet"
Note that multiple RELIABLE parameters like RELIABLE=Hosts1 RELIABLE=Hosts2 will be interpreted being simply catenated into a single RELIABLE="Hosts1,Hosts2", which will NOT mean "Hosts1 or Hosts2" if Hosts1 or Hosts2 includes some negation or composit 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 | no
connMap == ProtoList:dstHostList:srcHostList
-- default: RELAY="proxy,delegate:*:*:.localnet"
RELAY="proxy:*:*:*"
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
Default:
AUTH parameter* == AUTH=what:authProto:who
-- default: none
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 --
-- in FTP server and FTP/HTTP gateway --
-- in proxy and origin HTTP server --
| ident | -- Identification protocol [default] |
| pauth | -- Use Proxy-Authorization field "user@host:password" |
| auth | -- Use Authorization field "user@host:password" |
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[:connMap]
authServList == authServ[,authServ]* | & | *
authServ == authHost[/portNum]
authHost == hostName | hostAddr
connMap == ProtoList:dstHostList:srcHostList
-- default: none
-- restriction: applicable to Telnet, FTP and NNTP
If only authentication of user is necessary without authorization, the following special name will be useful as a authServList.
Example:
RIDENT parameter == RIDENT=ridentType[,ridentType]*
ridentType == client | server
-- default: none
Example:
MAXIMA parameter == MAXIMA=what:number,...
-- default: MAXIMA=listen:20,ftpcc:2,...
| randstack | -- | randomization range of stack base for security [32] |
| randenv | -- | randomization range of environment variables base [1024] |
| randfd | -- | randomization range of client socket file-descriptor [32] |
| listen | -- | max. size of the queue for entrance port [20] |
| delegated | -- | max. number of DeleGate processes runnable at a time [64] |
| ftpcc | -- | max. number of FTP connection cache servers to a host [16] |
| nntpcc | -- | max. number of NNTP connection cache processes to a host[16] |
| service | -- | max. number of services per delegated process [unlimited] |
| mailsplit | -- | max. size of of each partial mail [50000] |
| standby | -- | max. number of standby process [16] |
| http-cka | -- | max. number of connections in keep-alive [10] (*1) |
| http-ckapch | -- | max. number of connections in keep-alive at a time for each client host [4] |
| conpch | -- | max. number of connections at a time per client host [unlimited] |
(*1)Ten times larger value of "http-cka" is given to the first connection from each client host.
TIMEOUT parameter* == TIMEOUT=what:seconds,...
-- default: TIMEOUT=dns:60,acc:30,con:30,lin:30,...
| shutout | -- | disarming emergent shutout set on fatal error [900] |
| dns | -- | for DNS lookup [60] |
| acc | -- | for accept from client (include FTP data connection) [30] |
| con | -- | for connection to the server [30] |
| lin | -- | LINGER for output [30] |
| ident | -- | for connection to Ident server [10] |
| io | -- | general I/O (no data transmission) [600] |
| hello | -- | for HELLO negotiation with the MASTER [30] |
| login | -- | for login to proxy (Telnet,FTP) [60] |
| ftpcc | -- | for keeping alive FTP Connection Cache [900] |
| nntpcc | -- | for keeping alive NNTP Connection Cache [300] |
| daemon | -- | delegated [unlimited] |
| restart | -- | cause restart at every specified period [unlimited] |
| standby | -- | keep the delegated alive on standby for next client [30] |
| http-cka | -- | keep the connection with the client alive [5](*1) |
| takeover | -- | taking over a downloading to cache after disconnection [0](*2) |
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). (*1)the timeout is ten times longer for the first connection from each client host. (*2)after the disconnection of the client which initiated the downloading.
DELAY parameter* == DELAY=what:seconds
-- default: DELAY=reject:60,unknown:60,...
| reject | -- | continuous Reject resp. from self or MOUNTed servers [60] |
| unknown | -- | continuous Unknown resp. from self or MOUNTed servers [60] |
| reject_p | -- | continuous Reject resp. from origin server [0] |
| unknown_p | -- | continuous Unknown resp. from origin server [0] |
Each value specifies the maximum delay time and delay time increases according as the error count increases.
MOUNT parameter* == MOUNT="vURL rURL [MountOptions]"
-- default: MOUNT="/* SERVER_URL*"
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
This pattern matching can be restricted with a notation "[setOfCharacters]" prefixed before "*", like MOUNT="/abc/[a-z]* http://host/*", which matches with arbitrary strings starting with a character listed in "[setOfCharacters]".
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 vURL) can be prefixed with "-" or "+" to be determined dynamically by offsetting from the port number of the entransport, as in SERVER parameter.
MountOptions == option[,option]*
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.
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:
CONTROLS: The second group of options are to control the behaviors of DeleGate which are local to the MOUNT point.
URICONV parameter* == URICONV={convSpec|defElem|defAttr}
convSpec == convList:attrList
defElem == defelem:+,elemnameList
defAttr == defattr:+,attrnameList
-- default: it will be shown by URICONV=dump
| mount | -- | rewriting by MOUNT |
| normal | -- | normalize MOUNTed URL if it includes "../" in URL-path |
| partial | -- | represent (MOUNTed) URLs as partial URLs if possible |
| full | -- | convert all of URLs to full URLs |
The special convList URICONV="+" means loading the default URICONV configuration (no attrList in this case in the current implementation). The attrList is a list of attributes names each may be postfixed with an element name. A special attributes name "+" means the default set of attributes. An attribute prefixed with "-" character is excluded from the calculated set of attributes.
Example:
URICONV=mount,normal,partial:+ -- might be the default after Ver.6
URICONV=full:+,-HREF/BASE -- rewrite everything except HREF/BASE
URICONV=dump -- show the current URICONV config.
URICONV=+ URICONV=mount:-SRC/IMG URICONV=full:SRC/IMG
BASEURL parameter == BASEURL=URL
-- default: none
Example:
DELEGATE parameter == DELEGATE=gwHost:Port[:ProtoList]
-- default: DELEGATE=currentHost:currentPort
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
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=1d
CACHEFILE parameter == CACHEFILE=fileNameSpec
-- default: CACHEFILE='$[server:%P/%L/%p]'
| %P | -- | scheme | Protocol name part |
| %L | -- | host.d2.d1:port | Login part |
| %H | -- | host.d2.d1 | Host name |
| %T | -- | port | Port number |
| %h | -- | d1/d2/host | hierarchical host name directory |
| %d | -- | d1/d2 | hierarchical domain name directory |
| %1 | -- | d1 | top level domain |
| %2 | -- | d2 | second level domain |
| %p | -- | path | URL-path part |
| %Q | -- | host.d2.d1.d0 | use FQDN of a host name (like %Q%L or %Q%H) |
Another formatting pattern is "$[hash:format]" which
hashes a string generated by format into
hexadecimal value ranging from "00" to "ff".
This will be useful to divide a single huge directory containing all
servers into 255 small directories, which can be on physically
different disks.
Example:
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
| s | -- the ICP server is a "sibling" [default] |
| p | -- the ICP server is a "parent" |
| l | -- the ICP server is a "listener" which never respond |
| n | -- the ICP server is a navigation proxy |
| o | -- require HIT_OBJ response |
| H | -- the object server is a HTTP proxy [default] |
| D | -- the object server is a MASTER-DeleGate. |
| O | -- the object server is an origin server. |
| timeout/N | -- period to wait response as an ICP client (in seconds)[2.0] |
| parent | -- mark the default type of icpServers as "parent" |
| listener | -- mark the default type of icpServers as "listener" |
| hitobj | -- enable HIT_OBJ for all icpServers by default |
| Origin | -- object servers are origin server |
| DeleGate | -- object servers are DeleGate |
Example:
ICP="host0"
ICP="host0//8080/3130"
ICP="host0::8080:3130"
ICP="host1:timeout/1.0:::http,ftp:!*.my.domain:*.my.domain"
ICP="host1,host2/O/80/13130:timeout/2.0:8080:3130"
CHARCODE parameter == CHARCODE=[inputCode/]outputCode
outputCode == charCode
charCode == JIS | EUC | SJIS | UTF8
-- default: none
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
| deent | -- | decode entity symbol |
| enent | -- | encode entity symbol |
| fullurl | -- | convert all of URLs to full URLs (equals to URICONV="full:+,-HREF/BASE") |
"deent" and "enent" control encoding and decoding of special
characters between HTML and plain text
("<" to/from "<" for example)
when such characters appear in a text of
multi-byte charset (like ISO-2022-JP).
If "deent" is specified, encoded entity symbol appearing
in multi-byte charset text will be decoded.
This may be useful to recover a text
including characters indiscriminately encoded by
encoder which does not care multi-byte characters.
If "enent" is specified then entity symbols appearing
out of multi-byte charset text will be encoded.
This may be useful in case of NNTP-DeleGate to be accessed by
WWW client.
If empty list is specified, any conversion is disabled.
MIMECONV parameter == MIMECONV=mimeConv[,mimeConv]
mimeConv == thru | charcode
-- 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
-- default: none
Filters can be applied conditionally using CMAP based on circuit level information, or using CFI script based on application level information.
BUILT-IN FILTERS: if a filterCommand is prefixed with "-", then it is a filter built-in to DeleGate.
XCOM parameter == XCOM=filterCommand
XFIL parameter == XFIL=filterCommand
-- default: none
On WindowsNT and OS/2, commands executed as XCOM will be given a environment variable "SOCKHANDLE_CLIENT" which have the handle value of the inherited socket connected to the client.
CHROOT parameter == CHROOT=dirPath
-- default: none
-- restriction: super-user only on most of Unix
DGROOT parameter == DGROOT=dirPath
-- default: on Unix: '${HOME}/delegate' or
'/var/spool/delegate-${OWNER}' or
'/tmp/delegate-${OWNER}'
on Windows: '/Program Files/DeleGate'
SHARE parameter == SHARE=dirPatternList
-- default: empty
Example:
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'
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'
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.
LogFilename and dirPath Substitution for Aging
Example: aging a log file day by day and rotate by a month
Example: make log directory hierarchical by date
The latest LOGFILE will be pointed with another file name (hard link to it) which name is made by omitting "[date+format]" parts from LOGFILE specification. For example, by the LOGFILE specification in the above example, logfile will be named like "log/aged/00/12/31/80.http" while the latest one is given another name "log/80.http".
Another pattern for aging is "[start+format]" which will be evaluated in the same way with "date+" except that it will be substituted by the time when the DeleGate started (or restarted by SIGHUP or specified TIMEOUT=restart).
EXPIRELOG parameter == EXPIRELOG=LogFilename
-- default: EXPIRELOG='${LOGDIR}/expire.log'
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 == cache | file | nis | dns | sys
-- default: RESOLV=cache,file,nis,dns,sys
| cache | -- means cached result from following resolvers |
| file | -- means local hosts(5) file usually located at /etc/hosts, |
| nis | -- means hosts map on NIS or YP(4) service, |
| dns | -- means DNS service, and |
| sys | -- means using gethostbyname(2) and gethostbyaddr(2) which usually call system's standard resolver of the host. |
| cache:/path | -- path name of cache directory [$TMPDIR/resolvy] |
| file:/path | -- path name of password file [/etc/hosts] |
| nis:nisDomain | -- NIS domain name [default domain] |
| dns:dnsHost | -- DNS server and default domain |
RES_CONF parameter == RES_CONF=URL
-- default: RES_CONF="file:/etc/resolv.conf"
or from registry (on Windows)
RES_NS parameter == RES_NS=dnsServer[//socksV5Host]
-- default: depend on RES_CONF
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 == [!]hostSpec[,HostList]
hostSpec == [{userList}@]hostSpec[/netMask]
userList == userNamePattern[,userNamePattern]*
hostSpec == hostNamePattern | hostAddrPattern
userNamePattern == [*]uname[*]
hostNamePattern == [*]hname[*]
hostAddrPattern == IPaddressPattern | IPrange
netMask == IPaddress | maskLength
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, ..."
Example: inhibit access from unknown hosts or from unknown users
Example: conditional filtering using CMAP
Example:
Example:
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 ...
Substitution resources will be reloaded when the DeleGate restart receiving a SIGHUP signal or by "-restart" action in CRON parameter.
Another substitution is in the form "name=-=URL" which loads the content of URL into a temporary file on local file system (under ACTDIR), then the parameter is rewritten to "name=/path/of/temporary-file". This will be useful when you wish to pass remote resources to CGI or CFI programs, like "-eCONFIGDATA=-=http://server/configData", then those programs will be given an environment variable named CONFIGDATA of which value is a temporary file name containing the content of "http://server/configData".
CFI AND CFI SCRIPT
filterName="filterSpec"
CMAP="filterSpec":filterName:connMap
filterName == FCL | FTOCL | FFROMCL |
FSV | FTOSV | FFROMSV |
FMD | FTOMD | FFROMMD
filterSpec == filterCommand | CFIscriptName
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 bidrectional 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 filter can be applied conditionally based on circuit level information, using CMAP parameter like follows:
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.
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.
When the header ruleName is "Filter", "CGI", or "Header-Filter", exceptionally they specifies an action (or filtering) to be applied to the input data. For filters of "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:".
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 filed into the header. "Remove/ruleName:ruleBody" indicates removing header fields with name ruleName and body matches to ruleBody.
Example: rewriting HTTP response messages
[content of test.cfi]
#!cfi
Content-Type: text/html
Filter: sed 's/string1/string2/'
--
Content-Type: image/jpeg
Output/Content-Type: image/gif
Filter: jpeg2gif
PROXYING BY URL REDIRECTION
U->C:
user opens http://delegate/-_-http://www/path1
C->D: GET /-_-http://www/path1
D->S: GET /path1
D<-S: HREF=/path2
C<-D: HREF=http://delegate/-_-http://www/path2
U->C: user clicks the anchor
C->D: GET /-_-http://www/path2
D->S: GET /path2
S->D: HREF=ftp://ftp/path
D->C: HREF=http://delegate/-_-ftp://ftp/path
Originally, this redirection mechanism was implemented for Gopher proxy, and extended to HTTP protocol, then extended to a generic MOUNT mechanism. Now almost the same effect with "-_-" redirection can be emulated with a MOUNT parameter like follows, allowing to replace "-_-" with an arbitrary string.
You can write a DeleGate switching table in HTML. Suppose that you have two DeleGate hosts connected to different network provider each other, and you want to select one of them explicitly but without changing configuration of your browser and without typing a lengthy URL prefixed with "http://delegate/-_-". You can write a table in HTML to switch DeleGate like this:
This table works independently of if the client is using DeleGate or not, because DeleGate does not do URL redirection in response message described above if the URL is already redirected like above.
Right after the -_- mark, optional "/Modifier/" form can be inserted as follows:
Common Notation
TCPrelay
Example: two proxies on TCP with similar function
UDPrelay
Example: two proxies on UDP with similar function
Socks server
Example: Socks-DeleGate
HTTP proxy/server
Then use this DeleGate from your client on the internal host, specifying "firewall:8080" as the proxy for HTTP, HTTPS (Security), FTP, Gopher, Wais, and so on.
Example: cascaded DeleGate as an HTTP proxy
Run a generalist DeleGate on the firewall which only accepts request from internal host, then run a specialist on internal which use the generalist on firewall host. A generalist can be shared as an upstream DeleGate from multiple DeleGates of arbitrary protocol.
Example: DeleGate as an origin HTTP server
A file with a name with ".cgi" extension is treated as a CGI script.
Also you can use arbitrary name of CGI scripts under a specified
directory with a MOUNT like:
MOUNT="/xxx/* cgi:/path/of/cgi-bin/*"
Example: DeleGate as a CGI program
HTTP Transfer Log Format
| %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 filed in the request message |
| %S | -- status of CONNECTion to the server (c,m,p,d,s,v) |
HTTPCONF parameter == what:conf
-- default: welcome.dgp,welcome.shtml,welcome.html,...
Example:
FILETYPE parameter == suffix:gopherType:altText:iconName:contentType
-- default: FILETYPE=".txt:0:TXT:text:text/plain"
FILETYPE=...
Example:
FILETYPE=".txt:0:TXT:text:text/plain"
FILETYPE=".gif:g:GIF:image:image/gif"
CGIENV parameter == CIGENV=name[,name]*
-- default: CGIENV="*"
MountOptions for HTTP-DeleGate
CONTROLS:
Example:
MOUNT="http:* = method=POST,asproxy,useproxy"
MOUNT="http:* = withquery,asproxy,useproxy"
Example:
| %u | -- user name got using Ident protocol |
| %h | -- host name of the client got from the socket |
| %i | -- host name of the network interface to the client |
| %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: userame:password |
| %P | -- password part of client's [Proxy-]Authorization: userame:password |
Example:
A generated password is formatted as "passWord/%i" and a DeleGate rejects incoming requests with an Authorization field of such pattern. Thus forged password cannot pass the DeleGate on the host "%i".
Example:
| %F | -- E-mail address in From field |
| %L | -- local part of From: local@domain field |
| %D | -- domain part of From: local@domain field |
| %U | -- username part of Authorization: userame:password |
| %P | -- password part of Authorization: userame:password |
| %Q | -- "for clientFQDN" part of Forwarded: field |
Example:
firewall% delegated AUTH="fromgen:%u@%h" ...
internal% delegated AUTH="log:%D/%h:%L/%u:%U" ...
Configuration of DeleGate by Users
Example: MOUNTing news serverN at http://delegate/news/servN/
(This mechanism should be applied to other protocols like FTP...)
Server Side Include in SHTML files
SSI tags
META tags
ICP proxy/server
Example: a couple of ICP and HTTP DeleGates sharing a CACHEDIR
Example: an ICP proxy merging multiple upstream ICP servers
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,...
| para:N | -- the number of parallel ICP-DeleGate servers [2] |
| hitage:N | -- valid age of cached data to be notified as HIT [1d] |
| hitobjage:N | -- valid age of cached data to be sent by HIT_OBJ [1h] |
| hitobjsize:N | -- max. size of cached data by HIT_OBJ [1024](bytes) |
| timeout:N | -- default timeout of waiting response [2.0](seconds) |
| debug:N | -- the level of log for debug [0] |
FTP proxy/server
Example: proxy FTP-DeleGate
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:Example: cascaded FTP-Proxy
Example: FTP MOUNT with filtering, merging and aliasing
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
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
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".
FTP Transfer Log Format
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:
Telnet proxy/server
Example: proxy Telnet-DeleGate
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
POP proxy
Example: proxy POP-DeleGate
external% telnet firewall pop
+OK Proxy-POP server (DeleGate6.1.0) at firewall starting.
USER username@servername
...
USER username%servername is also available.
Example: POP MOUNT
MOUNT="//* ="
... don't rewrite if a server is specified by the user
MOUNT="* pop://defaultHost/*"
... specify default POP server
MOUNT="user1 pop://host1/*"
... let the "host1" be the server of "user1"
MOUNT="//pop2/* pop://host2/*"
... hide real hostname "host2"
Example: NNTP server to POP client gateway
Clients are expected to send a newsgroup name as a user name.
Example: POP server to HTTP client gateway
This DeleGate provides mailboxes in POP server (at mailHost by default) to HTTP clients. Clients accessing to "http://firewall/mail/" are required to enter Username and Password for POP server at mailHost as authorization information on HTTP. If Username is in the form "user@mailHost2", not mailHost but mailHost2 is accessed as a target POP server. Each mailbox of User at Host server is named as "http://firewall/mail/+pop.User.Host", thus you can directly specify User and Host in URL.
IMAP proxy
external% telnet firewall imap
* OK external Proxy-IMAP server DeleGate/6.1.15
C001 LOGIN username@servername
...
LOGIN username%servername is also acceptable.
SMTP proxy/server
Example: proxy SMTP-DeleGate
SMTPGATE parameter == SMTPGATE=dirPath
-- default: '${ETCDIR}/smtpgate'
Example: SMTP to SMTP forwarding
delegate.org# delegated -P25 SERVER=smtp
[the contents of SMTPGATE/users/feedback/conf]
Example: SMTP to NNTP forwarding
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.
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.
If no configuration for the recipient is found, then the default configuration is used if it exists at the following directory.
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.
The directory for each recipient contains following files.
Instead of the default archive file, user can define the file name and the unit of archive by ARCHIVE directive.
Example:
NNTP proxy/server
Example: Filtering
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
Example: merge multiple NNTP servers with authentication (by AUTHINFO)
Example: mount selected group(s)
Example: POP server to NNTP client
Example: NNTP server to HTTP client
Example: origin NNTP-DeleGate
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
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
LDAP proxy
Example: proxy LDAP-DeleGate
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).
Whois proxy
X proxy
Example: relaying to two displays on a single server host
Example: relaying to two server hosts
Gopher proxy
internal% gopher firewall 8070
internal% gopher -p -_-gopher://gopher.tc.umn.edu firewall 8070
SSL proxy
Example: relay between non-SSL client and SSL server
DNS (Domain Name System) proxy/server
DNSCONF parameter* == what:value
| para:N | -- the number of parallel server process [2] |
| domain:FQDN | -- [domain name of the host of DeleGate] |
| origin:FQDH | -- [host name of the host of DeleGate] |
| admin:Email | -- the mail address of the administrator [ADMIN] |
| serial:N | -- serial number [%Y%m%d%h of the last configuration change] |
| refresh:period | -- refresh interval [6h] |
| retry:period | -- retry interval [10m] |
| expire:period | -- expire period [14d] |
| minttl:period | -- minimum ttl [6h] |
CU-SeeMe proxy
RESERVED NAMES
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:
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.
DEFENSE AGAINST ATTACKERS
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 provability 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 (15 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.
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.
GENTLE RESTART
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.
Example: using DeleGate as a resolver
The following is a list of major functions.
FILES
| ${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.
AUTHOR
@ @ ( - ) _< >_Yutaka Sato <ysato@delegate.org>
Author's Note:
This is the first effort to write a document which is worth to be
called a reference manual of DeleGate
reflecting the up to date specification of DeleGate/6.1.
Although it is still so incomplete,
at least it is much better than former "Manual.txt"
which has been just a pile of memorandums without review
since the start of its development in six years ago
lacking overall consistency.
DISTRIBUTION
Release 6.1.18 Last change: September 5, 2000 --------- --------- --------- --------- --------- --------- --------- ---------