#!/path/of/delegated +=
###
##---------------------------------------------------------------------
## A template of default configuration file for DeleGate version 9.X
## ver.0.4alpha, 2014-11-05, Yutaka Sato @ DeleGate.ORG
##---------------------------------------------------------------------
## - The latest version of this file is available at:
## http://www.delegate.org/delegate/dg9.conf.txt
##
## - This is an example of a configuration file of DeleGate.
## - The "configuration" of DeleGate is a set of parameters (or options)
## which can be given in command line options, in configuration files,
## in environment variables, and so on.
## - A "configuration file" of DeleGate is a plain text file including
## a list of configuration parameters one per line.
## - The "default" configuration file is the one named as "XXX.conf"
## that is loaded on invocation of an executable file of DeleGate
## named as "XXX".
## - You may give all of parameters in the default configuration file
## and invoke DeleGate without command line options.
## - But it is more likely that writing a common set of parameters in
## the default configuration file while giving other parameters in
## command line options those are specific to individual usage.
##
## - Category of parameters
## ==A ... access control
## ==C ... configuration file
## ==D ... deployment of directories
## ==L ... logging
## ==N ... networking
## ==P ... application server
## ==R ... resource restriction
## ==S ... daemon and service
## - Multiplicity of parameters
## [0-1] ... at most one is given
## [0-n] ... can be given multiply
#
##==C [0-n] ---- shortcut example --------------- MINIMUM CONFIGURATION
#@ typical and minimum configuraiton for a HTTP proxy, plus alpha
##---------------------------------------------------------------------
## - The following is a typical set of configuraiton parameters for
## DeleGate as a HTTP proxy.
#
#ADMIN=foo@bar.baz # mail-address of the administrator of this DeleGate
#SERVER=http # the protocol DeleGate speaks with its clients
#-P8080 # the entrance port on which DeleGate waits clients
##
## - a little more parameters that are generally used.
#
#-vs # suppress logging of the behavior of DeleGate
#SOCKS=192.168.1.1:1080 # forwarding any protocol to a SOCKS server, or
#PROXY=192.168.1.1:8080 # forwarding HTTP to an upstream HTTP proxy
##
## - a little more, a little tricky usage.
#
#SSTUNNEL=192.168.1.1:8080 # forwarding any protocol to HTTP SSL-tunnel
#SERVER=tcprelay://odst.- # transparent TCPrelay maybe forwarded to SOCKS
#
##==C [0-1] ---- delegated.conf ------------ DEFAULT CONFIGURATION FILE
#@ ${EXECDIR}/${EXECNAME}.conf[.txt] ... the default configuration file
##---------------------------------------------------------------------
## - To be detected as the "default configuration file" by DeleGate,
## this file must be located at and named as:
## /path/of/delegated.conf[.txt]
## where the path of the executable file of DeleGate is:
## /path/of/delegated[.exe]
## - More generally, it must be EXECDIR/EXECNAME.conf[.txt] where
## EXECDIR is the directory under which the executable file of
## DeleGate is, and EXECNAME[.exe] is the name of the executable file.
## - On Unix, an EXECNAME file can be a symbolic link to the executable
## file so that each symbolic name can have each configuration file.
## - In v9.9.13 or later, also EXECDIR/../etc/EXECNAME.conf[.txt] is a
## candidate of a default configuration file.
#
##==L [0-1] ---- -vQ --------------- TRACING CONFIGURATION FILE LOADING
#@ -vQ ... quietly loading the default configuration file
#@ -vq ... quietly loading all configuration files (loaded by +=URL)
##---------------------------------------------------------------------
## - Uncomment the following line to suppress the message shown on the
## invocation of DeleGate as "#### loading default conf: ..."
#
#-vQ
#
##==D [0-1] ---- DGROOT ----------------------- DELEGATE ROOT DIRECTORY
#@ DGROOT=dirPath ... the root directory of DeleGate
##---------------------------------------------------------------------
## - The root directory of DeleGate under which all of directories of
## DeleGate are located by default.
## - DeleGate may load multiple configuration file but only the
## "default configuration file" can set the DGROOT value.
## - It can be specified as an absolute path like bellow:
#DGROOT='/home/${HOME}/delegate' # the default on Unix
#DGROOT='C:/Program Files/DeleGate' # the default on Windows
## - Or it can be specified as a relative path that is relative to the
## executable file of DeleGate using the string '${EXECDIR}'.
## - '${EXECDIR}' is substituted by the path of directory under which
## the executable file of DeleGate is located.
## - For example, if the path of executable is
## ".../DGroot/etc/delegated.exe" then the ${EXECDIR} points
## ".../DGroot/etc", thus "${EXECDIR}/.." points ".../DGroot".
#
DGROOT='${EXECDIR}/..'
#
##==C [0-1] ---- common.conf ---------------- COMMON CONFIGURATION FILE
#@ ${DGROOT}/common.conf ... the common configuration file
##---------------------------------------------------------------------
## - "common" configuration file is commonly used among DeleGates that
## uses the same DGROOT.
## - It is loaded unconditionally if exists.
#
##==C [0-n] ---- +=URL ---------- LOADING CONFIGURATION FILE EXPLICITLY
#@ +=URL ... loading configuration file from the specified URL
##---------------------------------------------------------------------
## - If the URL is a relative path, it is relative from the
## configuration file that loades it.
## - Configuration file can be loaded recursively.
#
#+=http://server/path/dgconf.txt
#+=/path/of/dgconf.txt
#+=dgconf.txt
#
##==D [0-1] ---- LDPATH ------------------------------- DYNAMIC LIBRARY
#@ LDPATH=listOfDirectory ... search path for dynamic libraries
#@ DYLIB=listOfNamePattern ... name pattern of dynamic libraries
##---------------------------------------------------------------------
#LDPATH='${ETCDIR};${LIBDIR};${HOME}/lib;/usr/lib;/lib'
#DYLIB='lib*.so.0.9.8,lib*.so.1,lib*.so' # Unix
#DYLIB='lib*.0.9.8.dylib,lib*.dylib' # MacOSX
#DYLIB='cyg*-0.9.8.dll,cyg*-1.0.0.dll' # Cygwin
#DYLIB='*.dll' # Windows
#
##==L [0-1] ---- ADMIN ---------------------------------- ADMINISTRATOR
#@ ADMIN=mailAddress ... mail address of the administrator
##---------------------------------------------------------------------
## - The address is used to notify fatal "incident" to administrator
## from DeleGate via mail.
## - "Incident" includes a detection of an attack from intruder that
## caused fatal error like segment violation in DeleGate.
## - It is also used to show the contact address of the administrator
## of this DeleGate to clients on usual error like broken links.
## - Thus, it is recommended to be not a personal address but an
## address of a role name like "delegate-admin@bar.baz".
#
#ADMIN=foo@bar.baz
#
##==N [0-1] ---- RESOLV -------------------------- HOST NAME RESOLUTION
#@ RESOLV=orderOfResolver ... order of trial of resolution methods:server
#@ RES_AF={46,64,4,6} ... order of IPv4 and IPv6
##---------------------------------------------------------------------
## - Controls the behavior of host-name resolver of DeleGate.
## + orderOfResolver is a list of followings:
## - cache: cache file for "file", "dns" and "sys" bellow.
## - file[:pathOfHosts] ... file in the format of /etc/hosts
## If the path is a relative one, it is searched under DGROOT/etc.
## - dns[:DNSserver] ... DNS server.
## - sys ... the resolver of the host system.
#
#RESOLV=cache,file,dns,sys # typical configuration
#RESOLV=cache,file:hosts,dns:192.168.1.1,sys
#
##==N [0-n] ---- HOSTS --------------------------- HOST NAME DEFINITION
#@ HOSTS="nameList/addressList" ... defining a pair of hotname/address
##---------------------------------------------------------------------
## - HOSTS pre-defines an entry in the on-memory cache of the resolver
## of DeleGate, suppressing resolution by resolvers listed in RESOLV.
## - It can be used to define hosts that are unresolvable by resolvers
## listed in RESOLV.
#
#HOSTS="localhost/127.0.0.1"
#HOSTS="{host1,host2}/1.2.3.4"
#HOSTS="host3/{1.1.1.1,1.1.1.2}"
#
##==N [0-n] ---- HOSTLIST ------------------------ HOST LIST DEFINITION
#@ HOSTLIST="name:listOfHosts" ... definition of named list of hosts
##---------------------------------------------------------------------
## - HOSTLIST defines a named list of hosts to be referred like a host
## name in other named or unnamed host lists.
## - A host list is used for matchhing of access control list (ex.
## REACHABLE), routing destination (ex. FORWARD), MOUNT, and so on.
## - A member of the list is one of host-name, domain-name with a wild
## card, IP-address, masked IP-address or range of IP-addresses.
## - "*" matches any hosts
## - Wild card in domain name matching is like *.subdoamin.domain
## - The matching can be negation by "!" prefix to a host
## - A masked IP address is n.n.n.n/m.m.m.m, n.n.n.n/m, or host-name/m
## - A range of IP addresses is as n.n.n.[n-m]
#
#HOSTLIST="reachable:host1,host2,*.dom1,!*.dom2.dom1,!10.0.0.0/8"
#HOSTLIST="unreachable:!reachable"
#
##==R [0-n] ---- MAXIMA ----------------------- RESOURCE USAGE LIMITTER
#@ MAXIMA=what:maxValue ... limitter of resource usage
##---------------------------------------------------------------------
## - The number of processes of DeleGate increases/decreases dynamically
## based on the current load onto DeleGate.
## - A "resident" process is the one that stays for a while after it
## finished a processing of a request/session, waiting a next
## connection from clients to process.
#
#MAXIMA=delegated:64 # max. parallel DeleGate processes
#MAXIMA=standby:32 # max. parallel resident DeleGate processes
#MAXIMA=conpch:16 # max. parallel connection from a client host
#MAXIMA=listen:16 # size of the backlog of the entrance socket
#
##==R [0-n] ---- TIMEOUT -------------------------------------- TIMEOUT
#@ TIMEOUT=what:timeOut ... timeout idle connection, process, response
##---------------------------------------------------------------------
##
#
#TIMEOUT=io:60 # breaking idle connection to terminate the session
#TIMEOUT=standby:30 # exit of resident DeleGate on no client connection
#TIMEOUT=dns:10 # giving up DNS response of too long latency
#TIMEOUT=http-cka:30 # breaking idle HTTP connection in keep-alive
#
##==D [0-1] ---- LOGDIR ------------------- LOGGING DIRECTORY AND FILES
#@ LOGDIR=logDirectory ... directory under which logfiles are located
##---------------------------------------------------------------------
#
#LOGDIR=${DGROOT}/log # the default
#LOGDIR=/var/spool/delegate/log
##
## - Logfiles can be split day by day using "[date+format]" specifier
## where "format" is the one like in strftime() function.
## - For example, "%y", "%m", "%d" and "%H" mean two digits
## representation of year, month, day and hour respectively.
## - The following is the recommended one that will be the default in
## future version of DeleGate. With this parameter, the log-file of
## HTTP in 31 October 2014 is "DGROOT/log/y14/m10/31/80.http".
## - On Unix, a hard link for a split log-file created with a name
## without the "[date+format]" part, that is "DGROOT/log/80.http" in
## the example bellow.
#
#LOGDIR='log[date+/y%y/m%m/%d]' # split log-directory day by day
#PROTOLOG='${LOGDIR}/${PORT}.${PROTO}' # the default log-file path
#
##==S [0-n] ---- SERVCONF --------------- RESTARTING SERVICE ON WINDOWS
#@ SERVCONF=[yesall|auto|demand] ... starting service without interaction
##---------------------------------------------------------------------
## - DeleGate on Windows become a service of name with the port number
## as "DeleGate-P8080".
## - It starts with interaction with the user on the console as follows:
## 1) stop the current service if running ... asking [y]/n
## 2) delete the current service if exists
## 3) create a new service ... asking [y]/n
## 4) set automatic start of the service ... asking [y]/n
## 5) start the new service
## - SERVCONF=yesall ... sets "y" for all interaction 1),3),4)
## - SERVCONF=auto ... sets "y" for 4)
## - SERVCONF=demand ... sets "n" for 4)
## - "yesall" behaves like "-r" option for Unix daemon.
#
#SERVCONF=yesall # restart without interaction
#SERVCONF=auto
#SERVCONF=demand
#
##==S [0-1] ---- -r --------------------------------- RESTARTING DAEMON
## -r ... restart after terminating current daemon process
##---------------------------------------------------------------------
## - The process-id of current daemon is recorded in
## '${DGROOT}/act/pid/${PORT}' where '${PORT}' is the "primary" port
## of the daemon.
## - The "primary" port is the one of entrance ports given firstly in
## "-P" or "-Q" option.
## - With "-r" option, DeleGate kills currently running DeleGate daemon
## process by SIGTERM, and wait until the process releases the
## entrance port.
## - This option is applicable to a daemon on Unix, or a daemon running
## in foreground on Windows.
## - "-r" behaves like SERVCONF=yesall for Windows service.
#
#-r
#
##==S [0-n] ---- -f ----------------------------- RUNNING IN FOREGROUND
#@ -f[v] and -v[v] ... running in foreground
##---------------------------------------------------------------------
## - running DeleGate in foreground mainly for testing and debugging.
## - In this mode, DeleGate is kept connected to the console (tty) from
## which it is invoked so that it can put log messages to the console
## and can be terminated with Control-C.
## - Also DeleGate stays on the working directory of the parent process
## (shell command usually) by which it is invoked so that
## configuration files and core files are get from or put to the
## working directory.
#
#-f # Running in foreground
#-fv # like -f, putting log both to console and log-file (LOGFILE)
#-v # Running in foreground, putting log to console
#-vv # like -v, with detailed log
#
##==L [0-1] ---- -v ------------------------------------- LOGGING LEVEL
#@ -v[stud] ... log detailness level
##---------------------------------------------------------------------
## - -v[stud] specifies detailness of information in "LOGFILE".
## - -vS specifies not creating "PROTOLOG".
#
#-vd # detailed
#-vs # silent, don't create LOGFILE.
#-vt # terse
#-vu # usual
#-vS # suppress "PROTOLOG" for HTTP (as 80.http) and FTP (ex. 21.ftp)
#
##==A [0-n] ---- RELIABLE ---------------------------- RESTRICT CLIENTS
#@ RELIABLE=hostList ... list of client hosts to be accepted
##---------------------------------------------------------------------
## - A comma separated list of client hosts to be accepted by DeleGate.
## - It is a unnamed hostList of which syntax follows the one of value
## part of HOSTLIST parameter.
#
#RELIABLE="localhost,10.10.0.0/16,!10.1.2.[5-7],*.delegate.org"
#RELIABLE="+,192.168.1.1/24"
#RELIABLE="*" # running as a server open to public
#
##==A [0-1] ---- REACHABLE --------------------------- RESTRICT SERVERS
#@ REACHABLE=hostList ... server hosts to be reachable
##---------------------------------------------------------------------
## - A comma separated list of server hosts to which connections from
## the DeleGate are allowed.
## - It is a unnamed hostList of which syntax follows the one of value
## part of HOSTLIST parameter.
#
#REACHABLE="*"
#REACHABLE="*,!10.0.0.0/8"
#
##==A [0-n] ---- PERMIT ----------------- RESTRICT CLIENTS WITH SERVERS
#@ PERMIT="protoList:servList:clntList" ... permit by combination
#@ REJECT="protoList:servList:clntList" ... reject by combination
##---------------------------------------------------------------------
#
#PERMIT="+:.reachable:.reliable" ... default
#PERMIT="*:*:*" ... fully open
#
##==A [0-n] ---- AUTHORIZER ---------- AUTHENTICATION AND AUTHORIZATION
#@ AUTHORIZER=listOfAuthMethod ... auth. method of users
#@ MYAUTH=user:pass ... auth. info to be sent to server (by proxy)
##---------------------------------------------------------------------
##
#AUTHORIZER=-list{user:pass},-pam
#AUTHORIZER=-dgauth{user:pass} ... digest authentication (HTTP only)
#
##==N [0-n] ---- FORWARD ----------------------------------- FORWARDING
#@ FORWARD=gwproto://[gwuser:gwpass@]gwhost:gwport[-_-protoL:servL:clntL]
#@ SOCKS=host[:port] ... upstream SOCKS server
#@ PROXY=host[:port] ... upstream proxy in protocol proto of SERVER=proto
#@ SSLTUNNEL=host:port ... upstream HTTP proxy as a SSL-tunnel
##---------------------------------------------------------------------
## - Forwarding to upstream proxy server.
## - Upstream proxy is one of SOCKS, application proxy (HTTP or FTP),
## or SSL-tunnel(HTTP proxy).
## - FORWARD is a generic parameter for forwarding. It defines an
## upstream proxy by its protocol (socks, http, ssltunnel, etc.), its
## host and port, and user name and password if necessary.
## - Multiple FORWARD can be specified and one of them are selected
## based on destination protocol, server, and source client.
## - Examples:
#FORWARD=socks://192.168.1.1:1080
#FORWARD=http://192.168.1.1:8080 # applicable when client's speaks HTTP
#FORWARD=ssltunnel://192.168.1.1:8080
## - Examples: The above can be abbreviated as the bellow.
#SOCKS=192.168.1.1:1080
#PROXY=192.168.1.1:8080
#SSLTUNNEL=192.168.1.1:8080
#
##==N [0-n] ---- -P --------------------------------- LISTENING CLIENTS
#@ -Pnnnn ... entrance ports for clients
#@ -Qnnnn ... an entrance port for clients
##---------------------------------------------------------------------
## - The entrance port(s) on which DeleGate listens and accepts
## connections from clients.
#
#-Q8080
#-Qlocalhost:8080
#-Q192.168.1.1:8080
#-Q8080/http
#-Q1080/socks
#
##==P [0-n] ---- SERVER ----------------- PROTOCOL OF CLIENT AND SERVER
#@ SERVER=protocol[://server[:port]] ... protocol with clients
##---------------------------------------------------------------------
## - The protocol in which DeleGate communicates with clients.
## - If a server is specified, DeleGate forwards its request to the
## server in the protocol with clients.
#
#SERVER=ftp
#SERVER=http
#SERVER=smtp
#SERVER=socks
#SERVER=http://host.domain
#SERVER=tcprelay://host.domain:22
#SERVER=udprelay://host.domain:53
#SERVER=tcprelay://odst.- # transparent proxy
#
##==P [0-n] ---- MOUNT -------------------- MAPPING VIRTUAL TO PHYSICAL
#@ MOUNT="vURL rURL mountOptions" ... serving as a server and a proxy
##---------------------------------------------------------------------
## - This is the central parameter to configure DeleGate as an
## application level origin/proxy server.
## - It maps a logical resource name in a request message from a client
## (like URL) to (more) physical one to access to a server.
## - Also it maps a physical name in a response message from a server
## to a logical name for a client.
## - It is applicable to HTTP, FTP, NNTP, SMTP and POP.
#
#MOUNT="/* file:data/www/*" # an HTTP origin server
#MOUNT="/abc/* http://def/ghi/* moved" # redirection
#MOUNT="/* http://server/* nvhost=xyz" # virtual hosting
#MOUNT="/xyz/* http://server/* # reverse proxy
#MOUNT="/xyz/* ftp://server/* # protocol translation
#MOUNT="/xyz/* sftp://server/* # protocol translation
#MOUNT="//xyz/* smtp://server/* # SMTP routing
#MOUNT="/-/ = AUTHORIZER=-list{adm:xyz} # access control
#MOUNT="/-/builtin/* data:builtin/* # customizing builtin data
#
##==N [0-n] ---- STLS ------------------------------------ SSL WRAPPING
#@ STLS={fsv,fcl}* ... inserting SSL filter
#@ CERTDIR=dirPath ... location of certificates
#@ TLSCONF=options ... configuration and debugging of SSL behavior
##---------------------------------------------------------------------
## - do TLS unconditionally, or on-demand by STARTTLS (or STLS)
## negotiation with client and server.
#
#STLS=fcl # wrapping communication with client by SSL
#STLS=-fcl # like fcl, but if explicit STARTTLS negotiation is done
#STLS=fsv # wrapping communication with server by SSL
#STLS=-fsv # like fsv, but if explicit STARTTLS negotiation is done
#
##==C [0-1] ---- END ------------------------ ENDING CONFIGURATION FILE
#@ END ... ending of a configuration file
##---------------------------------------------------------------------
END
Lines in a configuration file after "END" is ignored.
##--------------------------------------------------------------- ANNEX
#
##==C [0-1] ---- DGOPTS ------------ OPTIONS IN AN ENVIRONMENT VARIABLE
#@ DGOPTS="-opt1;-opt2;..." ... defining options in a parameter
##---------------------------------------------------------------------
## - This parameter is for giving options starting with "-" in a
## environment variable.
#DGOPTS="-Q8080;-r;-vd"
#
##==C [0-1] ---- -eNAME=VALUE ----------- DEFINING ENVIRONMENT VARIABLE
#@ -eNAME=VALUE ... setting environment variable
##---------------------------------------------------------------------
## - Defines an environment variable of name NAME with value VALUE to
## be used in DeleGate or its libraries.
#
#-eTZ=JST
#-ePATH=/usr/bin:/bin
##==C [0-1] ---- scripts ------------ CONFIGURATION BY SCRIPT LANGUAGES
To configure DeleGate reflecting the system environment or so, it
should be invoked by a script language, like /bin/sh for example.
It is recommended to define dynamic configuration in a script language,
static one in a configuration file, then load it by +=URL notation in
the script.
[console]
$ export LD_DEBUG=symbols
$ sh httpd.sh -fv
[httpd.sh]
#/bin/sh
. dgcommon.sh # include a shell script
DgExe=/path/of/delegated # path name of DeleGate executable
$DgExe -P80 +=dghttpd.conf $* # invoke a DeleGate
[dgcommon.sh]
#!/bin/sh
export MALLOC_CHECK_=2
if [ "$OS" = "Windows_NT" ]; then
export DGROOT=C:/DeleGate
else
export DGROOT=$HOME/delegate # this is the default on Unix
fi
[dghttpd.conf]
+=dgcommon.conf # load a configuration file
SERVER=http # speak HTTP with the client
HTTPCONF="max-ckapch:8" # limit the parallel connections to 8
HTTPCONF="methods:GET,POST" # allow only GET and PUT method
MOUNT="/* file:data/www/*" # map /* to DGROOT/data/www/*
RELAY=no # don't relay as a proxy server
[dgcommon.conf]
ADMIN=foo@bar.baz
RESOLV=cache,sys
##==C [0-1] ---- NAME="VALUE" ------------------------------- QUATATION
## - Quations for a parameter value is not necessary in a configuration
## file (except the MOUNT parameter).
## - But it is recommended to do so to be compatible with the
## notation in script languages so that it can be moved between script
## file and configuration file without modification.
#==C [0-1] ---- #!magic ---- CONFIGURATION FILE AS AN EXECUTABLE SCRIPT
On Unix or Cygwin, a configuration file can be used as an executable
script. To do so, the configuration file is needed to be with
executable flag set, and the file starts with a line as this:
#!/path/of/delegated +=
#######################################################################