PageViews: 73,665 hits / 262 nets |
home | updates | download | manual | documents | feedback | search | ITS more |
|
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.
This document is written based on the latest version of DeleGate version 9.X, and partially on version 10.X. Comments about this document are expected to be directed to mailto:feedback@delegate.org to be open and shared at http://www.delegate.org/feedback/. Watch DeleGate Home Page at http://www.delegate.org/ to see the latest status. Beginners are recommended to read a short tutorial at http://www.delegate.org/delegate/tutorial/ also. A collection of usage examples at http://www.delegate.org/delegate/HowToDG.shtml might be helpful to see what you can do with DeleGate. A list of related documents is at http://www.delegate.org/documents/.
PERMUTED INDEX
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
FTPxHTTP
X
YYsh
YYMUX
INDEX
-F
-P
-Q
-f
-r
-v
-d
-D
ADMIN
AF_LOCAL
Aging
AUTH
AUTHORIZER
BASEURL
CACHE
CACHEFILE
CAPSKEY
CERTDIR
CGIENV
CHARCODE
CHARMAP
CHOKE
CHROOT
CLUSTER
CMAP
CONNECT
COUNTER
COUNTERDIR
CRON
DATAPATH
DELAY
DELEGATE
DGCONF
DGOPTS
DGPATH
DGROOT
DGSIGN
DNSCONF
DYCONF
DYLIB
EXPIRE
FCL
FFROMCL
FFROMMD
FFROMSV
FMD
FSV
FTOMD
FTOSV
FILETYPE
FORWARD
FTOCL
FTPCONF
HOSTLIST
HOSTS
HTMLCONV
HTMUX
HTTPCONF
ICP
ICPCONF
INETD
LDPATH
LIBPATH
LOGDIR
LOGFILE
MASTER
MASTERP
MAXIMA
MIMECONV
MOUNT
MountOptions
MYAUTH
NNTPCONF
OWNER
PERMIT
PORT
PROTOLOG
PROXY
REACHABLE
REJECT
RELAY
RELIABLE
REMITTABLE
RESOLV
RES_AF
RES_CONF
RES_DEBUG
RES_NS
RES_RR
RES_VRFY
RES_WAIT
RIDENT
ROUTE
RPORT
SCREEN
SERVER
SHARE
SMTPCONF
SMTPGATE
SockMux
SOCKOPT
SOCKS
SOCKSTAP
SOXCONF
SOCKMUX
SRCIF
SSLTUNNEL
STLS
SYSLOG
TIMEOUT
TLSCONF
TUNNEL
UMASK
URICONV
VSAP
XCOM
XFIL
YYCONF
YYMUX
TCPrelay
UDPrelay
SockMux
Socks
DGAuth
PAM
HTTP
SSI.shtml
ICP
FTP
Telnet
POP
IMAP
SMTP
NNTP
LDAP
Whois
X
Gopher
SSL
DNS
CU-SeeMe
--------- --------- --------- --------- --------- --------- --------- --------- 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. 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) (see DGCONF also)
OPTIONS
-P option -- entrance port(s) to the DeleGate
== -Pport[,port]*
port == [host:]portNum[/udp][/admin][/protocolName]
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.
If "/protocolName" is specified, as "-P21/ftp,80/http,1080/socks" for example, the DeleGate will act in the specified application protocol on the specified port, rather than in the default protocol specified in the SERVER parameter.
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".
-Q option* -- entrance port to the DeleGate == -Qport
-f option -- foreground execution == -f[v]
-r option -- restart
-v option -- logging level control == -v[vdtsau]
-d option -- debugging of sub components == -d[hst]
-D option -- disabling sub components == -D[t]
-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
conditional parameter == (condition)parameter
-e option == -ename=value
PARAMETERS
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. Those parameters (including DGROOT, CHROOT, LDPATH, and DYLIB) need to be specified in command-line arguments or "implanted" into the executable file of DeleGate with the -Fimp option.
General
Routing
Access control
Resource usage restriction
Cache control
Mount
Data conversion
Filter control
Local file usage
Host name resolution
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
*
CLUSTER
protocol:hostList
define a cluster of servers
*
CMAP
map-spec
mapping table about the current connection
+
DYLIB
patternList
file-name patterns of dynamic libraries
+
LDPATH
dir;dir;...
search path for DYLIB
LIBPATH
dir:dir:...
search path for library files
DATAPATH
dir:dir:...
search path for data files
DGPATH
dir:dir:...
search path for SUBSTITUTION resources
*
DYCONF
conditions:path
dynamic configuration based on request
DGCONF
dir/file
the file of configuration parameters
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
*
YYMUX
host[:port]
connect via the YYMUX server
*
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
*
SCREEN
{reject|accept}
screen client host
*
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
These parameters can be useful where available resources are
in severe condition; when the host of DeleGate is heavy loaded,
network bandwidth is narrow, or response from server can be slow.
--
----------
------------------
----------------------------------
*
MAXIMA
what:number
maxima of parallel sessions and etc.
*
TIMEOUT
what:seconds
timeout of connection and etc.
*
DELAY
what:seconds
delay for penalty
*
CHOKE
Delay:Clnt:UA:Ref
choking robots
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
Parameters to control built-in converter for text type data.
--
----------
------------------
----------------------------------
*
CHARCODE
JIS|EUC|SJIS|UTF8
character conversion for Japanese text
*
CHARMAP
[jis|ucs]:a-z/A-Z
map character to character in text data
HTMLCONV
deent|enent|pre
decode/encode between HTML & plain text
MIMECONV
thru|charcode
control MIME encoder/decoder
Insert a filter program on the way to/from client or server
to convert data transmitted between them.
--
----------
------------------
----------------------------------
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
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
ADMDIR
dirPath
where dynamic administration files are
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
COUNTERDIR
dirPath
base directory of counters
COUNTER
CounterOptions
access counters
Resolve host name to/from IP address using DNS, NIS or local file.
Protocol specific
--
----------
------------------
----------------------------------
*
HOSTS
host/addr,...
private host/address mapping
RESOLV
file,nis,dns,sys
the order of resolvers to be used
RES_WAIT
sec:host
wait for resolver to be ready
RES_CONF
URL
where resolv.conf is
RES_NS
host[:port]
DNS server to be used
RES_AF
46 | 64 | 4 | 6
Address families (IPv4/v6) to be retrieved
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
*
FTPCONF
what[:conf]
FTP specific configuration
*
NNTPCONF
what:conf
NNTP specific configuration
*
SMTPCONF
what:conf
SMTP specific configuration
SMTPGATE
dirPath
SMTP to SMTP/NNTP g.w. configuration
*
DNSCONF
what:conf
configuration as a DNS server
*
SOCKSTAP
proto[:[dst][:src]]
interpret the protocol over SOCKS
SERVER parameter* == SERVER=protocol[://host[:portNum]][:-:MountOptions]
portNum == [+|-]number
-- default: SERVER=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 omittable as usual in URL
if the number is that of standard port number of the protocol.
A list of protocols and standard port numbers recognized by
the DeleGate is available at:
"http://delegate/-/builtin/mssgs/config.dhtml".
Port mapping:
If a portNum is prefixed with "-" or "+",
it means mapping the port number of the entrance port
adding the specified offset,
or using the port number as is by "-" with empty portNum.
Example: forwarding multiple ports to an another host
A special hostname "odst.-" can be used
to refer the original destination host when the incoming data is
forwarded by NAT.
Example: forwarding NAT to the original destination via a SOCKS proxy
-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
Example: {NNTP,SMTP,POP}-DeleGate as a single server
Example:
run with the user ID corresponding to the user name of the client
On Windows, OWNER=user may be specified when it is
invoked as a service, to set the user of the DeleGate service to be created.
With empty user name as OWNER="", the user name is got from
the USERNAME environment variable. The password can be specified
with a PASS=pass parameter or an environment variable, or
it will be asked on the console.
Example:
Example:
Example:
If a list is prefixed with "/R", the servers in the list are tried
in random order (the first server to be tried is selected randomly and
other servers are tried in the round-robin order).
It could be useful for load balancing among equivalent (proxy) servers.
The retrial by this parameter is commonly applied to servers of any protocols
in the phase of establishment of a TCP connection to a server.
The retrial covers the authentication phase for several protocols.
In HTTP origin/gateway servers, the retrial may be caused depending on
the response from the server, including the response code 503
(Service Unavailable) and 404 (Not Found) for example.
Example:
If "fcl" is specified, a client may start SSL without STARTTLS negotiation.
Such implicit SSL negotiation from the client-side is detected by peeping
a SSL hand-shake packet on the connection from the client-side at the
beginning of a session for a certain period specified with imimSec.
The default value is "im0.25" (250m seconds).
"-im" disables this implicit SSL negotiation.
If a stlsSpec is followed with "/im" as STLS="fsv/im" for example,
SSL with the peer (with the server in this case) is applied without
the STARTTLS negotiation.
If "mitm" is specified, it behaves like "-fcl,-fsv" that is
if SSL is enabled in the client side then SSL on the server side is enabled.
It can be used with a HTTP proxy DeleGate as a "secure proxy" or "SSL-tunnel"
to peep the bidirectional communication in CONNECT method,
relaying it as a usual HTTP applying filters and cache.
("mitm" means "Man-In-The-Middle" mode)
If it is set optional as "STLS=-mitm" then the MITM mode is activated
only when the client specified the server name prefixing with "-mitm."
as "https://-mitm.host.domain/" for "https://host.domain/".
ADMIN parameter == ADMIN=user@host.domain
-- default: built in at compile time
This parameter must be correctly given especially when the DeleGate runs on
a host directly reachable to/from internet.
This E-mail address will be used as follows:
- Shown in (error) messages to clients, as the name of
the administrator of this DeleGate
(HTTP, etc.).
- Shown in opening messages or in a help message to clients,
as the name of the administrator (FTP, NNTP, Telnet).
- Sent as a default user name (in PASS command)
on anonymous access to FTP servers.
- Sent as sender name (in FROM command)
in access to remote SMTP server on verification
by AUTH=anonftp:smtp-vrfy.
- Report messages are sent to the address
on occurrence of fatal signals
OWNER parameter* == OWNER=user[/group][:srcHostList]
-- default: OWNER="nobody/nogroup"
-- restriction: super-user only on most of Unix
-- restriction: setting the user of a service on Windows
This parameter is effective only when the invoker is a super-user.
If specified, the DeleGate will run with the right of specified
user, calling setuid(2) and setgid(2) system calls. User and group
can be specified either in symbolic name or in id-number prefixed
with "#" like "#1234".
If srcHostList is specified, owner of this DeleGate will be set to
the user when the client host is included in the list. The user
name "*" will be substituted by the user name of the client when
it can be got from an
Identification server on the client host.
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"
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:
these ADMIN and EXPIRE parameters are inherited to DeleGates
described in conf1 and conf2.
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.
CLUSTER parameter* == CLUSTER=[protoList]:ServerList
ServerList == [/R,]Server[,ServerList]
Server == Host[..Port]
The CLUSTER parameter defines an ordered set of alternative or
complemental servers (origin or proxy).
It is referred when DeleGate failed to connect or authenticate with
an upstream proxy server or an origin server.
It is applied to proxy server specified in
MASTER, PROXY, SSLTUNNEL, SOCKS,
or an origin server specified in SERVER or
in the right-hand of MOUNT.
CMAP parameter* == CMAP=resultStr:mapName:connMap
connMap == ProtoList:dstHostList:srcHostList
-- default: none
A generic parameter to make some parameters be conditional on the current connection.
When the protocol, the destination and the source
of the current connection match the connMap,
this map is enabled providing resultStr string
to be used for mapName.
Not only host name/address but also port number of destination servers
can be used for matching in dstHostList.
A typical usage of this parameter is for applying
filter conditionally.
TLSCONF parameter* == TLSCONF=tlsConf[,tlsConf]*
tlsConf == what:value
-- default: TLSCONF=scache:do,xcache:do
STLS parameter* == STLS=stlsSpecs[,sslwayCom][:connMap]
stlsSpecs == [-]stlsSpec[/im][/ssl][,stlsSpecs]
stlsSpec == fsv | fcl | mitm | imimSec
sslwayCom == {sslway [-Vrfy] [-CApath dir] ...}
connMap == ProtoList:dstHostList:srcHostList
-- default: none
-- restriction: applicable to HTTP, FTP, SMTP, POP, IMAP, SOCKS
-- required: SSLway
This parameter controls the initiation of SSL (TLS) based on a negotiation
between client and server in each application protocol.
The common scheme of the negotiation is known as "STARTTLS".
"fsv" specifies using SSL with server and "fcl" specifies using SSL with client.
When SSL is not supported on a connection, the STARTTLS negotiation will fail
and the connection will be closed by default.
To continue a session even when SSL is not available,
prefix "-" to "fsv" or "fcl".
If 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:
CERTDIR parameter == CERTDIR=dir -- default: ${ETCDIR}/certs -- version: DeleGate/9.8.0 + OpenSSL0.9.8g or laters
DGCONF parameter == DGCONF=dir/file -- default: DGCONF='${EXECDIR}/${EXECNAME}.conf'
DYCONF parameter* == DYCONF=[conditions]parameters parameters == file:path | cgi:path | arg:{listOfParameters} -- default: none
A condition for loading can be based on the identity (address or name) of the host of a client which is requesting over the new connection. Or it can be based on the content (sub-string or pattern) of the initial request data which is sent from a client over a connection. The request data is polled for a specified period (15sec. by default) and peeked by a specified size (4K bytes at max. by default).
Conditions:
Example:
DYLIB parameter == DYLIB=libfilePattern[,libfilePattern]* -- default: DYLIB='dglib*.so,lib*.so,dglib*.dylib,lib*.dylib'
Example:
LDPATH parameter == LDPATH=dirPath[;dirPath]* -- default: LDPATH='${LIBDIR};${EXECDIR};${HOME}/lib;/usr/lib;/lib'
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:${EXECDIR}:${ETCDIR}'
DGSIGN parameter == DGSIGN=signatureSpec -- default: DGSIGN="V.R.P/Y.M.D"
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://[user:pass@]gwhost[:gwport] connMap == protoList:dstHostList:srcHostList -- default: none
For special gwproto, FORWARD works as a generalized notation of MASTER, PROXY, SOCKS and SSLTUNNEL as follows.
If multiple FORWARD parameters are specified, they are tried in the order of the definition. If multiple routes to the destination server are available, specified with a mixture of FORWARD and other parameters (MASTER, PROXY, SOCKS or SSLTUNNEL), the route defined by FORWARD is tried in precedence defined by "proxy" or "master" in CONNECT.
Example: a gateway for HTTP clients to a HTTPS server reachable via SSLtunnel with authentication
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 -- restriction: applicable to HTTP, FTP, Telnet
Example:
SOCKS parameter* == SOCKS=host[:[port][/socksOpt][:dstHostList[:srcHostList]]] socksOpt == [ -4 | -r ]* -- default: none
Example:
SSLTUNNEL parameter == SSLTUNNEL=host:port -- default: none
VSAP parameter == VSAP=host:port -- default: none
Example:
YYMUX parameter* == YYMUX=host[:port][:connMap] connMap == ProtoList[:dstHostList[:srcHostList]] -- default: none
YYCONF parameter* == YYCONF=name[:value] -- default: none
CONNECT parameter* == CONNECT=connSeq[:connMap] connSeq == connType[,connType]* connType == cache|icp|proxy|master|https|vsap|direct|socks|udp connMap == ProtoList[:dstHostList[:srcHostList]] -- default: CONNECT="c,i,m,h,y,v,s,d:*:*:*"
connType:
cache | -- CACHE search (without connection) |
icp | -- via a PROXY hinted by ICP server |
proxy | -- via a PROXY server |
master | -- via a PROXY or a MASTER-DeleGate server |
https | -- via a SSLTUNNEL (SSL tunnel on HTTP) |
yymux | -- via a YYMUX server |
vsap | -- via a VSAP server |
direct | -- direct connection to the target server |
socks | -- via SOCKS servers |
udp | -- by UDP |
None | -- don't connect |
Each connection type can be abbreviated by the first character as
{c,i,m,d,v,s,u} respectively.
If ProtoList and dstHostList are given, this control is applied only
to the protocols and hosts included in the lists. For example,
to use cached data in a host which is not connected to external networks,
specify as CONNECT="cache:*:!./@".
Note: In current implementation, "cache" will be tried first anyway if it is included in the connSeq.
A combination of -Pport with CONNECT=udp relays from TCP client to UDP server, and -Pport/udp with non-udp CONNECT relays from UDP client to TCP server.SRCIF parameter* == SRCIF=host[:[port][:connMap]] connMap == ProtoList:dstHostList:srcHostList -- default: SRCIF="*:*:*:*:*"
This parameter 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:
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
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
Example: make a tunnel with login dialogue 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
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.
REJECT parameter* == REJECT=connMap connMap == ProtoList:dstHostList:srcHostList -- default: none
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. 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:
Exception:
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)
RELIABLE parameter* == RELIABLE=srcHostList -- default: RELIABLE=".localnet"
Note that multiple RELIABLE parameters like RELIABLE=Hosts1 RELIABLE=Hosts2 will be interpreted being simply concatenated into a single RELIABLE="Hosts1,Hosts2", which will NOT mean "Hosts1 or Hosts2" if Hosts1 or Hosts2 includes some negation or composite operators. You are recommended to use multiple PERMIT parameters instead if you are not sure what does these mean.
RELAY parameter* == RELAY=relayTypeList[:connMap] relayTypeList == relayType[,relayType]* relayType == proxy | delegate | vhost | no | nojava | noapplet connMap == ProtoList:dstHostList:srcHostList -- default: RELAY="delegate,nojava:*:*:.localnet" RELAY="vhost,nojava:http:{*:80}:.localnet" RELAY="proxy:*:*:*"
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:
Default:
SCREEN parameter == SCREEN={reject|accept} -- default: none
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 --
A DeleGate of arbitrary protocol (regardless of SERVER=protocol)
can have a port for remote administration
by specifying a port devoted to administration with "/admin" modifier like
"-PuserPort,adminPort/admin" option.
Example:
-- in FTP server and FTP/HTTP gateway --
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 --
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[@realmValue][:connMap] authServList == [authForw,]authServ[,authServ]* | & | * authForw == -map{inPat}{localPat}{fwdPat} | -strip | -fwd authServ == authHost[/portNum][(reprUser)] authHost == hostName | hostAddr realmValue == word | {words separated with space} connMap == ProtoList:dstHostList:srcHostList -- default: none -- restriction: applicable to Telnet, FTP, NNTP, SMTP, IMAP, Socks, SockMux, and HTTP
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:
Example:
Example:
The result of the authentication by the command is shown in its output string
or by its exit code.
The command may puts a string to its standard output to show the result
in the form of a status response of the FTP protocol, that is,
"230" for success and "530" for failure.
Otherwise the exit code of the process is used, the value zero for success
and non-zero values for failure.
Example: passing username in argument while password in environment variable
[the content of the myauth command]
// 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
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.
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
AUTHORIZER="-cmd{myauth %U}{MYPASS=%P}"
#!/bin/sh
if [ "$1" = "user1" -a "$MYPASS" = "pass1" ]; then
echo "230 SUCCESS"
else
echo "530 FAILURE"
fi
The "-map" prefix is used to split incoming authentication information
of USER and PASS (in inPat pattern) into a pair of authentications,
the one to be used locally by authServList (in localPat) and
another to be forwarded to the server (in fwdPat).
Each authentication information to be matched or generated is represented
by a string of a pair of a user name and a password as
"username:password".
If the username string generated by fwdPat ends with a substring as
"@Host" then it is striped and the Host is used as
the destination server.
The string is matched and generated by the pattern specification format
common to the one used for pattern matching in the
MOUNT parameter.
Example: -strip
Example: -fwd
local auth. by u1 or PAM <-- USER user1 + PASS pass1
outgoing to the server h2 <-- USER user2 + PASS pass2
Example:
As shown in the above example 1),
"-strip" is used to support a nested username and password
as USER "u1@u2@u3@h3@h2@h1" and PASS "p1@p2@p3".
It strips the first element before '@' in the USER and PASS to be used
for local authentication, strips the last element after '@' in USER as
the destination server, then forwards remaining string
to the destination server.
"-fwd" specifies to use the same USER and PASS both for the
local authentication and the authentication with a server.
If only authentication of user is necessary without authorization, the following special name will be useful as a authServList.
Example:
MYAUTH parameter* == MYAUTH=username:password[:connMap] -- default: none -- restriction: applicable to Socks, VSAP, SMTP, and HTTP
The pair of username+password which is sent from a client can be forwarded to the server by MYAUTH="%U:%P" (supported in HTTP and FTP only).
NOTE: For authentication with proxies, it is strongly recommended to use FORWARD with a gateway-URL including authentication information instead of MYAUTH. For example, SOCKS=host:port with MYAUTH=user:pass can be represented as FORWARD=socks://user:pass@host:port.
Example:
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] |
service | -- | max. number of services per delegated process [unlimited] |
standby | -- | max. number of standby process [32] |
conpch | -- | max. number of connections at a time per client host [unlimited] |
ftpcc | -- | max. number of FTP connection cache servers to a host [16] |
nntpcc | -- | max. number of NNTP connection cache processes to a host[16] |
http-cka | -- | (replaced by HTTPCONF=max-cka) |
http-ckapch | -- | (replaced by HTTPCONF=max-ckapch) |
udprelay | -- | max. number of parallel UDPrelay client [32] |
winmtu | -- | max. unit of send() on Win32 [1024] |
TIMEOUT parameter* == TIMEOUT=what:seconds,... -- default: TIMEOUT=dns:10,acc:10,con:10,lin:30,...
shutout | -- | disarming emergent shutout set on fatal error [1800] |
dns | -- | for DNS lookup [10] |
dnsinv | -- | for DNS inverse lookup [6] |
nis | -- | for NIS lookup [3] |
acc | -- | for accept from client (include FTP data connection) [10] |
con | -- | for connection to the server [10] |
lin | -- | LINGER for output [30] |
authorizer | -- | expiration of authorization by AUTHORIZER [unlimited] |
dgnonce | -- | for AUTHORIZER=-dgauth (lifetime of "nonce") [60] |
ident | -- | for connection to Ident server [1] |
rident | -- | for receiving RIDENT=client info. [1.0] |
io | -- | general I/O (no data transmission) [600] |
silence | -- | no data transmission either from client or server [0] (applicable only to tcprelay) |
hello | -- | for HELLO negotiation with the MASTER [30] |
login | -- | for login to proxy (Telnet,FTP,SOCKS) [60] |
daemon | -- | delegated [unlimited] |
restart | -- | cause restart at every specified period [unlimited] |
standby | -- | keep the delegated alive on standby for next client [30] |
takeover | -- | taking over a downloading to cache after client's disconnection [5]
(after the disconnection of the client which initiated the downloading) |
ftpcc | -- | for keeping alive FTP Connection Cache [120] |
nntpcc | -- | for keeping alive NNTP Connection Cache [300] |
http-cka | -- | (replaced by HTTPCONF=tout-cka) |
cfistat | -- | for status information from -s,filter [1.0] |
DELAY parameter* == DELAY=what:seconds -- default: DELAY=reject:60,unknown:60,...
reject | -- | continuous Reject resp. from self or MOUNTed servers [60] |
unknown | -- | continuous Unknown resp. from self or MOUNTed servers [60] |
reject_p | -- | continuous Reject resp. from origin server [0] |
unknown_p | -- | continuous Unknown resp. from origin server [0] |
Each value specifies the maximum delay time and delay time increases according as the error count increases.
CHOKE parameter* == CHOKE=Choking:Client:Ua:Referer:Url:Server:Protocol -- default: none
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
If "=" is specified as vURL or rURL, it means mount as is without rewriting for the vURL in a request, or rewriting for rURL in a response.
The port number of the destination server (in rURL)
can be prefixed with "-" or "+"
to be determined dynamically
by offsetting from the port number of the entransport,
as in SERVER parameter.
A special host name "odst.-" in rURL (or in the SERVER
parameter) represents the original destination host of the TCP connection
from the client via NAT (provided by iptables on Linux).
It can be used to configure a transparent proxy (or gateway)
for arbitrary protocols.
The original destination port number can be referred with "-" as "odst.-:-".
The number can be mapped with an offset value as "-8000" or "+8000" for example.
The name "odst.-" can be used in the "rserv" MountOption
too.
If the rURL is of "file:path" and the path is a relative one, then the data file is searched under the DGROOT directory or directories listed in DATAPATH.
If a rURL is prefixed as "vurl:rURL", the rewritten URL (in a request message) from vURL to rURL will be rewritten by another MOUNT again. This recursive MOUNT is not applied to the rewriting a URL in response data from rURL to vURL, therefore it does not work as expected in HTTP where such reverse rewriting of URL in response is expected too.
Example: recursive MOUNT
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
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
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.
Another special convList URICONV="where:any" enables searching URL to be rewritten not only in HTML tags but also in XML, JavaScript, CSS (Cascading Style Sheets) and SWF (Shockwave Flush).
Example:
BASEURL parameter == BASEURL=URL -- default: none
When an origin/gateway HTTP-DeleGate received "Host:vhost1" in a request header, it overrides BASEURL="http://vhost0" parameter to have "vhost1" be the base URL of the DeleGate. To override the "Host:" header by BASEURL, prefix "-" to a host name as BASEURL="http://-vhost0".
Example:
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.
COUNTER parameter == COUNTER=listOfCounterControl counterControl == do | total | acc | ssi | ref | err | ro | no | mntpV -- default: COUNTER=no -- restriction: applicable to HTTP, SMTP, FTP and DNS
Each access counter is stored in a file at "ADMDIR/counts/access/URL#count". Each counter file starts with a line consists of the numbers of accesses in ASCII decimal format so that it can be initialized or modified manually. The line can contain three numbers; the first one is the total count, the second one is the count excluding repetitive accesses from the same client, and the third one is the count excluding repetitive access from one of recent ten clients. Each count are represented as %T, %U and %V respectively in the format string described below.
The counter can be displayed in a specified format using SSI as the PAGE_COUNT or COUNTER value. If no "url" attribute is specified in a tag, the URL of the SHTML file containing the tag is implied. Counter values are converted to a printable character string following to the format string given in the "fmt=..." attribute. The default format is "%T".
Format Specifiers:
Example:
The total count is displayed by TOTAL_HITS tag or by COUNTER tag with "sel=total". The referrer counter of a URL is incremented when the URL is in "Referer:" header in a HTTP request. Each referrer counter is stored in a file at "ADMDIR/counts/referer/URL#count-ref". The referrer counter can be displayed with "sel=ref" attribute in the COUNTER tag.
Example:
Enabling all counters for each URL can be expensive and/or unnecessary. You can reduce counters by using the counter of a MOUNT point as the representative, or using only total access counters of the server. In the following example, counters for all URLs is enabled by default (with COUNTER=do), while counters for URLs under /srv1/ is represented by the counter of /srv1/, and only the server's total counter and SSI counters are enabled for URLs under /mine/. As shown in this example, COUNTER can be specified as a MountOption of which initial value is inherited from the COUNTER parameter.
Example:
COUNTER=do MOUNT="/srv1/* http://srv1/* COUNTER=mntpV" MOUNT="/mine/* file:dirpath/* COUNTER=no,total,ssi"
COUNTERDIR parameter == COUNTERDIR=dirPath -- default: COUNTERDIR='${ADMDIR}/counts[date+/year%y/week%W]'
CACHE parameter* == CACHE=cacheControl[,cacheControl]*[:connMap] cacheControl == do | no | ro connMap == ProtoList[:[dstHostList][:srcHostList]] -- default: none -- restriction: applicable to HTTP, FTP, NNTP and Gopher
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]'
%P | -- | scheme | Protocol name part |
%L | -- | host.d2.d1:port | Login (or site) part |
%H | -- | host.d2.d1 | Host name |
%T | -- | port | Port number |
%h | -- | d1/d2/host | hierarchical host name directory |
%d | -- | d1/d2 | hierarchical domain name directory |
%1 | -- | d1 | top level domain |
%2 | -- | d2 | second level domain |
%p | -- | path | URL-path part |
%Q | -- | host.d2.d1.d0 | use FQDN of a host name (like %Q%L or %Q%H) |
Another formatting pattern is "$[hash:format]" which
hashes a string generated by format into
hexadecimal value ranging from "00" to "1f".
This will be useful to divide a single huge directory containing all
servers into 32 small directories, which can be on physically
different disks.
Example:
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:
CHARCODE parameter* == CHARCODE=[inputCode/]outputCode[:[tosv][:connMap]] outputCode == charCode charCode == iso-2022-jp | euc-jp | shift_jis | utf-8 | us-ascii | JIS | EUC | SJIS | UTF8 | ASCII | guess connMap == [ProtoList][:[dstHostList][:[srcHostList]]] -- restriction: applicable to HTTP, FTP, SMTP, POP, NNTP, Telnet, Tcprelay -- default: none
The pseudo code name "guess" means not doing conversion but supplement the "charset" attribute in "Content-Type" header in a message when it is lacking, guessing it from the body of the message. This is useful when a viewer program (ex. a web browser) of the message is not localized to Japanese thus non-ASCII codes like EUC-JP are guessed as European or so by the viewer.
If "tosv" is specified, the conversion is applied to the request message (or a message toward a server). The conversion is also applied to fragments of Japanese text in a HTTP request message encoded in "%XX" in its request URL or in the body of a POST message (when it is encoded in Content-Type: application/x-www-form-urlencoded). The set of values of Content-Type to which the conversion is applied can be specified with HTTPCONF=post-ccx-type.
The application of the conversion can be limited only to a specified set of protocols, servers and clients specified with connMap. In the connMap, the default value of ProtoList, dstHostList and srcHostList is "*" which matches any protocols or hosts.
Example: send response in UTF8 to clients and send request in Shift_JIS to HTTP servers
For the FTP protocol, the conversion is applied only to the data of the ASCII type relayed on the data-connections by default. It is applied also to binary data or data on the control-connection with FTPCONF="ccx:any".
To enable this parameter for internet-mail/news protocols (SMTP, POP and NNTP), also MIMECONV parameter must be specified so that it enables character conversion (enabled by default).
A HTTP client can override this specification by sending its choice in "Accept-Language" field in a request message, which may be configurable in each client (WWW browser). For example, if "Accept-Language: (charcode=EUC)" is sent in a request from client, the response text will be converted into EUC regardless of CHARCODE specification of the DeleGate. If "Accept-Language: (charcode=THRU)" is specified, any conversion specified by the administrator of this DeleGate is disabled.
CHARMAP parameter* == CHARMAP=mapType:charMap[,charMap]*[:tosv] mapType == ascii | ucs | jis | ucsjis | jisucs charMap == inCharCode1[-inCharCode2]/outCharCode2[-[outCharCode2]] charCode == hexa-decimal code | single ASCII character -- default: none
A character to be mapped is represented in a hexa-decimal value of it
(represented in more than 2 columns), or a direct character in a single columns.
The characters in the JIS X 0208 character set encoded in the variants of its
encoding (ISO-2022-JP, EUC-JP, and Shift_JIS) are represented in
its JIS code value without the most significant bits (8080) as "2121".
The characters in the JIS X 0212 character set are represented in its
JIS code value prefixed with "1" as "1222F".
If inCharCode2 and outCharCode2 is specified, each character in
the range is mapped to the corresponding character.
If no -outCharCode2 is given, any input characters in the range
is mapped to outCharCode1.
The mapType is one of followings:
Example: reverse lowercase and upper case
Example: "rot13" encoding
Example: replace any Japanese character in JIS X 0208 with "GETA MARK"
Example: replace any Japanese character in JIS X 0212 with "GETA MARK"
Example: represents unknown characters by "WHITE SQUARE" instead of "GETA MARK"
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 | nospenc | textonly | alt:first | alt:plain -- default: none -- MIMECONV="" if CHARCODE parameter is given
Here is a group of options for filtering a "multipart/*" message to convert it into a plain message by selecting or unfolding the list of parts as follows:
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
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.
Example:
-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
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: if ${STARTDIR}/DGROOT exists then use it, or on Unix: '/' if CHROOT is set or '${HOME}/delegate' or '/var/spool/delegate-${OWNER}' or '/tmp/delegate-${OWNER}' on Windows: '/Program Files/DeleGate'
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'
ADMDIR parameter == ADMDIR=dirPath -- default: ADMDIR='${VARDIR}/adm'
LOGDIR parameter == LOGDIR=dirPath -- default: LOGDIR='${VARDIR}/log' -- v10-default: LOGDIR='log[date+/y%y/m%m/%d]'
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.
SYSLOG parameter* == SYSLOG=[syslogOpts,][syslogServ] syslogOpts == syslogOpt[,syslogOpts] syslogOpt == -vt | -vs | -vS | -vH | -fname -- default: none
Multiple SYSLOG parameters can be specified to send a log data to multiple different destinations each specified by a syslogServ. A syslogServ is a URL of a syslog server or a local file. The default syslogServ is the local logger to which log is sent via the standard "syslog()" function. For each destination, the log format or detailness can be specified by prefixing a list of syslogOpt as follows:
-vt | -- terse LOGFILE |
-vs | -- without LOGFILE |
-vS | -- without PROTOLOG |
-vH | -- without the syslog header |
-fname | -- use the facility name instead of "daemon" |
Example:
SYSLOG= | -- to the local syslog |
SYSLOG=syslog://host | -- to a remote syslog server |
SYSLOG=syslog://host:port | -- on a non-standard port |
SYSLOG=/dev/tty | -- to the console |
SYSLOG=file:path | -- to a local file |
SYSLOG=-vH,file:path | -- without the syslog header |
SYSLOG=-fdaemon | -- as the "daemon" facility (default) |
SYSLOG=-flocal1 | -- as the "local1" facility |
The source port (and the address) of syslog UDP packets to a remote
syslog server can be specified as
SRCIF=":8514:syslog"
(or SRCIF="xx.xx.xx.xx:8514:syslog")
for example.
Switching syslog servers based on each client and server of the
application protocol is not (yet) supported.
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 == resType[:[resParam][:[queryHostList][:clientHostList]]] resType == 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 host-name file [/etc/hosts] |
nis:nisDomain | -- NIS domain name [default domain] |
dns:dnsHost | -- (a list of) DNS server |
Example: selecting DNS servers depending on the inquired host/address
Example: selecting resolvers depending on the inquiring (client) DNS host
By default, a connection to a host which has multiple IP addresses is tried for each address in the order they are defined in each resolver. A special parameter HOSTS="*/*/RR" can be added to specify "Round Robin" where those IP addresses are tried in round robin order.
RES_WAIT parameter == RES_WAIT=seconds:hostname -- default: RES_WAIT="10:WWW.DeleGate.ORG"
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] | END. -- default: depend on RES_CONF
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_DEBUG=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 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:
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:
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".
A substitution resource can be given in an encrypted format. Encrypted data can be directly represented in the string of format as "+=enc:ext::XXXX:" in which the part of XXXX contains the encrypted data. This format of data is created with "-Fenc" option of DeleGate. When it is named with the suffix ".cdh" as "+=conf.cdh", it is decrypted by "Credhy" using the passphrase for decryption which is specified as the password of the "config" user.
Substitution can be done recursively. In this case, a relative resource name is searched in DGPATH or LIBPATH. By default, DGPATH='+:.:${HOME}/delegate' where "+" stands for the place where the "caller" resource is. For example, if "+=file2" is referred from caller file "/local/etc/file1", the "file2" will be searched first as "/local/etc/file2". A resource name can be specified in full URL like "+={file:/local/etc/file1}" or "+={http://host/file}".
paramRef == +=[URL][?label,[label]*] paramList == line line ... paramListPart == CASE label paramList ESAC
Substitution resources are the list of options (or parameters) where each line stands for an option (or a parameter). In each line, strings after sharp character(#) will be ignored as a comment. White space characters (SPACE, TAB, LF and CR) at the beginning or the ending of each line are ignored. Single quote(') and double quote(") are stripped. Back slash character(\) let the succeeding character be as is.
Example: The following five examples have the same meaning with each other.
PERMIT=a:b:c PERMIT=a:b:d PERMIT=a:e:f PERMIT=x:y:z ...
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:
For FTOXX and FFROMXX filters,
CFI script enables selecting an appropriate filter
to be applied to each data depending on the type of data.
Instead of direct usage of a filter program like
FTOCL=filterCommand, specify
FTOCL=filter.cfi where filter.cfi is a file
in the CFI script format.
Or a CFI script can be loaded from remote host like
FTOCL=URL via HTTP or FTP.
When the file name of CFI scripts or a filter command referred
in the script is specified in relative path name,
it is searched in LIBPATH.
CFI script
The CFI script is a simple script to select an appropriate filter
to be applied to a message data relayed on DeleGate, depending on
the type of data, the server name, the type of client, and so on.
A CFI script is text data which
starts with a magic string "#!cfi" and
contains more than one filter specifications
which are separated by "--" with each other.
Input Format:
CFI script == "!#cfi" NL filterUnit [ "--" NL filterUnit ]*
filterUnit == filterRule [ filterRule ]*
filterRule == matchingRule | rewriteRule | filterSpec
matchingRule == matchingName ":" ruleBody
matchingName == MIMEheader | X-header | CGIENV
MIMEheader == "Content-Type" | "User-Agent" | ...
X-header == "X-Status-Ver" | "X-Status-Code"
| "X-Request-Method" | "X-Request-Ver"| "X-Request-URL" | ...
CGIENV == "REQUEST_METHOD" | "SERVER_PROTOCOL" | "SERVER_NAME"
| "PATH_INFO" | "PATH_TRANSLATED" | "HTTP_USER_AGENT" | ...
rewriteRule == Action "/" MIMEheader : ruleBody
Action == "Output" | "Remove"
filterSpec == filterType ":" ruleBody
filterType == "Body-Filter" | "CGI" | "Header-Filter"
| "MIME-Filter" | "Message-Filter"
ruleBody == string NL [ SP string NL ]*
The input data to CFI script is a message of application protocol in
MIME format preceded with a request or a response status line of the
application protocol (HTTP, SMTP, POP, NNTP).
A MIME message is composed with a header and a body separated with
an empty line.
CFIinputMessage == statusLine MIMEheader NL MIMEbody
Example: a simple HTTP response message
HTTP/1.0 200 OK ... response status line Content-Type: text/html ... header Content-Length: 20 ... header ... header/body separator body of the message ... body
Matching Rule:
A matchingRule indicates matching the
ruleName:ruleBody to the input header.
It matches when the input message has a ruleName header with
a field body matches with ruleBody.
If at least one of matching rules turns to be true,
then the filterUnit is adopted.
If no matching rule is included in a filterUnit then
the filterUnit is adopted unconditionally.
Currently, only a limited set of MIME headers (in request or response
message) can be used for the matching.
Also, some extended headers can be used to match with information not
included in the original header (ex. "X-Status-Code" which means
status code in response message).
Matching with CGI
environment variables.
Example: a matching rule
Rewriting Rule:
A rewriteRule with a prefix "Action/" to a
ruleName:ruleBody specifies some simple rewriting
using ruleBody data for relevant ruleName field.
"Output/ruleName:ruleBody" indicates appending (or replacing)
a ruleName:ruleBody field into the header.
"Remove/ruleName:ruleBody" indicates removing header fields
with name ruleName and body matches to ruleBody.
Filter Specification:
A filterSpec specifies a filter to be applied to the input data.
The whole or a part of input message will be passed to
the standard input of the filter program, then the output from the
standard output of it will be forwarded to the destination
(client or server) instead of the original input message.
Body-Filter: filter for MIMEbody CGI: filter for MIMEbody Header-Filter: filter for MIMEheader MIME-Filter: filter for MIMEheader + MIMEbody Message-Filter: filter for statusLine + MIMEheader + MIMEbodyFor filters of any type, the set of CGI environment variables is passed. In addition, CFI origin environments variables are passed including "SERVER_HOST" (the name of the destination server), "REQUEST_URL" (the URL of the request).
For filters of "Body-Filter" or "CGI", the "Content-Length" header in the forwarded message will be adjusted to indicate the size of the body part after the filtering. The output of "CGI" filter must preceded with the status header of CGI output.
For filters of "Header-Filter", the header part of a message will be passed to and from the filter. The start-line in the HTTP message (Request-Line or Status-Line) will be passed as a header field prefixed with "Request-Line:" or "Status-Line:".
For filters of "MIME-Filter", the whole of the MIME message consists of a header and a body is passed to and from the filter.
For filters of "Message-Filter", the whole message of the application protocol is passed to and from the filter where each message consists of a MIME message prefixed with a line representing request or response status in the application protocol.
Example: rewriting HTTP response messages
Example: dump available headers and environment variables
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
Example: a gateway between UDP and TCP
A pair of gateways like above can be used to convey UDP packets over TCP connections, but such relaying (tunneling) is realized more efficiently using SockMux with a single TCP connection.
DGAuth server
Example: DGAuth-DeleGate server and its client
Example: DGAuth-DeleGate server and its client on the same host
A DGAuth server receives a set of components to be used to calculate digest for each application protocol, then return the digest, as follows.
PAM server
Example: PAM-DeleGate server and its client
Example: PAM-DeleGate server and its client communicating over SSL
Note that most of PAM authentications need to be executed under the privilege of superuser on Unix (with OWNER="root" option). But you can avoid running your PAM-DeleGate server with superuser privilege by installing external program "dgpam" under DGROOT/subin/.
The default port number of the experimental PAM/HTTP server is 8686. Other ports can be specified as AUTHRIZER=-pam//host..port, for example as AUTHORIZER="-pam//hostX..8765/passwd".
PAM/HTTP protocol uses the format of HTTP compatible request/response messages as follows.
Following the format, you can easily develop your own PAM server, instead of PAM-DeleGate, using your own HTTP server with CGI or so.
FTPxHTTP server
YYsh server
YYMUX server
SOCKMUX parameter* == SOCKMUX=host:port:option[,option]* option == acc | con | ssl -- default: none -- status: tentative
host:port specifies the port toward which a SockMux persistent connection is established. The connection is established from the DeleGate with "con" option to the DeleGate with "acc" option.
Options:
Example: SOCKS proxies chained over SockMux
Example: SOCKS proxies chained over SockMux connected from the server side
Example: HTTP proxies chained over SockMux
SOXCONF parameter* == SOXCONF=confSpec[,confSpec]* -- default: none
SockMux server
The persistent connection is established with "-Phost:port" parameter at receptor side, and "SERVER=sockmux://host:port" at connector side. The port to accept outgoing connections to be forwarded to remote is specified with PORT="listOfPorts parameter. The server to be connected for incoming connections from remote is specified with a postfix string ",-in" like SERVER="telnet://host:23,-in".
An incoming connection can be processed with DeleGate as a proxy of the specified protocol. If only protocol name is specified like SERVER="telnet,-in", or if "-in" is postfixed like "-in(option list)", then a DeleGate is invoked to process the connection. The option list is passed to the invoked DeleGate as the list of command line options. For example, SERVER="telnet://host,-in(+=config.cnf)" will invoke a DeleGate with command line options like ``delegated SERVER=telnet://host +=config.cnf''.
Example: bi-directional SockMux-DeleGate
Example: uni-directional SockMux-DeleGate
Example: uni-directional to proxy-Telent-DeleGate
When SockMux is used just to relay data between sockets, without interpreting the application protocol relayed over SockMux, such relaying can be represented with simpler expression using DEST parameter instead of SERVER as follows:
Example: tcprelay over SockMux
Example: relaying UDP over SockMux/TCP
Another way to establish a persistent connection between two SockMux-DeleGate is using a FIFO device like named pipe. It is specified like SERVER=sockmux:commtype@fifoName where commtype is one of "commin", "commout", and "comm", which represents uni-directional input, uni-directional output and bi-directional input/output respectively.
Example: use fifo device on a host
Example: use communication port between two hosts (not tested yet)
The persistent connection can be established by a given external program invoked by DeleGate. The process of the program is passed a socket to/from DeleGate at file descriptor number 0 and 1;
Example: establish connection by external command
The destination SERVER for an incoming connection from remote can be selected depending on which port it was accepted. A SERVER parameter postfixed with ":-:-Pxxxx" will be applied only to connections which is accepted on remote host with PORT=xxxx.
Example: forwarding multiple port
NOTE: forwarding FTP data connection is not supported (yet).
HTMUX parameter == HTMUX=sv[:[hostList][:portList]] | HTMUX=cl:host:port | HTMUX=px:host:port -- restriction: requires CAPSKEY -- default: none
Not only incoming connections but also outgoing connections from a HTMUX client is established via the HTMUX server by default. This might not necessary for a DeleGate that relays incoming request to internal server. In such case, use the CONNECT parameter to specify such connections to be established directory, as CONNECT="direct:*:192.168.1.*" for example.
Example:
This example implies that hostX is a multi-homed host with a private addresses 192.168.1.1 and a global address xx.xx.xx.xx. The DeleGate on hostX acts as a HTMUX server. HTTP DeleGate on hostI and FTP DeleGate on hostJ act as HTMUX client which remotely accepts requests (arrived at xx.xx.xx.xx) via the HTMUX server on HostX.
A pair of HTMUX server and client uses a single persistent connection to relay
multiple parallel connections on it multiplexing them by the
SockMux protocol.
This feature must not be exploited maliciously, for example to invite
incoming connections violating a restriction on a firewall.
Therefore you need to install CAPSKEY to enable this feature.
Other usages of HTMUX being disabled by default are
non-direct connection between client and server (connection via NAT or proxy),
too large clock skew between client and server (300 seconds by default),
or inserting SSL encryption between client and server.
There are two ways to enable non-direct connection for HTMUX. One way is to install a CAPSKEY to enable indirect HTMUX connection. Another way is inserting a HTMUX proxy as the following example.
Example: cascading HTMUX with a HTMUX proxy
The persistent connection between HTMUX client and server is capable to convey connections bi-directionally, thus can be used to make a pair of proxies over it. Each proxy accepts requests at the local port and forwards them to the remote peer as the following example.
Example: using HTMUX to make symmetric proxies (the simplest generic configuration)
In this example, -P8080 is equivalent to a wild-card address expression
"-P*:8080" to accept from the port number 8080 on any network interfaces
on the host.
Therefore requests to the port 8080 on any interface on hostX is forwarded
to the servers via the DeleGate on hostY as a HTMUX client (and a HTTP proxy).
Symmetrically, requests to the port 8080 on any interface on hostY is
forwarded to the servers via the DeleGate on hostX as a HTTP proxy (and a
HTMUX server at hostX:9876).
(Again, note that this feature is disabled by default and needs
CAPSKEY to enable it)
The port to be used on the server side and on the client side can be specified separately with the "/local" and "/remote" modifiers for -P or -Q option. "/local" marks a port to be used on the local host (on a HTMUX client), and "/remote" marks the port to be used on the remote host (on a HTMUX server). The specification "-P8080" in the above example is equivalent to "-P*:8080/remote,*:8080/local".
Example: using HTMUX bi-directionally
In this example, between hostX and hostI, requests to localhost:8081 on each host are forwarded to the peer (equivalent to "-Plocalhost:8081/remote,localhost:8081/local") Between hostX and hostJ, hostX:8082 and hostJ:8083 are forwarded to the peer (equivalent to "-PhostX:8082/remote,hostJ:8083/local")
Example: using HTMUX only for outbound requests
This is an example to use HTMUX only for outbound requests. It works even without the HTMUX parameter, but with HTMUX, a single persistent connection is used between the server and client. This usage of HTMUX is enabled by default when DeleGate is executed in foreground (with -fv option, running not as a service or a daemon), without restrictions described as above, and don't require CAPSKEY.
CAPSKEY parameter* == CAPSKEY=opaque -- default: none
Socks server
Example: Socks-DeleGate
To accept an incoming TCP connection via a SOCKS-DeleGate server, the network interface to be used for it is selected automatically by DeleGate (based on the DST.ADDR or DSTIP which is sent from a SOCKS client as the parameter of the BIND command). With the SRCIF parameter, you can select a network interface (and port number) manually, with the pseudo protocol name "tcpbind". The complete syntax of the parameter is SRCIF= "[host]:[port]:tcpbind[:dstHostList[:srcHostList]]". Typically, only the host filed is specified to select a network interface, like SRCIF="150.29.202.120::tcpbind" for example.
NOTE: When you chain DeleGate with another SOCKS server, it may cause problems in UDP relaying due to the private and tentative extensions to the SOCKS protocol by DeleGate. The following SRCIF parameters can be useful to escape such problems.
SOCKSTAP parameter* == SOCKSTAP=ProtoList[:[dstHostList][:[srcHostList][:params]]] -- default: none
Example: Socks-DeleGate which do caching for HTTP and FTP
Example: Socks-DeleGate which do caching for HTTP with an upstream proxy
See http://www.delegate.org/delegate/sockstap/> for more details.
HTTP proxy/server
Then use this DeleGate from your client on the internal host, specifying "firewall:8080" as the proxy for HTTP, HTTPS (Security), FTP, Gopher, Wais, and so on.
Example: cascaded DeleGate as an HTTP proxy
Run a generalist DeleGate on the firewall which only accepts request from internal host, then run a specialist on internal which use the generalist on firewall host. A generalist can be shared as an upstream DeleGate from multiple DeleGates of arbitrary protocol.
Example: DeleGate as an origin HTTP server
A file with a name with ".cgi" extension is treated as a CGI script.
Also you can use arbitrary name of CGI scripts under a specified
directory with a MOUNT like:
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 field in the request message |
%S | -- status of CONNECTion to the server (c,m,p,d,s,v) |
%s | -- session Id by HTTPCONF=session |
%As | -- session Id in Digest Authorization |
%{field} -- arbitrary field in the request message
| |
The session identifier put by "%s" is generated by specifying HTTPCONF=session:cookie option while "%As" is generated by AUTHORIZER=-dgauth option. The format of session identifier is as this:
For example, "031114-173045.1234.5+6+7.9" means that it is the 9th request from the client in the session started at 17:30:45 on November 14 by the process of PID=1234. The start of the session is recorded in LOGFILE as this:
Note that the reqnum part may not be unique because of parallel or pipelined requests generated by a client as the owner of the session. Note that the reqnum part for "%As" may not be incremented on each request because the container of session identifier, the opaque" parameter in Digest Authentication in this case, may not be updated on each request.
HTTPCONF parameter == HTTPCONF=what:conf
Automatically detects virtual servers in MOUNT parameters and notate
each of them as a MOUNT rule to be applied only to a virtual server.
It can be done manually by specifying "nvserv" MountOption
for each MOUNT parameter.
"nvserv:alias" means detecting target servers of host names with
common IP-addresses and notate them as virtual servers.
"nvserv:gen" means notating MOUNT parameters with "genvhost"
MountOption as virtual servers.
"nvserv:auto" is equivalent to "nvserv:alias,gen".
The guessing can be overridden by explicitly specifying
the avserv MountOption for each MOUNT parameter.
"nvserv:none" disables any treatment of virtual servers which are
detected automatically or specified explicitly by the "nvserv" MountOption.
Example:
Example:
Example:
encrypt specified attributes in a Set-Cookie response to be stored in a client, then decrypt and forward the Cookie request only to the originator of the Cookie. An attribute in a Cookie is specified as "attribute@host" or "attribute@.domain". In the former case, a cookie generated by a host is encrypted and echoed to host only. In the latter case, a cookie generated by hosts in the domain can be echoed to hosts in the domain. The special string "%a" in cryptKey is substituted by the IP-address of the client. This makes the crypted Cookie be usable only by clients on the host of the IP-address.
Example:
Example:
Example:
HTTPCONF="add-qhead:X-Forward-For:%a"
Example:
Example:
Example:
Example:
FILETYPE parameter == FILETYPE=suffix:gopherType:altText:iconName:contentType -- default: FILETYPE=".txt:0:TXT:text:text/plain" FILETYPE=...
Example:
CGIENV parameter == CGIENV=name[,name]* -- default: CGIENV="*"
MountOptions for HTTP-DeleGate
CONTROLS:
Example: virtual hosting, acting as multiple HTTP servers
MOUNT="/* http://wwwA/* nvhost=dom1.com"
MOUNT="/* http://wwwB/* nvhost=dom2.org"
MOUNT="/* file:data/wwwC/* nvhost=dom3.net"
MOUNT="/* file:data/www/*"
Example:
MOUNT="http:* = method=POST,asproxy,useproxy"
MOUNT="http:* = withquery,asproxy,useproxy"
AUTH parameters for HTTP-DeleGate
Example:
%u | -- user name got using Ident protocol |
%h | -- host name of the client got from the socket |
%i | -- host name of the network interface to the client |
%I | -- like %i but use the value of "Host:" if given in HTTP |
%a | -- host address of the client |
%n | -- network address of the client |
%H | -- hostname of the DeleGate |
%M | -- the ADMIN of the DeleGate |
%A | -- generated string by "CMAP=string:authgen:mapSpec" |
%U | -- username part of client's [Proxy-]Authorization: username:password |
%P | -- password part of client's [Proxy-]Authorization: username:password |
Example:
A generated password is formatted as "passWord/%i" and a DeleGate rejects incoming requests with an Authorization field of such pattern. Thus forged password cannot pass the DeleGate on the host "%i".
Example:
%F | -- E-mail address in From field |
%L | -- local part of From: local@domain field |
%D | -- domain part of From: local@domain field |
%U | -- username part of Authorization: username:password |
%P | -- password part of Authorization: username:password |
%Q | -- "for clientFQDN" part of Forwarded: field |
Example:
Configuration of DeleGate by Users
Example: MOUNTing news serverN at http://delegate/news/servN/
(This mechanism should be applied to other protocols like FTP...)
Server Side Include in SHTML files
SSI tags
Note that including a resource by SSI is under the access control of
DeleGate (as origin or proxy server) common to the access control
against client users. That is, if a client user is forbidden to
access the included resource, it is also forbidden even via SSI-include.
Especially allowing including a resource out of the DeleGate server,
with URL like virtual=http://exserver/dir/fileX
can make a security hole made by a user as a SHTML writer.
In an origin server, relaying as a proxy must be forbidden by
RELAY=no, but it also forbids SSI-include to do
from other servers.
A simple workaround in version 9 is adding a limited RELAY as
RELAY="proxy:http:exserver:*" that only allows
relaying to exserver.
Another safer workaround is using MOUNT like
MOUNT="/ex/* http://exserver/dir/*" then write SSI-include like
virtual="/ex/fileX".
But both of these allows client users to access to resources
other than the intended virtual URL in the exserver.
To cope with the above problem in version 10, RELAY=ssi is
introduced to be used together with RELAY=no. RELAY=ssi allows
SHTML writers to do include from other servers, leaving the permission
for client users unchanged (as RELAY=no).
In other words without RELAY=ssi, you (as the administrator of DeleGate)
can forbid SHTML writers to include from other servers.
Also you can restrict the includable target server (and protocols or clients)
by the generic notation of DeleGate as
RELAY=ssi:protocolList:serverList:clientList.
NOTE: Maybe it is impossible to forbid CGIs to access arbitrary servers
in a way independent of platforms and languages.
But at least we can forbid CGIs completely with
REMITTABLE="+,-cgi".
Another (and maybe more important) extension in version 10 is relaying
request/response message header (as Cookie or User-Agent) back and forth
between client and server via SSI-include.
META tags
ICP proxy/server
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
Also the complete format user:pass@host[:port] as the generic server specification in URL is usable both for USER and CWD like follows.
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
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: MOUNT to non-anonymous FTP (and sftp) server
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
"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
If a ftpControl listed above is followed by ":sv" or ":cl" like "nopasv:sv" for example, the ftpControl is applied only for server side or client side respectively.
controls how to manipulate FTP Bounce.
FTPCONF can be applied on a specific condition by specifying it
as a MountOption like
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
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
SSH/Telnet gateway
POP proxy
Example: proxy POP-DeleGate
external% telnet firewall pop
Example: POP MOUNT
MOUNT="//* ="
... don't rewrite if a server is specified by the user
When a target POP server indicates that it accepts APOP authentication
(by a greeting message with a time stamp), DeleGate tries login with
APOP first, then retries with USER+PASS when APOP failed.
But if a server never accepts APOP in spite of its greeting, the useless
trial with APOP can be suppressed by "noapop" MountOption like this:
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
SMTP proxy/server
Examples:
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.
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:
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.
Anonymizing NNTP articles
To disable mail address mining for spamming, mail addresses transferred
over NNTP protocol can be anonymized with the "rewaddr" MountOption as this:
In the Telnet-DeleGate (DeleGate server for Telnet clients), a host name
prefixed with "-ssh" and "." (as "-ssh.host") implies a SSH server
on the host.
In access to such a server, Telnet-DeleGate works as a gateway between
the SSH server and a Telnet client.
For example, using a Telnet-DeleGate configured like follows,
Telnet clients can login to a SSH server on host as user
as follows:
% delegated -P8023 SERVER=telnet://-ssh
The target SSH server can be limited as this:
% telnet -l user@host localhost 8023
% delegated -P8023 SERVER=telnet://-ssh.host
The user on the target SSH server can be limited as this:
% telnet -l user localhost 8023
% delegated -P8023 SERVER=telnet://user@-ssh.host
The password of the user can be specified as this:
% telnet localhost 8023
% delegated -P8023 SERVER="telnet://user:pass@-ssh.host"
In this case, the Telnet client cannot specify anything about the target
SSH server and the login procedure is achieved fully automatically.
Reserved characters in the pass part should be escaped with
the "%XX" notation (at least "@" must be escaped with "%40").
% telnet localhost 8023
Telnet clients without the capability to send authentication information
with the "-l user" option or so, can specify it in the traditional way
of the Telnet-DeleGate as follows:
% delegated -P8023 SERVER=telnet://-ssh
% telnet localhost 8023
>> Host name: user@host
firewall# delegated -P110 SERVER=pop
+OK Proxy-POP server (DeleGate6.1.0) at firewall starting.
USER username@servername
...
Instead of "@", "%" or "#" can be used as the delimiter between
username and servername, like
username%servername or
username#servername.
"pop://user@server" is represented
as "pop://server/user" internally thus
it can be controlled by MOUNT as follows:
MOUNT="* pop://defaultHost/*"
... specify default POP server
MOUNT="user1 pop://host1/*"
... let the "host1" be the server of "user1"
MOUNT="//pop2/* pop://host2/*"
... map user@pop2 to user@host2, hiding real hostname "host2"
MOUNT="//*%S/%S pop://server/*%(1)@%(0)"
... forward user@host as is to pop://server/user@host
MOUNT="* pop://server/* noapop"
SERVER=pop
MOUNT="* nntp://nntpserver/*"
MOUNT="ns2-* nntp://nntpserver1/* apop=password"
MOUNT="ns3-* nntp://nntpserver2/* pass=password"
firewall# delegated -P80 MOUNT="/mail/* pop://mailHost/*"
Example: proxy IMAP-DeleGate
firewall# delegated -P143 SERVER=imap
* OK external Proxy-IMAP server DeleGate/6.1.15
C001 LOGIN username@servername
...
LOGIN username%servername is also acceptable.
SMTPCONF parameter* == SMTPCONF=what:conf
-- default: SMTPCONF=bgdatasize:64K
Multiple conditions can be specified concatenated with "+" as
SMTPCONF="reject:nomx+nohelo+nofrom+pipeline".
The default specification is
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".
// forward messages accepted at "feedback@delegate.org"
// toward "delegate-en@smtpgate.etl.go.jp"
INHERIT: sendmail
SERVER-HOST: mail.etl.go.jp
RECIPIENT: delegate-en@smtpgate.etl.go.jp
ACCEPT/From: !%, !MAILER_DAEMON@, !hotmail.com, ...
[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
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:)
SMTPGATE/admin/@default/
CONTROL/INHERIT: sendmail
CONTROL/RECIPIENT: ${recipient}
CONTROL/SERVER-HOST: ${recipient.mx}
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.
# delegated -P119 SERVER=nntp://nntpServer/group.
// 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."
// mounts a mail spool as if it is a newsgroup named "+pop.user.host".
# delegated -P119 SERVER=nntp
MOUNT="= pop://user:pass@host/"
# delegated -P80 MOUNT="/news/* nntp://nntpServer/*"
# delegated -P119 SERVER=nntp://-.-/
'${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)
MOUNT="* nntp://server/* rewaddr=*:%l@%r"
MountOptions for NNTP
NNTPCONF parameter* == NNTPCONF=what:conf -- default: NNTPCONF=upact:600/300/120
LDAP proxy
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
Example: relay between SSL client and non-SSL serverDNS (Domain Name System) proxy/server
Example: {NIS,FILE,DNS}/DNS gateway
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
DNSCONF parameter* == DNSCONF=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] |
mx:FQDH | -- [primary host name of -MX.host if exists or inquired host itself] |
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
AF_LOCAL SOCKETS
CUSTOMIZATION
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 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.
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.
ENCRYPTED CONFIGURATION
The Passphrase will be used by SSL library for decryption of the
private-key, which might be bundled in a file together with a certificate,
like this for example:
Another passphrase is for getting encrypted
configuration parameters specified as "+=conf.cdh".
The passphrase to decrypt such data is given as the password of
a special user named "config" in a special domain, as this:
The suffix ".cdh" means that the data is encrypted with "Credhy" algorithm.
A file can be encrypted and decrypted with -Fcredhy as follows:
An encrypted configuration file can be used as follows:
When a configuration file is loaded from a remote server,
it is strongly recommended to use the encryption.
If the MasterKey is not specified with a CRYPT parameter
for a DeleGate which requires it,
then it will be asked interactively.
When restarting DeleGate with "-r" or SIGHUP,
or restarting in short time after termination,
or possibly after rebooting the host machine,
the MasterKey is automatically saved and reused
without the interaction.
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.
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
The following is a list of major functions.
FILES
See the description of DGROOT parameter
and Local file usage
for more information.
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"
MOUNT="/-/builtin/* http://yourwww/delegate/builtin/*"
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.
Configuration data can be in encrypted format which requires a passphrase
to decrypt it. Such a passphrase is specified as the password
for a special user, "sslway" and "config",
representing the kind of configuration.
PLATFORM SPECIFIC ISSUE
The passphrase to decrypt the private-key for SSL is given as
the password of a special user named "sslway" in a special domain, as this:
delegated -Fauth -a sslway:Passphrase -dgauth@admin
delegated -Fauth -a config:Passphrase -dgauth@admin
delegated -Fcredhy Passphrase < conf > conf.cdh
delegated -Fcredhy Passphrase -d < conf.cdh > conf
delegated +=conf.cdh
delegated +=http://server/path/conf.cdh
As shown in the examples, those special user names to hold passphrases
are in the special domain "-dgauth@admin" [DGAuth].
The storage for passwords in DGAuth are encrypted with a passphrase,
or MasterKey.
It can be specified as this:
CRYPT=pass:MasterKey
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:
FUNCTIONS
delegated -Fkill-hup -Pport
Version 10 Specific
% delegated -Fresolvy www.delegate.org
% ln -s delegated Resolvy
% Resolvy www.delegate.org
Example: doing "find . -ls" together with "du(1)"
delegated -Ffindu -ls -du
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"
Example:
delegated -Fauth -a ken:blahblah -smtp.users.local
// and refer this as AUTHORIZER=-smtp.users.local
Acronyms
${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
AUTHOR
@ @ ( - ) _< >_Yutaka Sato <y DOT sato AT delegate DOT org>
FEEDBACK
DISTRIBUTION
- help ... this information
- search ... searching Manual in a search engine (FreyaSX)
- decomp ... hyperlinks is rewritten to create decomposed view of each part
- parts ... each part is annotated and hyperlinks is rewritten as in "decomp"
- skeleton ... list of parts of Manual
- frame ... Manual is shown in frame
- [CTX] ... jump to the label of this part in the whole plain Manual
- [ALL] ... jump to the label of this part in the "decomp" version of Manual
DeleGate Version 9.9.10 + 10.0.0 Last change: September 28, 2014 --------- --------- --------- --------- --------- --------- --------- ---------