((((((( ``DeleGate Home Page'' is at http://wall.etl.go.jp/delegate/ ))))))) ((((((( Read http://wall.etl.go.jp/delegate/tutorial/ first. ))))))) >>>>>>>>>>>>>>>>>>>>>>>>>>>>>> HALF DONE (^_^; <<<<<<<<<<<<<<<<<<<<<<<<<<<<< DELEGATED(8) MAINTENANCE COMMANDS DELEGATED(8) NAME delegated - DeleGate server SYNOPSIS delegated -P [-v[v|t|s|d]] [-F] [name=value]* DESCRIPTION Delegated is the DeleGate server process which relays TCP/IP protocols like HTTP, Gopher, Whois, FTP, Telnet, NNTP, SMTP, POP, and so on. The DeleGate mediates communications between a server and a client those are isolated from each other by FIREWALL for security. If necessary, DeleGate also achieves caching, domain name resolution, and JIS character code conversion by proxy for clients. The DeleGate supports a kind of MOUNTing that gives a integrated view for distributed services on remote hosts, which may be hidden in a firewall. A pair of DeleGate servers can be chained to form a TUNNEL that convey TCP/IP communication via non TCP/IP protocols like tty I/O on a phone line, because the inter DeleGate communication does not depend on TCP/IP. Unlike other proxy servers like SOCKS or PROXY_HTTP, NO modification for HTTP and Gopher clients is necessary to cope with DeleGate. Thus any existing client programs on various platforms are able to enjoy the benefits of DeleGate right away (see DEFECT). To redirect the request from client for the DeleGate, it rewrites URLs in HTTP and Gopher Directory Entity(DirEnt) in response message, so that the requests referring the URL or DirEnt are directed to the DeleGate's port again. A pair of original host and port is encoded in special format into the URL or DirEnt selector part. This bidirectional rewriting mechanism realizes `MOUNTing'. MOUNTING means, for example, showing a resource http://hosti/ as if it is http://hostx/iii for users. To realize this, link information in a response message, like is rewritten to . There are two types of delegated, `SPECIALIST' and `GENERALIST'. From a client view, SPECIALIST delegated looks like a server of specified protocol at the specified host; it behaves like a httpd or gopherd on a remote host. It is SPECIALIST that makes rewriting URL and DirEnt when relaying response from the server to the client. When a SPECIALIST cannot reach the destination server directly, or it wants to connect to the caching server, it forwards a request to and receives the response from GENERALIST delegated. A GENERALIST accepts a request in the `DeleGate protocol', relays it to the server and keeps the response data in the cache. The following shows a typical configuration of DeleGate server chain. # # # # P client -> SPECIALIST -+ [A] # [B] # +-> P server *protocol P +-> GENERALIST --+-> GENERALIST -+-+ | *without DNS # *with DNS # | Q client -> SPECIALIST -+ *with cache # *accept [A] # +-> Q server *protocol Q # only # *JIS code conv. # # The GENERALIST[A] on the internal host accepts requests from any hosts, whereas the GENERALIST[B] on the firewall accepts request from GENERALIST[A] only. In this configuration, GENERALIST[B] may be substituted with a Proxy_httpd. In another configuration, SPECIALISTs may be connected to GENERALIST[B] directly. GENERALISTs can be chained in any number of hops, thus you can overcome multiple firewalls, place multiple caches at multiple hosts with different expiration, and so on. OPTIONS The -P option specifies the server's port number as . This option is ignored when the delegated is invoked from inetd(8). Both `nowait' and `wait' status may be specified in inetd.conf. In `nowait' status, the delegated will processes just one service and exits. In `wait' status, the delegated will process multiple services, which count may be limited to N by "MAXIMA=service:N". When the host machine has multiple network interfaces or multiple IP addresses bound on a physical network interface, you can select one of them to which the delegated is bound, with the specification format -P:. A delegated can accept from multiple ports or (limited) multple network interfaces by -P,,,... where is either of : or . A port in -P option is made as a TCP port by default. It can be made as a UDP port with postfix "/udp" to port number like -Pxxxx/udp, regardless of the application protocol which will be specified in a SERVER parameter. If -v option is specified, the delegated will run foreground and log will be put on the control tty. More detailed log than that of -v can be get using -vv option. Similarly you can control the detailness of log to be written into logifle by -vt or -vd options; -vt make log terse whereas -vd make it detailed with debug information. With -vs option makes logging stop and be silent; this option has similar effect with LOGFILE="". If -F option is specified, the delegated will work as a program of rathar than DeleGate server. Available functions are ``kill'', ``cgi'', and so on. -Fhelp will show the list of available functions. "delegated -Fkill -P" means to kill the delegated running on the . With -Fcgi, DeleGate act as a cgi program which is invoked form a HTTP server. Other options specified in name=value pair are optional and can be set as environment variables. Options can be loaded from external resources. See SUBSTITUTION. name value format -------- ----------------- SERVER proto://host:port -- of what SPECIALIST it should be *ROUTE gateway-_-dst:src -- route toward gateway if from src to dst *MASTER host:port -- where MASTER GENERALIST DeleGate is MASTERP host:port -- MASTER private to the delegated PROXY host:port -- where a Proxy server is on *CONNECT {ca,ma,di}* -- the order connections shold be tried RIDENT {client,server} -- forwarding remote socket id. TUNNEL type:script-name -- SHIO-script file for DeleGate Tunneling DELEGATE host:port -- where URL and DirEnt should be redirected *HOSTS host/addr,... -- private host/address resolution list RESOLV {file,nis,dns}* -- control usage of hosts file and DNS RES_CONF URL -- where resolv.conf is RES_NS dnsHost -- specify DNS server to be used RES_RR HostsList -- round robin IP-address-list for the hosts RES_VRFY "*.INVALID" -- hostname returned on verififcation failure SOCKS socks-host -- control usage of socks SSLTUNNEL Host:Port -- connect via SSL tunneling (on HTTP) *MOUNT "path URL opt" -- mount the URL at //${DELEGATE}/path *RELIABLE HostList -- accept only from the specified hosts *REACHABLE HostList -- only specified hosts are reachable REMITTABLE protocolList -- protocols remittable to the server *PERMIT Proto:Dst:Src -- protocols/server/client to be permitted *RELAY {proxy,delegate} -- restrict proxy functionality *CHARCODE {JIS,EUC,SJIS,II} -- conversion of Japanese code in response DGROOT dir-name -- root directory of all of DeleGate files VARDIR dir-name -- default base of LOGDIR, WORKDIR, CACHEDIR CACHEDIR dir-name -- where HTTP/Gopher cache are placed CACHEFILE file-name-spec -- in which file cache data are stored CACHE cache-condition -- condition to determine do cache or not *EXPIRE {days,hours,secs} -- expiration of the cached data EXPIRELOG file-name -- file which records expire log ETCDIR dir-name -- where persistent management files are LOGDIR dir-name -- where DeleGate logs are LOGFILE file-name -- where DeleGate make logging ERRORLOG file-name -- where DeleGate make error logging PROTOLOG file-name -- httpd or wu-ftp compatible log file COUNTER field:dir-name -- where counter files for the field are WORKDIR dir-name -- where DeleGate should dump core (-_-; ACTDIR dir-name -- where temporary files are placed TMPDIR dir-name -- where invisible temporary files are placed PIDFILE file-name -- where the delegated's PID is recorded OWNER user-name -- who's process the delegated should be ADMIN user-address -- E-mail address of the manager of DeleGate PUBLIC proto://host:port -- let this delegated public from that one HTMLCONV deent,enent,pre -- decode / encode between HTML & plain text *URICONV convList:attrList -- control URI rewriting MIMECONV thru,charcode -- control MIME encoder/decoder *DELAY what:seconds -- sleep *TIMEOUT what:seconds -- timeout of connection *MAXIMA what:number -- maxima of servers and etc. OVERRIDE master:paramlist -- override limits in the MASTER *AUTH what:aproto:users -- authorized users for remote management *AUTHORIZER serv:prt:dst:src -- authentication server DGPATH dir1:dir2:... -- search path of substitution resources FFROMCL filter-command -- filter of data from client to delegated FTOCL filter-command -- filter of data from delegated to client FCL filter-command -- filter of data between client and delegated FFROMMD filter-command -- filter of data from server to delegated RPORT {tcp,udp}:host -- connection for the server to the delegated HTTPMAIL server:relay -- access HTTP via mail SMTPSERVER mailserver -- SMTP server for mail posting from delegated FILETYPE suffix:type-spec -- filename to type conversion *CMAP mapspec -- mapping table about the cuurent connection *NNTPCONF spec-list -- NNTP specific configuration *CRON cron-spec -- sceduled actions *INETD server-conf -- inetd like server configuration notation *ICP icp-client-config -- ICP client configuration *ICPCONF icp-server-config -- ICP server configuration *DNSCONF dns-server-config -- configuration as a DNS server VSAP VSAP-server -- accept/connect via the remote socket mapper PORT port-list -- reserve ports *HTTPCONF config-script -- http configuration SMTPGATE config-dir -- SMTP to SMTP/NNTP gateway config. dir CGIENV list-of-env-vars -- environment variables to be passed to CGI ---------- ----------------- HostList host,net/mask,... -- a list of hosts/nets with optional mask ProtoList [-]protocol,... -- a list of protocols In above list, names prefixed with `*' may be repeated in command line argument as nameX=value1 nameX=value2 ... nameX=valueN. If other names are repeated, the lastly given value is taken. The prefiex `#' means that the function is obsolete and will be removed in the near future. SERVER proto://host:port (default: none) SERVER proto (means proto://-/) *SERVER proto://host:port:-:MountOptions If specified, the delegated will become SPECIALIST DeleGate, which behaves like a server of `proto' protocol at `host:port'. If not specified, the delegated will become GENERALIST DeleGate, which gets request from SPECIALISTs, other GENERALISTs, or clients who speak the DeleGate protocol. The third parameter format with mountOptionList specifies that the SERVER will be dynamically selected if the condition specified in the conditions in MountOptions is true. Example: SERVER="nntp://newsserver1:-:from={*.dom1}" SERVER="nntp://newsserver2:-:from={*.dom2}" A special protocol name "exec" means executing some local command rather than connecting to a server. With "exec", DeleGate will work like simple "inetd" or "wrapper". What will be executed is specified with either XCOM or XFIL parameter. Commands executed as XCOM will be given standard I/O which are bound for a socket connected to the client. Commands executed as XFIL will be given standard I/O which are redirected to a pair of pipes bound for DeleGate, which relays it to and from the client. Example: -P8023 SERVER=exec XFIL=command.com WORKDIR="/" (Use command.com of Windows95 as a simple telnet server) 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. *ROUTE proto://host:port/-_-{dstHostList}:{srcHostList} (default: none) Forwards requests from hosts in srcHostList to the resources listed in dstHostList toward the server at `host:port' in `proto' protocol. ROUTE is a generalized notation for MASTER, PROXY. A host specification in a HostList may be prefixed with "proto://" to restrict the protocol to be forwarded. For example, ROUTE="http://h:p/-_-{ftp://*}:*" means that only access to FTP servers are forwarded to the proxy at "http://h:p/". A host specification in a HostList can be restrected more with port number. For example, ROUTE="http://h:p/-_-{*:21}:*" means that only accesses to the port number 21 (FTP service) is routed to the proxy. NOTE: The notation can be extended as `gateway-_-/Modifier/dst:src' where Modifier controls caching or code conversion according to the route. *MASTER host:port (default: none) *MASTER host:port:HostList *MASTER host:port/master_control:HostList MASTER is the abbreviation of ROUTE="delegate://host:port/-_-HostList:*". The port of a GENERALIST delegated should be specified here. If specified, the delegated will forward a request from the client to the specified MASTER delegated, if the destination host is not reachable, or the name is not resolvable, or the "master" is specified in CONNECT parameter for the current protocol and the host. Forwarding for the MASTER can be filtered by postfixing HostList, a list of host and net addresses. In this case, only listed destination hosts/nets are forwarded to the MASTER. See the HostList below about how to write it. When multiple MASTERs are given, they are tried from the first one to the last one until connection to the MASTER success. In the third form of MASTER has ``/master_control'' after the port number. cache -- read only cache in the MASTER teleport -- make persistent ``Teleport'' connection to the MASTER MASTERP host:port (default: "" for HTTP Specialists) This parameter may be given for the HTTP Specialist delegated. HTTP Specialists need MASTER delegated for data cache for non HTTP protocols and connection cache for FTP and NNTP. When neither MASTER nor MASTERP is given, MASTERP="" is used as a default value, which means making private MASTER automatically at a dynamically assigned port number. Both of MASTER and MASTERP="" may be specified together to force caching at the local host when the MASTER is running at a remote host. PROXY host:port (default: none) *PROXY host:port:HostList Only HTTP SPECIALIST and FTP SPECIALIST can specify this variable. For HTTP SPECIALIST, PROXY is the abbreviation of ROUTE="http://host:port/-_-HostList:*". The port of another HTTP SPECLIALIST or Proxy_httpd could be specified here. (Proxy_httpd is a HTTP server which accepts fully specified URL in method argument of request messages). If this parameter is specified, the delegated will forward request to the PROXY server. Proxy FTP can be chained with PROXY parameter like follows; SERVER=ftp PROXY=proxyhost:proxyport. *CONNECT {cache,icp,master,vsap,direct,socks,udp}*:ProtoList:dstHostList (default: c,i,m,h,d,v,s:*:*) This parameter controls the order of trials for connection to the target server using several connection method as followings: cache -- cache search (without connection) icp -- via a PROXY hinted by ICP server master -- via a MASTER DeleGate server https -- SSL tunnel on HTTP vsap -- via a VSAP server direct -- direct connection to the target server socks -- via Socks servers udp -- by UDP Each connection type can be abbreviated by the first character as {c,i,m,d,v,s,u} respectively. If protoList and dstHostList are given, this control is applyed only to the protocols and hosts included in the list. 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 list, ProtoList should be "*", PROXY cannot be controlled. In the future, the cache type could be followed by timeout period, like `direct/10s' or `cache/5d'. A combination of -Pxxxx CONNECT=udp relays from TCP client to UDP server, and -Pxxxx/udp and non-udp CONNECT relays from UDP client to TCP server. RIDENT {client,server}* (default: none) If RIDENT="server" is specified, identification information about the client socket got by getsockname(2) and getpeername(2) will be forwarded to the PROXY or MASTER DeleGate which will receive the information by RIDENT="client", and will use it for access control. A DeleGate server with RIDENT="client" can accept both from DeleGate with RIDENT="server" and other proxy servers with no RIDENT support. An intermediate DeleGate in a chain of cascaded DeleGate servers should be given RIDENT="client,server". TUNNEL type:script (default: none) If specified, communication with the MASTER will be `tunneled' via the standard input/output of the command. The tunnel may be made of serial line without TCP/IP handling. Otherwise it may be the channel to the delegated which is invoked from the inetd. The type part specifies TUNNEL type, currently only `tty7' and `proc' is available. When the type is tty7, How the TUNNEL is established is described in the specified `SHIO script' file. See the src/sample.shio in the distribution file. When the type is proc, then the script part should be specified as a shell command. *HOSTS name/addr (default: localhost/127.0.0.1) List of domain-names/IP-addresses pairs which will override DNS (or NIS or /etc/hosts table) data. This could be used for speed-up of resolution for frequently referred hosts, aliasing, or relief of unknown hosts in public delegate. Multiple names or addresses could be specified in the form {name1,name2,...}/{addr1,addr2,...} RESOLV {cache,file,nis,dns,sys}* (default: cache,file,nis,dns,sys) Specify which name resolver should be used in what order. `file' means local host file like /etc/hosts, `nis' means hosts map on NIS service, `dns' means DNS service, and `sys' means using gethostbyname() and gethostbyaddr() function which usually call system's standard resolver of the host. If empty value is specified as "RESOLV=" then only hosts listed in HOSTS parameter can be resolved (this could be useful when you must hide hosts table for security consideration). Each resolver can be specified with optional argment like follows: cache:/path -- path name of cache directory [/tmp/resolvy] file:/path -- path name of password file [/etc/hosts] nis:nis-domain -- NIS domain name dns:dns-host -- DNS server and default domain 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_CONF URL (default: /etc/resolv.conf) Specify where the ``resolv.conf'' file is. The file is interpreted by the DeleGate original resolver named ``Resolvy''. Resolvy recognizes "nameserver", "domain", "ndots", "search", and "sortlist" in it. RES_NS dnsServer (default: none) RES_NS dnsServer //socksHost Specify a DNS server to be used: dnsServer is a host name or an IP-address of the host name DNS server, which may optionally be followed by port number, like "host:8053" when the port number is not standard port(53). In the second form, a DNS server on the dnsHost beyond a firewall can be referred through a Socks V5 server. RES_RR HostsList (default: "*") Round robin IP-address-list for the hosts included in the HostList. Currently, only RES_RR="*" and RES_RR="" are supported. RES_VRFY (default: none) With "RES_VRFY=", results of reverse look-up of DNS server is verified. When an is resolved to , and when the is resolved to which does not include the , the varification fail and the result is ignored. ## With RES_VRFY="*.INCONSISTENT", the inconsistent host name "host.domain" ## will be marked as "host.domain.INCONSISTENT". SOCKS sockd-host/dns-host/dflt-domain (default: none) SOCKS sockd-host/-5 Specify to use SOCKS server on `sockd-host'. If you use the SOCKS_DEFAULT_SERVER specified at compile time, empty specification "SOCKS=" is sufficient. Multiple SOCKS parameters can be specified. The order of trial of connection directly and via Socks can be controlled with the CONNECT parameter. In the second form, host name resolution will be achieved at the Socks server of the Socks version 5 protocol. *MOUNT "path-pattern URL" (default: "/ ${SERVER}") *MOUNT "path-pattern URL MountOptions" Redirect the path to/from the URL. If a path-pattern is terminated with `*' then partially matched path is also rewrote. If a URL is terminated with `*' then remaining part in the partially matched path will be copied after the URL. For example, the specification MOUNT="/abc/* http://H:P/*" in a HTTP/DeleGate specifies to rewrite a URL "/abc/def" to "http://H:P/def". This pattern matching can be restricted with a notation "[a-set-of-characters]" prefixed before `*', like MOUNT="/abc/[a-z]* http://H:P/*", which matches with arbitrary strings starting with a character listed in "[set-of-characters]". If `=' is specified as path-pattern or URL, it means mount `as is', that is, rewriting for the path-pattern in a request, or rewriting for URL in a response will be suppressed. MOUNT can be used in 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 `aias-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 delegated merges the newsgroups on the servers, and serves the newsgroups to a client as if they are on a single server. MountOptions MountOptions is a list of options listed bellow separated by `,' character. ro -- Read only for NNTP protocol to inhibit POST command moved -- Don't relay but return `302 Moved' response in HTTP indirect -- Example: where MOUNT="URL1/* URL2/* indirect" is given, when "URL1/name1/path" is requested, if "URL2/name1/indirect.cfi" contains "Base: URL3", then "URL3/path" will be accessed. This is done by generating MOUNT="URL1/name/* URL3/*". robots={no,ok} -- disable or enable access from robots. The default value for NNTP and FTP is "no", while it is "ok" for other protocols. from={HostList} -- from the client. the mount specification will be applied only when the client is included in the HostList. via={HostList} -- via the host. the mount specification will be applied only when at least one host passed through is included in the HostList. path={HostList} -- through the hosts the mount specification will be applied only when all of hosts passed through is included in the HostList. host={HostList} -- interface host with the client. the mount specification will be applied only when the client has connected to the delegated via the specified network interface included in the HostList. When the delegated is acting as an origin server and a virtual host name is shown in "Host: host" field in the request message, the virtual name is examined prior to the real host name. If multiple virtual names are bound to the same IP-adrress, prefix "-" to the virtual hostname like "host=-hostname" to distinguish among virtual names. genvhost=host -- Set "Host: host" field in the request message to be forwarded to the server. hide={GroupList} -- List of patterns of news group names to be hidden to NNTP clients. (ex. "hide={alt.*,!alt.comp*}") upact:Invoke/Reload/Posted -- control updating of active list cache. The same meaning with the NNTPCONF=upact:... except this controls only the destination server of this MOUNT parameter. cache=no -- disable any usage of cache for the server cache=no-article -- disable NNTP ARTICLE caching. cache=no-list -- disable NNTP LIST caching. cache=no-overview -- disable NNTP XOVER caching and generating it from ARTICLE by DeleGate. useproxy[=proxyURI] -- generate "305 Use Proxy" response message. If proxyURI is omitted or given as "direct", the response message is sent with Set-Proxy field as "Set-Proxy: DIRECT". Otherwise the URI is set in the filed as "Set-Proxy: SET; proxyURI=proxyURI". method={methodList} -- true if the access method of the current request is included in the methodList. dst={hostList} -- true if the destination host is included in the hostList. This option will be useful when "=" is used as the ringht hand of MOUNT option. asproxy -- true if the delegated is called as a proxy server that is the requeted URL is in full URL format. withquery -- true if the requested URL has "?query" componet charcode=code -- code conversion specific to the mount point, in the same meaning with global CHARCODE parameter 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: 1) MOUNT="* URL1 host=this-host" MOUNT="* URL2 host=localhost" 2) -P70,80 MOUNT="* URL1 host=*:70" MOUNT="* URL2 host=*:80" "useproxy", "method", "dst" and "withsearch" options are introduced originally to refuse potentially troublesome acesses which may invoke CGI programs in target servers. For example, to refuse any request with POST method, or with URL including "?": MOUNT="http:* = method=POST,asproxy,useproxy" MOUNT="http:* = withsearch,asproxy,useproxy" ?AUTOMOUNT where:URLList ((Not yet done)) Mount URLs listed in the URLList at `where/${URL}'. If `where' is omitted, they are mounted at `http://${DELEGATE}/' for HTTP and FTP, and `http://${DELEGATE}/${GTYPE}/' for Gopher. DELEGATE host:port (default: current-host:current-port:all) DELEGATE host:port:ProtoList This parameter controls relaying function for non-Proxy HTTP/Gopher access by URL/DirEnt rewriting with `Gateway-_-URL' or `proto://host:port/-_-URL' notation. The host and port of delegated which will be encoded into the URL/DirEnt should be defined here. By default, current-host is encoded in raw IP address number so that clients can reach the delegated even if they don't know how to resolve the host name of the delegated. In the second specification form, DELEGATE is followed by ProtoList, a list of protocols. This list specifies which protocols should be called back to, or detained to the DELEGATE. The URLs and DirEnts in a response message are redirected to the DELEGATE if the protocol is listed in this variable. To suppress the relaying function, specify this parameter as "DELEGATE=-:0:-all". *PERMIT ProtoList:dstHostList:srcHostList Each PERMIT parameter specifies what kind of accesses should be permitted by the DeleGate. An access will be permitted if the access is from a client host included in srcHostList, to a server host included in dstHostList, with a protocol included in ProtoList. If no PERMIT parameters is given, access permission is controlled by REMITTABLE, REACHABLE and RELIABLE parameters which can be defined explicitly or implicitly based on SERVER parameter. 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 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 acceptable clients in srcHostList. The host specifications in the dstHostList can be restricted with port number. For example, PERMIT="telnet:{*:23}:*" means permitting telnet only for the standard port number (23). A protocol name in the ProtoList can be modified like "protocolname/{PortList}/{MethodList}" to restrict accessible ports and methods of 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 next DeleGate server using RIDENT parameter and will be examined using PERMIT paramter. REMITTABLE ProtoList (default: "*" -- for GENERALIST, "." -- for SPECIALIST) Only protocols (to the server) listed in ProtoList will be accepted by the delegated. For GENERALIST (a delegated without a SERVER specification) any protocols is permitted by default. For SPECIALIST, only the protocol specified in the SERVER parameter (which can be represended by ".") is permitted by default. If a protocol name is followd by `/{PortList}', only ports listed in the PortList is permitted. As a special case, delegated as a proxy Telnet (with SERVER="telnet") is restricted to be accessible only toward standard Telnet port (23), with REMITTABLE="telnet/23" by default. This restriction can be disarmed by specifying like REMITTABLE="telent". For HTTP-SPECIALIST, "REMITTABLE=http,https/{443,563},gopher,ftp,wais" is the default. A PortList can be followed by "/{MethodList}" which restricts available methods in the protocol. Currently, only "readonly" is supported. For example, REMITTABLE="ftp//readonly" make the FTP-DeleGate be "read only" which inhibits uploading to FTP servers. Exceptionally, when the current destination server is determined by a MOUNT parameter like MOUNT="Path1 Proto://Server/Path2", the protocol "Proto" is automatically allowed as a destination protocol. If the first element of the list is "+", it means the default list of permitted protocols. For example, REMITTABLE="+,-https/563,-wais,file" with SERVER=http means REMITTABLE="http,https/443,gopher,ftp,file". *RELAY {proxy,delegate,no} *RELAY {proxy,delegate,no}:protoList:dstHostList:srcHostList (default: proxy,delegate:*:*:.localnet ; proxy:*:*:*) This parameter controls in which way the delegated works as a HTTP proxy server. HTTP DeleGate works in two ways: as a standard (CERN compatible) HTTP proxy which accepts full URL in a request, and as a DeleGate original proxy which accepts /-_-URL in a request and rewrites URLs in the response. With the second (full) specification format, available relaying mode can be classified by combination of server protocol, server host and client host. EXAMPLE: RELAY=no ... does not work as a proxy RELAY=proxy ... CERN compatible mode only RELAY=delegate ... DeleGate mode only (/-_-URL) RELAY=proxy,delegate ... both CERN and DeleGate mode DEFAULT: Both "proxy" and "delegate" are allowed to users on ".localnet", but only "proxy" is allowed to other users. *RELIABLE HostList (default: .localnet) Only request sent from hosts (or networks) listed in HostList will be accepted by the delegated. By default, only accesses from host and network local to the delegated's host is permitted (RELIABLE=".localnet"). See HostList below about how to write it. *REACHABLE HostList (default: none = any host is reachable) If specified, only request directed to the hosts (or networks) listed in HostList will be accepted by the delegated. CHARCODE {JIS,EUC,SJIS,II} (default: none) *CHARCODE input-code/output-code If specified, HTTP and Gopher SPECIALIST will convert the JIS code in text type response into the specified character code. A client can override this specification by sending its choice in `Accept-Language' field in a request. For example, if `Accept-Language: (charcode=JIS)' is sent in a request from client, the response text will be converted into JIS regardless of CHARCODE specification of the delegated. The full specification of the parameter value is input-code/output-code. CHARCODE=JIS is the abbreviation of CHARCODE=JP/JIS where JP means Japanese text encoding {JIS,EUC,SJIS}. You can specify CHARCODE=CN/JIS that means translation from Chinese text encoding {Big5,GB,HZ} to JIS. `II' means 'inline image'. Each Japanese character code in a response message will be converted to a '', which is a inline image of HTML. This will be useful for HTTP clients without Japanese fonts. II can be used other than Japanese. A notation `charset/II' specify encoding codes of `charset' into II. CHARCODE="II" is the abbreviation of CHARCODE="JISX0208/II" If `(charcode=THRU)' is specified in Accept-Language, any conversion is disabled. A set of Accept-Languages may be specified by a client in its menu or configuration file. DGROOT dir-name (default: undefined on Unix, "/Program Files/DeleGate" on Windows) If defined, all of sub-directories (LOGDIR, ETCDIR, ADMDIR, CACHEDIR, ACTDIR, WORKDIR and TMPDIR) will be located under the DGROOT. VARDIR dir-name (default: ${DGROOT:-/var/spool/delegate}) CACHEDIR dir-name (default: ${VARDIR}/cache) CACHEFILE file-name-spec (default: $[server:%P/%L/%p]) Caching will be enabled if the directory CACHEDIR exists, and it is both readable and writable for delegated, and CACHE="no" is not given. Currently, caching of HTTP, Gopher NNTP and FTP is supported. CACHEFILE specifies how the file name of a cache file is formed. The name is derived mainly from informations about server host and requested URL. Those informations are specified in the format "$[server:format]" where the format is a sequence of followings. URL of the resource: scheme://host.d2.d1:port/path %P -- Protocol name part scheme %L -- Login part host.d2.d1:port %H -- Host name host.d2.d1 %T -- Port number port %h -- host name directory d1/d2/host %d -- domain name directory d1/d2 %1 -- top level domain d1 %2 -- second level domain d2 %p -- URL-path part path %Q -- use FQDN of a host name host.d2.d1.d0 (like %Q%L or %Q%H) *CACHE cache-condition (default: none) Specify a restriction of cache usage. no -- cache is disabled [undef] ro -- cache is read only [undef] ## bintext -- binary text will be cached also [undef] ## mtime/Days -- original data is modified within Days [unlimited] ## dsize/Num -- data size is smaller than Num bytes [unlimited] ## xrate/Num -- transmission is slower than Num bytes/sec [unlimited] EXPIRE N{d,h,s} (default: 1d) *EXPIRE validity/custody (default: 1d/forever) *EXPIRE N{d,h,s}:protoList:dstHostList:srcHostList (default: none) EXPIRE specifies the term of validity of cached data, in one of days, hours, or minutes. Validity does not mean active removement of cached data by delegated; delegate merely ignores cached data if it is older than the specified term. ETCDIR dir-name (default: ${VARDIR}/etc) LOGDIR dir-name (default: ${VARDIR}/log) LOGFILE file-name (default: ${LOGDIR}/${PORT}) ERRORLOG file-name (default: ${LOGDIR}/errors.log) PROTOLOG file-name (default: ${LOGDIR}/${PORT}.${PROTO}) WORKDIR dir-name (default: ${VARDIR}/work/${PORT}) COUNTER field:dir-name (default: none) ((Not yet done)) EXPIRELOG file-name (default: ${LOGDIR}/expire.log) The patterns ${PROTO} and ${PORT} will be substituted with the protocol name and the port number of the delegated respectively. These files and directories will be created automatically by delegated if possible. You can stop logging by specifying null file name like LOGFILE="" or PROTOLOG="". The format of PROTOLOG for HTTP protocol can be modified with a optional format specification postfixed after the file-name as PROTOLOG="file-name:format". In this case, default file name can be suppressed. For example, PROTOLOG=":%X" specifies making a NCSA like extended common logfile format. The default format is PROTOLOG=":%C %D". %C -- common logfile format of CERN-HTTPD %c -- same as %C except the date is recorded in mili-second precision %D -- extention by DeleGate (conn-time + relay-time : status) %X -- '%C "%r" "%u"' common logfile format with Referer and User-Agent %r -- Referer field in the request message %u -- User-Agent filed in the request message %S -- status of CONNECTion to the server (c,m,p,d,s,v) The client information part in %C, which records hostname, Ident, and username by default, can be modified by AUTH="log:" parameter. If WORKDIR is not accessible, or if WORKDIR is not explicitly specified when -vv option is given, then current directory (of invoker of the delegated) will be used as WORKDIR. If `file-name's are specified in a relative path then they are placed under ${LOGDIR}. If those names start with "./" then they are placed under ${WORKDIR}. AGING: If the pattern `[date+format]' is included in the file name, it is evaluated by strftime(3) compatible function and will be substituted with the evaluated strings. For example, a format `%d' means day of month [01-31], thus when LOFILE is specified like LOGFILE='${PORT}[date+.%d]', the file will be aged day by day and will be rotated by a month. A format `%W' which means week number of year [01-52], is useful for week by week aging. Another example; LOGDIR='/var/log/delegate/[date+aged/%y/%m/%d]' will make hierarchical logs. 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. You can use another pattern `[start+format]' for aging. `start+' pattern will be evaluated in the same way with `date+' except that it will be substituted by time when the delegated started (or restarted by SIGHUP or specified TIMEOUT=restart). ACTDIR dir-name (default: /tmp/delegate } TMPDIR dir-name (default: none) PIDFILE file-name (default: ${ACTDIR}/pid/${PORT}) FTPGETS file-name (default: ${ACTDIR}/ftpget/${SERVERNAME}) Information about currently active servers are placed at ${ACTDIR} Those are temporary files which are made on invocation of a server and are removed at exit. OWNER user (default: `nobody' for root, otherwise invoker) OWNER user/group (default: `nobody/nogroup' for root, otherwise invoker) *OWNER user:srcHostList If specified, the delegated will run with the right of specified user, calling setuid() and setgid() system calls. User and group can be specified either in symbolic name or in id-number prefixed with `#'. If srcHostList is specifed, owner of the delegated 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 Ident server (identd). A simple example is OWNER="*:*@*". This variable is effective only when the invoker is a super-user. ADMIN user-address (default: none) You must specify this parameter when you invoke a delegated on the firewall or the hosts directly reachable to internet. This E-mail address will be used as follows: - Shown in (error) messages as the name of administrator of the delegated (HTTP). - Shown in opening messages or in help message as the name of administrator of the delegated (FTP, NNTP, Telnet). - Sent as user name (in PASS command) on anonymous FTP access to remote FTP servers. - Sent as sender name (in FROM command) in access to remote SMTP server on verification by AUTH=anonftp:smtp-vrfy. MANAGER user-address Equal to ADMIN. This is the former name of ADMIN parameter. *PUBLIC proto://host:port (default: none) If specified, the delegated will be registered as a public DeleGate. The registration is done by sending a message to the delegated at the specified `proto://host:port' when it is invoked. The registration will be removed when the delegated finishes. Specify PUBLIC="" for PUBLIC="http://wall.etl.go.jp/" to declare that your delegate is public to anyone in internet. HTMLCONV conv-list (default: deent) Specify a list of switch to control convertion for HTML text in a HTTP response message. deent -- decode entity symbol enent -- encode entity symbol fullurl -- convert all of URLs to full URLs (equals to URICONV="full:+,-HREF/BASE") Deent and enent control encoding and decoding of special characters between HTML and plain text. If `deent' is specified, encoded entity symbol like `<' in ISO-2022-JP text will be decoded into `<'. This will be useful with PROXY in Gopher gatewaying. If `enent' is specified then entity symbols out of ISO-2022-JP text will be encoded. This will be useful in case of NNTP/DeleGate for WWW client. If empty list is specified, no conversion is performed. URICONV convList:attrList (default: it will be shown by URICONV=dump) URICONV defelem:+,elemnameList URICONV defattr:+,attrnameList Specify which kind of URI rewriting should be applied to which kind of attributes of tags in HTML document. The convList is a list of following items. mount -- rewriting by MOUNT normal -- normalize MOUNTed URL if it includes abnormal "../" partial -- represent (MOUNTed) URLs as partial URLs if possible full -- convert all of URLs to full URLs The special convList URICONV="+" means loading the default URICONV configuration (no attrList in this case in the current implementation). The attrList is a list of attributes names each may be postfixed with an element name. A special attributes name ``+'' means the default set of attributes. An attribute prefixed with ``-'' character is excluded from the calculated set of attributes. EXAMPLE: URICONV=mount,normal,partial:+ -- might be the default after Ver.6 URICONV=full:+,-HREF/BASE -- rewrite everything exept HREF/BASE URICONV=dump -- show the current URICONV config. URICONV=+ URICONV=mount:-SRC/IMG URICONV=full:SRC/IMG -- don't apply MOUNT to MIMECONV thru,charcode (default: all) Control MIME encoding/decording in NNTP/POP/SMTP DeleGate. MIMECONV=thru disables any MIME encoding/decording, and MIMECONV=charcode enables only character code conversion. *DELAY what:seconds Delay for specified seconds before doing `what'. reject -- continuous Reject resp. from self or MOUNTed servers [60] unknown -- continuous Unknown resp. from self or MOUNTed servers [60] reject_p -- continuous Reject resp. from origin server [0] unknown_p -- continuous Unknown resp. from origin server [0] Each value specifies the muximum delay time and delay time increases according as the error count increases. *TIMEOUT what:seconds,... (default: dns:60,acc:30,con:30,lin:30) Specify timeout period (in seconds by default) of `what' which includes: shutout -- disarming emergent shutout set on fatail error [900] dns -- for DNS lookup [60] acc -- for accept from client (include FTP data connection) [30] con -- for connection to the server [30] lin -- LINGER for output [30] ident -- for connection to Ident server [10] io -- general I/O [600] hello -- for HELLO negotiation with the MASTER [30] login -- for login to proxy telnet/ftp [60] ftpcc -- for keeping alive FTP Connection Cache [900] nntpcc -- for keeping alive FTP Connection Cache [300] daemon -- delegated [unlimited] restart -- cause restart at every specified period [unlimited] (the unit of period can be changed like 1d, 1h, 1m) standby -- keep the delegated alive on standby for next client [30] http-cka -- keep the connection with the client alive [5] (the timeout is ten times longer for the first connection from each client host) takeover -- taking over a downloading to cache after the client which initiated the downloading disconnected [0] The timeout value `0' means `never timeout' (unlimited). *MAXIMA what:number,... (default: listen:20,ftpcc:2) Specify the maximum number of specified servers. listen -- server's queue size [20] delegated -- the number of delegateds runnable at a time [64] ftpcc -- the number of ftp connection cache servers to a host [16] nntpcc -- the num. of NNTP connection cache processes to a host[16] service -- the number of services per delegated process [unlimited] mailsplit -- maximum size of of each partial mail [50000] standby -- the maximum number of standby process [16] http-cka -- connection Keep-Alive [10] (the maximum is ten times larger for the first connection from each client host) http-ckapch -- the number of connection in Keep-Alive at a time for each client host [4] conpch -- the maximum number of connections at at time per client host [unlimited] OVERRIDE master:port:ParamList (default: none) Override limits in the MASTER. Currently only OVERRIDE="*:*:TIMEOUT=timeoutList" and OVERRIDE="*:*:CONNECT=cache" are supported. *AUTHORIZER authServ:protoList:dstHostList:srcHostList (default: none) Specify the server for authentication (with authorization possibly) for 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 only authentication of user is necessary without authorization, the following special name will be useful as a authServ. "&" -- the client host (user name on the client host is required) "*" -- any authHost specified by the client by "user@authHost" EXAMPLE: SERVER=telnet AUTHORIZER="&:::!*.local.domain" (clients from outside of local.domain is requred authentication) SERVER=telnet AUTHORIZER="localhost" RELAIBLE="*" (any clients is allowed if the user is authenticated with localhost) *AUTH what:authProto:who (default: none) Authorize `who' to do `what'. Authentication of user will be done using protocol specified in authProto. Identification about ``who is the client's user'' is done based on Identification protocol to the client host if it supports the protocol. Otherwise FTP-server may be used as an authorization server. Given Authorization information consists of Username:Password, where Username can be User@Host, if a trial login to Host with User and Password succeed, then the client is authenticated to be User@Host. Currently following three categories of authorization are supported: manager:*:user@host Permit `user@host' to perform remote management of the delegated including server restarting and logging control. The second field should be `*' in current implementation. See anonftp:*:password This parameter is referred from FTP/HTTP gateway. If specified, the delegated asks anonymous-ftp users to inform of his/her E-mail address as Login-name in the HTTP authorization scheme. If `password' field is specified as `*', then any Password in the authorization will be acceptable. The second field should be `*' in current implementation. anonftp:smtp-vrfy:* This parameter is referred by FTP proxy to check an E-mail address given as the password for the anonymous user. (The E-mail address must be sent as user-name in FTP/HTTP gateway). With this specifcation, invalid E-mail addresses will be rejected. When the address is valid but is in a format like "user@host", it will be expanded automatically to a FQDN format like "user@host.domain". If the third field is "-" (i.e. "AUTH=anonftp:smtp-vrfy:-@*") only the connectivity to mail server at "host.domain" is checked. # The third field can be the matching level of domains of verified # address and the address of the client host like follows: # E-mail:"user@host.d3.d2.d1" and client-host:"hostname@d3.d2.d1" proxy:{ident,auth,pauth} (default: proxy:ident) Specify identification/authorization protocols for the delegated as a HTTP proxy server. This parameter is checked only when access control for user is specified in PERMIT or RELIABLE. ident -- Identification protocol pauth -- Use Proxy-Authorization field `user@host:password' auth -- Use Authorization field `user@host:password' Example: AUTH=proxy:auth PERMIT="*:*:{*,!?}@*" Any user at any host is allowed as long as he/she is identified. NOTE: When the client does not support Proxy-Authentication, you are obliged to use `auth' for Authentication. In such case, note that the client cannot access resources which requires Authentication. forward:{by,for,ver,*} Put identification information of the source host in the ``Forwarded: by Me (Ver) for Client'' field in a HTTP request header field, if the destination host is included in the dstHostList and the source host is included in the srcHostList. Currently, if this is specified, it is regarded as AUTH="forward:*:" regardless of the second field. This is usefull for a delegated on a firewall which relays internal HTTP servers towoard outside . authgen:basic:authString Generate ``Authorization: Basic authString'' in a HTTP request header if it does not have an original Authorization field. The authString should be "userName:passWord". The following special string stand for attributes of clients. %u -- user name got using Ident %h -- host name of the client got from the socket %i -- host name of the network interface to the client %a -- host address of the client %n -- network address of the client %H -- hostname of the delegated %M -- the ADMIN of the delegated %A -- generated string by "CMAP=string:authgen:mapSpec" Example: When the firewall have two network interfaces and internal and external hosts access from different interface, then they can be distinguished by the name of interface. AUTH="authgen:basic:%i:%h" Otherwise, internal networkd should be explicitly defined using CMAP as follows. AUTH="authgen:basic:%A" CMAP="{internal:passWord}:authgen:*:*:{IntenalNetList}" CMAP="{external:passWord}:authgen:*:*:*" A genereted password is formatted as "passWord/%i" and a delegated rejects incoming requests with an Authorization field of such pattern. Thus forged password cannot pass the delegateds on the host. fromgen:fromString If specified, "From: fromString" will be put in the HTTP request if the original header does not have an original From field. If fromString is omitted, the default value is "%u@%h". log:remoteHost:Ident:authUser Specify contents of the client information part in common logfile format of HTTTP servers. The default value is AUTH="log:%h:%u:%U". %F -- E-mail address in From field %L -- local part of From: local@domain field %D -- domain part of From: local@domain field %U -- username part of Authorization: userame:password %P -- password part of Authorization: userame:password %Q -- `for FQDN' part of Forwarded: field Example: To record information about an original client in an internal delegated which is forwarded from a firewall delegated, generate From field at the firewall delegated and record it at the internal delegated. firewall% delegated AUTH="fromgen:%u@%h" ... internal% delegated AUTH="log:%D/%h:%L/%u:%U" ... 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 `anonftp' and `proxy'. DGPATH dir1:dir2:... (default: +:.:${HOME}/delegate) FCL filter-command FFROMCL filter-command FTOCL filter-command FSV filter-command FTOSV filter-command FFROMSV filter-command FMD filter-command FFROMMD filter-command Specify a filter command for data transmitted between the delegated and the client. Filters except for FCL,FSV and FMD get input from standard input and put output to standard output. Filter commands for FCL,FSV and FMD are given file descriptor 0 bound for the client, and file descriptor 1 bound for the delegated. You can apply filters conditionally using CMAP in the format like follows: CMAP=filter-command:filter-name:protoList:dstHostList:srcHostList For example, CMAP="sslway -co:FSV:telnet:hostA:*" means apply SSLway filter only when connecting to the Telnet server at hostA. RPORT {tcp,udp} RPORT {tcp,udp}:host This parameter should be used together with MASTER parameter. If specified, a connection (for response data transfer) from the MASTER delegate to this deleate is established separately from the connection (for request data transfer) from the delegated to its MASTER delegated. A specified type of response connection will be made from the MASTER towards the delegate at the specified host. ?RPASV ((Not yet available)) ... similar to RPORT, but the connection is established from the delegated to the MASTER delegated ... HTTPMAIL server:relay HTTPMAIL server:relay:mailsplit If specified, the delegated will access remote HTTP service via E-mail. The `server' is the E-mail address of HTTPMAIL server, and the `relay' is the E-mail address of HTTPMAIL client (may be delegated) which receives response from the server and relays it to the delegated. `mailsplit' indicate the desirable maximum size of each separated message of response message from the server. FILETYPE suffix:gopher-type:alt:icon:content-type Define file name to content-type mapping. gopher-type: 0 - text, 1 - directry, 4 - BinHex, 6 - uuencode, 9 - binary, g - gif, I - image, ... alt: alternative text which should be displayed for the icon image in text only displays icon: binary,binhex,compressed,directory,document,ftp,gzip, image,index,index2,movie,sound,tar,telnet,text,unknown,uu (see http://-.-/-/builtin/icons/ of HTTP/DeleGate) content-type: text/plain, image/gif, ... (see RFC1521) EXAMPLE: FILETYPE=".txt:0:TXT:text:text/plain" FILETYPE=".gif:g:GIF:image:image/gif" *CMAP result:mapname:protoList:dstHostList:srcHostList *NNTPCONF spec-list (default: upact:600/300/120) server:host [ :port ] [ /grouplist ] set NNTP server(s) for requests by URLs nntp://*/... or news:... pathhost:Server/PathHost -- define PathHost name of the Server-host. EXAMPLE: NNTPCONF="etlinn.etl.go.jp/etl.go.jp" upact:Invoke/Reload/Posted -- control updating of active list cache. Invoke and Reload specifies expire time of the cache in seconds. After an article is posted via the delegated, the cache will be updated whenever the client checked it (by LIST command), within the period specified by Posted. overview.fmt:{FieldList} (default: {Subject,From,Data,Message-ID,References,Bytes,Lines}) The format of the response message to XOVER command. xover:Number (default: xover:2000) Limit the maximum number of articles in "XOVER range" nice:Number (default: none) Set the nice value if defined. auth:{srcHostList} Force authentication (using AUTHINFO) at the beginning of the NNTP session if the client hosts is included in the srcHostList. This parameter should be set if the NNTP server does any authentication for any subset of users, and this delegated does caching for NNTP. nntpcc:number (default: 1) Specify "nntpcc:0" to disable "connection cache" for NNTP. *CRON cron-spec (default: none) Cause an action at a time specified in the cron-spec. Cron-spec is written in the following syntax which is compatible with that of "cron" server of Unix systmes. minute hour day month dayofweek action If the action is prefixed with '/' then it is an external action which will be executed by the system() 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 delegated -exit -- finish the delegated -expire N -- execute expiration for $CACHEDIR by "-atime +Nd" -system command -- execute `command' as a shell command # -fetch URL # -refresh URL /path/of/com args -- equiv. to "-system /path/of/com args" - args -- equiv. to "/path/of/delegated args" -Ffunc args -- equiv. to "/path/of/delegated -Ffunc args" EXAMPLE: CRON="0 0 * * * -restart" CRON="0 3 * * * -expire 3" (this is equivalent to followings) CRON="0 3 * * * -Fexpire /path/of/cache -rm -atime +3 -sum" CRON="0 3 * * * /path/of/delegated -Fexpire /path/of/cache -rm -atime +3 -sum" *INETD server-conf (default: none) Invoke a new DeleGate process with the specified configuration when a request is arrived at the specified port. The format of the specification is like that of inetd.conf(5) in Unix systems: [host:]port stream/dgram tcp/udp nowait/wait user exec-path arg-list A special exec-path "-" means to start child delegated with the given arg-list. The configuration of the parent delegated is inherited to child delegateds. For example, when a parent delegated is invoked like: delegated ADMIN=foo EXPIRE=1 INETD="conf1" INETD="conf2" these ADMIN and EXPIRE parameters are inherited to delegateds specified in "conf1" and "conf2". NOTE: "wait" state is not yet supported in the current version. 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 XCMD="/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) *ICP icpServers *ICP icpServers:icpOptions:proxyPort:icpPort *ICP icpServers:icpOptions:proxyPort:icpPort:dstProtos:dstHosts:srcHosts ICP client configuration which is referred when "icp" is included in the CONNECT sequence. icpServers is a comma separated list of icp servers where each server is represented in the following format: icpHost/icpType/proxyPort/icpPort icpHost The host name or IP address of the ICP server [localhost] icpType "s" -- the ICP server is a "sibling" [default] "p" -- the ICP server is a "parent" "l" -- the ICP server is a "listener" which never respond "n" -- the ICP server is a navigation proxy "o" -- require HIT_OBJ response "H" -- the object server is a HTTP proxy [default] "D" -- the object server is a MASTER DeleGate. "O" -- the object server is an origin server. #### "P" -- the object server is an proxy of origin protocol. proxyPort The port number of the corresponding object server [8080]. icpPort The port number of ICP protocol [3130]. icpOptions: timeout/N -- period to wait response as an ICP client [2.0](seconds) parent -- mark the default type of icpServers as "parent" listener -- mark the default type of icpServers as "listener" hitobj -- enable HIT_OBJ for all icpServers by default Origin -- object servers are origin server DeleGate -- object servers are DeleGate EXAMPLE: ICP=icphost (This is the simplest usage which is the abbreviation of ICP="icphost/sH/8080/3130:timeout/2.0:8080:3130:*:*:*" ) ICP="host0" ICP="host0//8080/3130" ICP="host0::8080:3130" ICP="host1:timeout/1.0:::http,ftp:!*.my.domain:*.my.domain" ICP="host1,host2/O/80/13130:timeout/2.0:8080:3130" *ICPCONF {para:N,hitage:N,hitobjage:N,hitobjsize:N,timeout:N} ## *ICPCONF icpOptions:dstProtos:dstHosts:srcHosts ICP configuration when the DeleGate server is running as an ICP server with SERVER="icp". 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) ## nofetch -- returns NOFETCH for MISS (off) debug:N -- the level of log for debug [0] *DNSCONF Specify the configuration of the DNS-DeleGate server with (SERVER=dns). para:N -- the number of paralles server process [2] domain:FQDN -- [domain of the host of DeleGate] origin:FQDH -- [host of the host of DeleGate] admin:Email -- the mail address of the administrator [ADMIN] serial:N -- serial number [%Y%m%d%h of configuration change] refresh:N -- refresh interval [3600] retry:N -- retry interval [600] expire:N -- expire period [3600*24] minttl:N -- minimum ttl [3600] EXAMPLE: SERVER=dns RESOLV=cache,file,nis DNSCONF=domain:my.domain VSAP vsap-host:port (default:none) Specify a VSAP server to be used for acception from clients or for connection to clients. VSAP is a remote socket mapping server which enables servers to accept a TCP connection via a remote host as well as to connect via a remote host. EXAMPLE: firewall% delegated -P8000 SERVER=vsap PORT=8080-8090 -- VSAP server internal% delegated -P8080@firewall:8000 ... -- accept via VSAP, internal server for external clients internal% delegated -P8080 CONNECT="{vsap/firewall:8000}" ... -- connect via VSAP, proxy server for internal clients internal% delegated -P8080 VSAP=firewall:8000 ... -- accpet and connect via VSAP server *HTTPCONF conf-script (default: welcome:welcome.html,welcome.cgi, index.html,index.cgi,-dir.html) welcome:listOfWelcomeFiles A list of index files or CGI scripts which should be used for URLs of directories ending with "/" like "/path/". This is a list of cancidate file names. The list may be ended with "-dir.html" which means a built-in index generator. If the list is empty, empty data is substituted for index data. search:pathOfSearchScript (default: none) The path of a CGI script to be applied for URLs with search part like "/path?search". This is a global specification applied for all URLs. Also you can specify a local search script for each MOUNT point like MOUNT="/path2/* /root/of/path2/* search:srcipt2". This local specification is prior to the global one. A special local specification "search:-" can be used just to ignore the global specification for the MOUNT point. EXAMPLE: HTTPCONF=search:/path/of/searchScript MOUNT="/* file:/path/of/data/*" MOONT="/bin/* cgi:/path/of/cgi-bin/* search:-" SMTPGATE config-dir (default: ${ETCDIR}/smtpgate) Specify the configuration directory for SMTP to {SMTP,NNTP,FTP} gatway. ProtoList [!]protocol,... A ProtoList is a list of protocol names separated with `,'. Reserved name `*' means all of protocols. If `!' or '-' is prefixed, the protocol is excluded from the protocol list. Special protocol names `tcprelay' and `udprelay' provide generic full duplex channel for application protocols on TCP and UDP protocols respectively. HostList [!]host,host/mask,... A HostList is a list of hostname and IP-address optionally followed by a mask value, or IP-address range specification. This list is used in matching to examine whether a certain host name or IP-address is included the list or not. You can prefix or postfix wild card character `*' to the hostname, like `*.ac.jp' or `*.etl.go.jp'. IP-address range can be specified like 192.168.[0-255], 192.168.1.[32-63]. These range can be written as 192.168.0.0/16 and 192.168.1.32/27. There are special host names which are substituted with real host names at runtime. "." -- the host where the delegated is running. "-" -- identical to "." if the host has unique IP address (network interface), but if it have multiple IP addresses, it will be the IP address from which the client connected to the delegated. ".o" -- identical to "." if the host has unique IP address, but if it have multiple network interface, outgoing network interface ".localnet" -- represents "localhost,./@,-/@,.o/@" "-C" -- the client host which may be useful to restrict access from a client only to the client (network). "?" -- matches any `unknown hosts' which name or address is not known by resolvers (listed in RESOLV). If a hostname (or a IP-address) is prefixed with "-" like "-hostname" ("-192.168.1.1"), then no name resolution (reverse resolution) will be tried for the hostname (IP-address). This will avoid wasting time in resolution trial for a never resolvable hostname (IP-address). Specifying a mask value, you can check only a part of address, typically network address. The mask value can be specified in one of four forms; hexa-decimal value, internet address in dot notation, `@', or one of `@A', `@B' and `@C'. `@' means the default network mask for the IP-address of the host to be masked. @A, @B, @C represent 255.0.0.0, 255.255.0.0 and 255.255.255.0 respectively. The `@X' notation can be followed by the number of bits for subnets; for example `@B4' means class B network divided into sixteen subnets. If `!' is prefixed to a host, it means that the host is excluded from the list. All of elements in the list are scanned from the first one to the last one. Thus once included (excluded) name may be excluded (included) in succeeding list. For HostList concerning source hosts, list of user names (UserList) can be prefixed to a host name like {user1,user2,...}@host. The negate symbol `!' have the same meaning with that in HostList. Note that !user@host is different from {!user}@host; the former excludes user@host, but the latter means {*,!user}@host thus includes *@host exept user@host. The special user name `?' matches with users whos names are not IDENTified with identd. You can inhibit access from unknown hosts or from unknown users with "RELIABLE={!?,!?@*}". SUBSTITUTION Options and values can be loaded from external `substitution resources'. An option like `+=file' is substitued by a list of options enumerated in the resource named `file', an option like `name=+=file' is substitued by a list of `name=value' where the `value' is enumerated in the `file'. Substitution can be done recursively. In this case, a relative resource name is searched in DGPATH. By default, DGPATH="+:.:${HOME}/delegate" where `+' stands for the place where the `caller' resource is. For example, if `+=file2' is referred from file `/usr/etc/file1', the `file2' will be searched first as `/usr/etc/file2'. A resource name can be specified in URL like `+={http://host/file}'. Substitution resources are the list of options (or values) where each line stands for an option (or a value). In each line, strings after sharp character(#) will be ignored as a comment. White space characters (SPACE, TAB, LF and CR) at the beggining 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. Substitution resources will be reloaded when the delegated received a SIGHUP signal. Another subustitution 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 rewriten 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 given an environment variable named CONFIGDATA of which value is a temporary file name containing the content of "http://server/configdata". URL REWRITING RULE The general rewriting rule for URLs of protocols to be gatewayed by HTTP proxy is as follows: ORIGINAL REDIRECTED URL --------------- ---------------------------------- P://OH:OP/F -> http://DH:DP/-_-P://OH:OP/F where DH and DP means the host and port of delegated respectively. The redirected URL is composed of three parts: proxy part: http://DH:DP/ delimiter: -_- original URL: P://OH:OP/F If P is HTTP, then it may be omitted. This rewiting rule could be applyed for proxies of other protocols, exept for Gopher. In Gopher proxy, rewriting should be as follows: ORIGINAL REDIRECTED URL --------------- ---------------------------------- gopher://H:P/GS -> gopher://DH:DP/G-_-gopher://H:P/GS where `G' and `S' means `gtype' and `selector' respectively. The rewriting rule of Directory Entity is compatible with that of URL: G User_Name Tab S Tab Host Tab Port -> G User_Name Tab -_-gopher://Host/Port/GS Tab DH Tab DP -- DELEGATE SWITCHING TABLE -- Delegated does not apply rewriting rule to already REDIRECTED request. Thus you can write delegate switch tables in HTML. Suppose that you have two firewall hosts connected to different networks each other: firewall1 -> NTT firewall2 -> NTT where the HTTP SPECIALIST delegated on 10080 and 20080 are, for example, connected to the Proxy_httpd on firewall1 and firewall2 respectively. -- MODIFIER -- Right after the -_- mark, optional `/Modifier/' form can be inserted as follows: http://delegate/-_-/Modifier/URL Modifier can be a list of multiple Modifiers sepalarted each other by by comma (,) character. cc -- Client's character code specified as ``cc.OutCode.InCode'' F -- is a list of flag characters compatible with (obsoleted) ``=flags='' extension. # # OBSOLETED BY MODIFIER # #-- ENCODING STATE IN URL -- # # Right after the -_- mark, optional `=flags=' form can be inserted as # follows. # # -_-=JN=gopher:H:P=G # # Flags in a request to the delegated will be copyed in the URL or DirEnt # in its response. Thus flags can be used to represent some `state' in # stateless protocols like HTTP and Gopher. Currently supported flag are: # # N use internet address number overriding DELEGATE specification # E force EUC output overriding CHARCODE variable # S force SJIS output overriding CHARCODE variable # J force JIS (ISO-2022-JP) output overriding CHARCODE variable # I force II output # c force CN (Chinese BIG5,GB,HZ) input to Japanese JIS conversion # C DISABLE cache # # These rewriting can be achieved by some script commands for user # when they invokes the real client. You will find `dmosaic' and # `go-far' script in the bin/ directory of DeleGate distribution file. -- DEFECT -- In this rewriting mechanism, Users of clients are forced to mind that they are using DeleGate. To open something directly by specifying its locater like a URL, they must know the special encoding format of URL to use DeleGate. When they save HTML text got via DeleGate, they should rewrite URLs included in it into original format. But for the clients with PROXY_HTTP facility, DeleGate becomes unvisible for users and these defects are cancelled. Those clients can use DeleGate for Proxy_httpd, or they can use DeleGate only for JIS code conversion. DeleGate-TUNNEL If -P option is not specified then the standard input/output is used as a fixed communication channel to a client. In this case the channel is called as a `DeleGate-TUNNEL' and a connection oriented DeleGate protocol is performed on the channel. A TUNNEL will be used when the delegated is invoked from inetd, when it is connected to a non-IP communication channel such as a serial line, or when you need to pass through a protocol-filtered router using permitted protocol. EXAMPLE -- HTTP/DeleGate -- A simple usage of the delgated just for HTTP clients is running it on your `firewall' host as Proxy-HTTP server like follows: firewall% delegated -P8080 SERVER=http://-/-/ RELIABLE=internal Then use it from your client on the `internal' host: internal% setenv http_proxy http://firewall:8080/ internal% setenv ftp_proxy http://firewall:8080/ internal% setenv gopher_proxy http://firewall:8080/ internal% setenv wais_proxy http://firewall:8080/ internal% mosaic http://info.cern.ch/ If a Proxy_httpd on a host `firewall' at the port 8080 is available, you can utilize it at `internal' host like follows: internal% delegated -P10080 PROXY=firewall:8080 \ SERVER=http://www.ntt.jp:80 Otherwise you must run GENERALIST DeleGate on the firewall, then run a SPECIALIST on `internal' host which use the GENERALIST on firewall: firewall% delegated -P19999 RELIABLE=internal internal% delegated -P10080 MASTER=firewall:19999 \ SERVER=http://www.ntt.jp:80 After you invoked delegated, try to use it as follows. If your WWW client supports Proxy: localhost% setenv http_proxy http://internal:10080/ localhost% mosaic localhost% mosaic http://info.cern.ch/ Otherwise: localhost% w3client http://internal:10080/ localhost% w3client http://internal:10080/-_-://info.cern.ch/ In the first example in each case, mosaic(w3client) will be connected to the default server specified at delegated's command line (in this case, www.ntt.jp). In the second example, the server specified in command line (info.cern.ch) will be connected. -- DeleGate as a HTTP origin server -- host# delegated -P80 SERVER=http REMITTABLE=file,cgi \ MOUNT="/* /path/of/root/*" A file with a name extensioned with ".cgi" is treated as a CGI script. Also you can use arbitraly name of CGI scripts under a specified directory like follows: MOUNT="/xxx/* cgi:/path/of/cgi-bin/*" -- DeleGate as a CGI program -- You can use DeleGate as a CGI program from a HTTP server. For example, specify in the ``httpd.conf'' file of your HTTP server(A) as follows. Exec /other/* /path/of/cgi-delegate Then write the content of the file /path/of/cgi-delegate as follows: #!/bin/sh delegated -Fcgi MOUNT="/-* =" \ MOUNT="/www2/* http://www-server2/*" \ MOUNT="/news/* nntp://nntp-server/*" This will add a pseudo sub tree ``/other/'' on server(A) including /other/www2/ which is a content of a HTTP server ``www-server2'', and /other/news/ which is a content of a NNTP server ``news-server''. -- Gopher/DeleGate -- firewall% delegated -P19999 RELIABLE=internal internal% delegated -P10070 MASTER=firewall:19999 CHARCODE=JIS\ SERVER=gopher://gopher.ncc.go.jp:70 localhost% gopher internal 10070 localhost% gopher -p -_-gopher://gopher.tc.umn.edu internal 10070 localhost% gopher -p -_-=E=gopher://gopher.tc.umn.edu internal 10070 The third example of client invocation includes `=E=' just after the `-_-' mark, which specifies code conversion to EUC should be done in the server regardless the CHARCODE value of the server. Note that a GENERALIST delegated can be shared among SPECIALIST delegateds for HTTP, Gopher and others. -- FTP/DeleGate -- You can pass through the firewall with your `normal' FTP client without SOCKSification. Run a delegated as a `FTP-Proxy' as follows: filewall% delegated -P8021 SERVER=ftp RELIABLE=internal Then you can connect to outside FTP servers via the FTP-Proxy. Move to the pseudo directory `//server' then you will be connected to the FTP server. internal% ftp ftp> open firewall 8021 220-- firewall PROXY-FTP server (DeleGate2.3.0) ready. 220-- @ @ 220-- ( - ) { DeleGate2.3.0 by ysato@etl.go.jp } 220- You can connect to a SERVER by `cd' command as: 220- ftp> cd //SERVER 220 Name (ysato:ysato): ftp 331 Guest login ok, enter your E-mail address as password. Password: ysato@etl.go.jp 230- Guest login ok, your E-mail address is 230- Now you can select a FTP SERVER by cd //SERVER 230 ftp> cd //host1.domain1/ 220 host1.domain2 FTP server ready. ftp> cd //host2.domain2/ 220 host2.domain2 FTP server ready. ftp> NOTE: The majoriy of ftp clients on UNIX can allow to specify port number of FTP at command line like follows: internal% ftp firewall 8021 - Cascaded FTP-Proxy - firewall# delegated -P21 SERVER=ftp PERMIT="ftp:*:internal" internal# delegated -P21 SERVER=ftp PROXY=firewall:21 Also Wu-ftpd can be specified as a PROXY. - FTP MOUNT - Filtering, Merging and Aliasing filewall# delegated -P21 SERVER=ftp://serv1/ \ MOUNT="/pub2/* ftp://serv2/pub/*" \ MOUNT="/pub3/* ftp://serv3/pub/*" This delegated mainly relays for serv1 but replaces its /pub2/* by that of serv2. - FTP to LPR (Line Printer Daemon Protocol) gateway MOUNT="/* lpr://printer0/qname0/*" MOUNT="/pr1/* lpr://printer1/qname1/*" MOUNT="/pr2/* lpr://printer2/qname2/*" -- DeleGate as a FTP origin server -- host# delegated -P21 SERVER=ftp MOUNT="/* /path/of/root/*" STOR (writing to the file) is disabled by default in this case. You must specify "rw" as a mount option to the MOUNT point which should be writable, like MOUNT="/xxx/* /yyy/* rw". -- Telnet/DeleGate -- firewall% delegated -P8023 SERVER=telnet RELIABLE=internal internal% telnet firewall 8023 -- @ @ PROXY-TELNET server on DeleGate2.3.0 by ysato@etl.go.jp -- ( - ) { Enter empty host name if you won't continue. } Host name: ysato SunOS UNIX (ysato) login: -- POP/DeleGate -- firewall# delegated -P110 SERVER=pop external% telnet firewall pop +OK Proxy-POP server (DeleGate2.4.4) at firewall starting. USER username@servername ... USER name `username%servername' is also available. - POP MOUNT ``user@server' is represented as ``//server/user'' internally and it can be controlled by MOUNT as follows: MOUNT="//* =" ... don't rewrite if a server is specified by the user MOUNT="* pop://defaulthost/*" ... specify default POP server MOUNT="user1 pop://host/*" ... let pophost be server of user1 MOUNT="//pop1/* pop://host1/*" ... hide hostname host1 - POP NNTP GATEWAY SERVER=pop MOUNT="* nntp://nntpserver/*" MOUNT="ns2-* nntp://nntpserver1/* apop=password" MOUNT="ns3-* nntp://nntpserver2/* pass=password" Clients are expected to send a newsgroup name as a user name. -- POP/HTTP gateway DeleGate -- firewall# delegated -P80 MOUNT="/mail/* pop://mailHost/*" This delegated provides mailboxes in POP server (at mailHost by default) to HTTP clients. Clietns 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 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. -- NNTP/DeleGate -- Filterling firewall# delegated -P119 SERVER=nntp://news-server/group. relays only newsgroups which have name pattern `group.*'. A list of groups can be specified for a news-server like `nntp://news-server/group1.,group2.,...' Merging firewall# delegated -P119 SERVER=nntp \ MOUNT="= nntp://server1/" \ MOUNT="= nntp://server2/" merges newsgroups on two NNTP servers. Aliasing MOUNT="= nntp://server1/group." mounts groups of group.* with it original names. MOUNT="alias-group. nntp://server1/group." mounts groups of group.* with aliased names `alias-group.*' POP to NNTP relay MOUNT="= pop://user:pass@host/" mounts a mail spool as if it is a newsgroup named `+pop.user.host.' -- NNTP/HTTP gateway DeleGate -- firewall# delegated -P80 MOUNT="/net/news/* nntp://nntp-server/*" -- DeleGate as a NNTP origin server -- % delegated -P119 SERVER=nntp://-.-/ Make a new newsgroup named ``NewsGroup'' -> Make an empty file ${ETCDIR}/news/groups/NewsGroup Relay an existing ``/MH/folder'' as a ``NewsGroup'' -> Make a file ${ETCDIR}/news/groups/NewsGroup with content like 0 0 0 0 /MH/folder (four zeros followd by a path name of MH-folder) -- SMTP/DeleGate -- Aliasing and Filtering firewall# delegated -P25 SERVER=smtp://mail-server/ \ MOUNT="foo@bar smtp://foo2@bar2" \ MOUNT="* smtp://-" (BUG: target should be mailto:user2@bar2 ...) -- HTTP via mail HTTPMAIL server Setup forwarding that forwards the mail to to "|delegated FUNC=hmserver". HTTPMAIL client Setup forwarding that forwards the mail to to "|delegated FUNC=hmrelay", and HostA% delegated -P8080 \ HTTPMAIL=hmserver@serverhost.domain:hmrelay@yourhost.domain HostA should be IP-reachable from the mail server of yourhost.domain. Typically HostA is the same host with yourhost.domain. For testing, you may use `hmserver@wall.etl.go.jp' as a server. -- LDAP/DeleGate -- firewall# delegated -P389 SERVER=ldap Specify this DeleGate server as your client's LDAP server and append "@host.of.ldap-server" after root directory name (i.e. name of baseObject for search). -- Whois/DeleGate -- firewall% delegated -P19999 RELIABLE=INTERNAL INTERNAL# delegated -P43 SERVER=whois MASTER=firewall:19999 internal% whois -h INTERNAL whois://whois.nic.ad.jp/help -- CU-SeeMe/DeleGate -- firewall% delegated -P7648 SERVER=cuseeme://Reflector/ RELIABLE=INTERNAL INTERNAL# delegated -P7648 SERVER=cuseeme://firewall/ internal% {use firewall or INTERNAL as a proxy-reflecter for Reflector} RESERVED-NAMES Special names `-'and `-.-', when it is used in the `host:port' part of URL, means the host and port of the delegate itself. And URL `http://-.-/-/' is reserved for a entry point of a control page of delegated. FILES /var/spool/delegate/etc -- persistent files mainly for configuration /var/spool/delegate/log -- log files which will grow up /var/spool/delegate/work -- for core dump /var/spool/delegate/cache -- for cached data /tmp/delegate -- volatile files which should be erased on shutdown $HOME/.rhosts.delegate -- hosts permitted to invoke delegated via rsh See the description of DGROOT parameter for more information. AUTHOR Yutaka Sato Electrotechnical Laboratory (AIST,MITI), Tsukuba, Ibaraki 305, JAPAN COMMENT: I have clients of ftp, telnet, and whois, which support DeleGate and directly communicates GENERALIST. But I think they are not so useful for you because you can use more neat proxy server for them, SOCKS. DISTRIBUTION The latest version of DeleGate is available at the following location. in a tar+gzip format file named ``delegate*.tar.gz''. Release 5.9 Last change: June 2, 1999