SERVER parameter* == SERVER=protocol[://host[:portNum]][:-:MountOptions] portNum == [+|-]number -- default: SERVER=delegate
Example: a SERVER parameter for unbound Telnet-DeleGate
If no destination server (host) is specified, it is to be be given by client somehow at run-time, on application level in protocol dependent way.
The protocol with server is implicitly expected to be the same with the protocol with the client. Some protocols like HTTP have their inherent way to specify the protocol with the destination server. Otherwise it must be explicitly given with MOUNT parameter, like MOUNT="/news/* nntp://server/*" for example.
SERVER=protocol://host:portNum specifies the URL of
destination server.
The ":portNum" part is 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
ADMIN parameter == ADMIN=user@host.domain -- default: built in at compile time
- Shown in (error) messages to clients, as the name of
the administrator of this DeleGate
(HTTP, etc.). |
- Shown in opening messages or in a help message to clients,
as the name of the administrator (FTP, NNTP, Telnet). |
- Sent as a default user name (in PASS command)
on anonymous access to FTP servers. |
- Sent as sender name (in FROM command)
in access to remote SMTP server on verification
by AUTH=anonftp:smtp-vrfy. |
- Report messages are sent to the address on occurrence of fatal signals |
OWNER parameter* == OWNER=user[/group][:srcHostList] -- default: OWNER="nobody/nogroup" -- restriction: super-user only on most of Unix -- restriction: setting the user of a service on Windows
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.
CRON parameter* == CRON="crontab-spec" crontab-spec == minute hour day month dayOfWeek action -- default: none
-suspend N | -- suspend for N seconds |
-restart | -- restart the DeleGate |
-exit | -- finish the DeleGate |
-expire N | -- execute expiration for $CACHEDIR by "-atime +Nd" |
-system command | -- execute command as a shell command |
/dir/command args | -- equiv. to "-system /dir/command args" |
- args | -- equiv. to "/dir/delegated args" |
-Ffunc args | -- equiv. to "/dir/delegated -Ffunc args" |
Example:
INETD parameter* == INETD="inetd-conf" inetd-conf == port sockType proto waitStat uid execPath argList port == [host:]portNum sockType == stream | dgram proto == tcp | udp waitStat == nowait ("wait" is not yet supported) -- default: none
Example:
INETD="8080 stream tcp nowait nobody - SERVER=http"
INETD="8080 - - - nobody - SERVER=http" (equivalent to the above)
INETD="8119 - - - - - SERVER=nntp://nntpserver/"
INETD="8888 - - - - /bin/date date" (equivalent to the following)
INETD="8888 - - - - - SERVER=exec XCOM="/bin/date date"'
INETD="8888 dgram udp - - /bin/date date"
INETD="localhost:8888 - - - - - /bin/sh sh"
INETD=+=/path/of/inetd.conf (load configuration from a file)
HOSTLIST parameter* == HOSTLIST=listName:HostList
Example:
CLUSTER parameter* == CLUSTER=[protoList]:ServerList ServerList == [/R,]Server[,ServerList] Server == Host[..Port]
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:
CMAP parameter* == CMAP=resultStr:mapName:connMap connMap == ProtoList:dstHostList:srcHostList -- default: none
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
If "fcl" is specified, a client may start SSL without STARTTLS negotiation. Such implicit SSL negotiation from the client-side is detected by peeping a SSL hand-shake packet on the connection from the client-side at the beginning of a session for a certain period specified with imimSec. The default value is "im0.25" (250m seconds). "-im" disables this implicit SSL negotiation. If a stlsSpec is followed with "/im" as STLS="fsv/im" for example, SSL with the peer (with the server in this case) is applied without the STARTTLS negotiation.
If "mitm" is specified, it behaves like "-fcl,-fsv" that is if SSL is enabled in the client side then SSL on the server side is enabled. It can be used with a HTTP proxy DeleGate as a "secure proxy" or "SSL-tunnel" to peep the bidirectional communication in CONNECT method, relaying it as a usual HTTP applying filters and cache. ("mitm" means "Man-In-The-Middle" mode) If it is set optional as "STLS=-mitm" then the MITM mode is activated only when the client specified the server name prefixing with "-mitm." as "https://-mitm.host.domain/" for "https://host.domain/".
If non default SSLway command path or options are necessary to be used, the SSLway command can be specified after stlsSpecs as STLS="fcl,sslway -Vrfy -cert mycert.pem" for example.
Example:
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:
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,...
DELAY parameter* == DELAY=what:seconds -- default: DELAY=reject:60,unknown:60,...
reject | -- | continuous Reject resp. from self or MOUNTed servers [60] |
unknown | -- | continuous Unknown resp. from self or MOUNTed servers [60] |
reject_p | -- | continuous Reject resp. from origin server [0] |
unknown_p | -- | continuous Unknown resp. from origin server [0] |
Each value specifies the maximum delay time and delay time increases according as the error count increases.
MOUNT parameter* == MOUNT="vURL rURL [MountOptions]" -- default: MOUNT="/* SERVER_URL*"
If a vURL is terminated with "*" then partially matched path is also rewritten. If a rURL is terminated with "*" then remaining part in the partially matched path will be copied after the rURL.
Example: a MOUNT for HTTP-DeleGate
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
do -- enable all counters including "total,acc,ssi,ref,err" total -- enable the total hit counter of this server acc -- enable access counters for each access to each URL ssi -- enable access counters for SSI (by PAGE_COUNT in .shtml) ref -- enable referrer counters for HTTP "Referer:" err -- enable error counters (for SMTP) ro -- enable counters in read-only no -- disable counters [default] mntpV -- use the counter of the MOUNT point (vURL) instead of each URLIf enabled with COUNTER="do", all access counters for any requests, referrers, and errors are incremented. If enabled with "total", the access counter for any requests to this server is incremented. If enabled with "acc", access counters for any requests to each target URL is incremented. If enabled with "ssi", only the access counter for the URL of a SHTML page including a SSI PAGE_COUNT reference is incremented when the page is accessed. If enabled with "ref", the referrer counter of the URL in the HTTP "Referer:" fields is incremented.
Each access counter is stored in a file at "ADMDIR/counts/access/URL#count". Each counter file starts with a line consists of the numbers of accesses in ASCII decimal format so that it can be initialized or modified manually. The line can contain three numbers; the first one is the total count, the second one is the count excluding repetitive accesses from the same client, and the third one is the count excluding repetitive access from one of recent ten clients. Each count are represented as %T, %U and %V respectively in the format string described below.
The counter can be displayed in a specified format using SSI as the PAGE_COUNT or COUNTER value. If no "url" attribute is specified in a tag, the URL of the SHTML file containing the tag is implied. Counter values are converted to a printable character string following to the format string given in the "fmt=..." attribute. The default format is "%T".
Format Specifiers:
%T -- total count %U -- the count excluding repetitive accesses form a client %V -- the count excluding repetitive accesses from recent 10 clients %N -- the number of networks [ 0 - 1023 ] %M -- the map of networks %L -- the list of the last ten clients %mT %mU %mV -- mean counts per day %mHT %mHU %mHV -- mean counts per hour %tC -- the time of the first count (counter creation) %tT %tU %tV -- the time of update of each countThe specifier %N represents the number of networks of clients where each network is with net-mask of 10 bits (0xFFC00000 255.192.0.0/10). This means that the whole IPv4 address space is divided into 1024 networks. So the %N represents the distribution of clients onto networks over the address space as a coverage value in per-mill. %M shows the distribution of clients as a visual map.
Example:
<!--#echo var=PAGE_COUNT --> <!--#echo var=COUNTER --> <!--#echo var=COUNTER fmt="%T hits since %tC" --> <!--#echo var=COUNTER url="URL" --> <!--#echo var=COUNTER fmt="%U/%T hits" --> <!--#echo var=COUNTER url="URL" fmt="%U/%T hits" -->The total count is displayed by TOTAL_HITS tag or by COUNTER tag with "sel=total". The referrer counter of a URL is incremented when the URL is in "Referer:" header in a HTTP request. Each referrer counter is stored in a file at "ADMDIR/counts/referer/URL#count-ref". The referrer counter can be displayed with "sel=ref" attribute in the COUNTER tag.
Example:
<!--#echo var=TOTAL_HITS --> <!--#echo var=COUNTER sel=total --> <!--#echo var=COUNTER url="URL" fmt="%U/%T refs" sel=ref -->
Enabling all counters for each URL can be expensive and/or unnecessary. You can reduce counters by using the counter of a MOUNT point as the representative, or using only total access counters of the server. In the following example, counters for all URLs is enabled by default (with COUNTER=do), while counters for URLs under /srv1/ is represented by the counter of /srv1/, and only the server's total counter and SSI counters are enabled for URLs under /mine/. As shown in this example, COUNTER can be specified as a MountOption of which initial value is inherited from the COUNTER parameter.
Example:
COUNTER=do MOUNT="/srv1/* http://srv1/* COUNTER=mntpV" MOUNT="/mine/* file:dirpath/* COUNTER=no,total,ssi"
CACHE parameter* == CACHE=cacheControl[,cacheControl]*[:connMap] cacheControl == do | no | ro connMap == ProtoList[:[dstHostList][:srcHostList]] -- default: none -- restriction: applicable to HTTP, FTP, NNTP and Gopher
do -- create CACHEDIR if not exist (to enable cache) no -- disable cache ro -- use cache in read-onlyCache is enabled by default. Cache will be disabled if the CACHEDIR directory does not exist, or it is not readable and writable by the DeleGate, or CACHE="no" is specified, or "cache" is not included in CONNECT.
EXPIRE parameter* == EXPIRE=validity[/custody][:connMap] connMap == ProtoList:dstHostList:srcHostList validity == period custody == period period == Num[d|h|m|s] -- default: EXPIRE=1h
CACHEFILE parameter == CACHEFILE=fileNameSpec -- default: CACHEFILE='$[server:%P/%L/%p]'
%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.
FILTER CONTROL OPTIONS: options to get status information from,
or control synchronization with filter program.
-w -- wait the filter process to exit before starting relay
-p -- detach the filter when it exits then continue relaying
BUILT-IN FILTERS: if a filterCommand is prefixed with "-",
then it is a filter built-in to DeleGate.
-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: 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'
LOGDIR parameter == LOGDIR=dirPath -- default: LOGDIR='${VARDIR}/log'
LOGFILE parameter == LOGFILE=[LogFilename] PROTOLOG parameter == PROTOLOG=[LogFilename][:logFormat] ERRORLOG parameter == ERRORLOG=LogFilename TRACELOG parameter == TRACELOG=LogFilename -- default: LOGFILE='${LOGDIR}/${PORT}' -- default: PROTOLOG='${LOGDIR}/${PORT}.${PROTO}' -- default: ERRORLOG='${LOGDIR}/errors.log' -- default: TRACELOG='${LOGDIR}/ptrace.log'
The patterns ${PROTO} and ${PORT} will be substituted with the protocol name and the port number of this DeleGate respectively. These files and directories will be created automatically by DeleGate if possible. You can stop logging by specifying null file name like LOGFILE="" or PROTOLOG="".
The format of PROTOLOG for HTTP is compatible with the common logfile format and is customizable. The format of PROTOLOG for FTP is compatible with xferlog.
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