DeleGate is a multi-purpose proxy server for multiple application protocols running on multiple platforms. The aim of this document is to provide an introduction to how to use DeleGate by a collection of usage examples with a short tutorial for beginners. Details of configuration parameters should be referred to the Reference Manual. This document is written based on the specification of the latest version of DeleGate version 9.
| [Latest] [Home] [Manual] [Tutorial] [Download] [Install] [Copyright] |
|
% -- implies a command prompt for a non-privileged user
(subin)
delegated -- the name of an executable file of DeleGate (download) -Pport -- the port on which DeleGate accepts requests from clients (install) SERVER=proto -- the protocol in which DeleGate communicate with clients -v -- the option to run DeleGate in foreground putting the log to console ADMIN=you@your.domain -- the E-mail address of the administrator of the DeleGate +=filename -- loading command line arguments from a file |
The simplest command to run DeleGate as a HTTP proxy is as follows:
To test a command observing the progress, use "-v" option to make DeleGate run in foreground with logging on the console.
You will be asked the E-mail address of the administrator (it should be yourself) if your delegated is got as the binary distribution. It can be specified in the ADMIN argument.
A list of command line arguments can be loaded from a file with "+=filename" option. The file contains an argument per line.
| % delegated +=dg.conf | [the content of dg.conf] -P8080 SERVER=http -v ADMIN=you@your.domain |
When you use DeleGate on the privileged port (of number lower than 1024) on Unix, you need to run DeleGate with the privilege of the super-user.
But running DeleGate under the super-user's privilege is not recommended in the consideration of security. You should install subin to escape the problem.
DeleGate as an Application Level Proxy
% delegated -P8080 SERVER=http
% delegated -P80 SERVER=http://server/
% delegated -P8080 SERVER=http CACHE=do
% delegated -P8021 SERVER=ftp
% delegated -P8110 SERVER=pop
% delegated -P8143 SERVER=imap
% delegated -P389 SERVER=ldap
(*2) Proxies for application protocols except HTTP do not have an inherent sub-protocol to realize a proxy server which supports to connect to an arbitrary server specified by a client. Therefore to access arbitray server in FTP, POP and IMAP is realized by accepting user@host:port instread of username as a login name.
(*1) You need to use SERVER=https instead of SERVER=tcprelay to relay between HTTP and HTTPS. This is necessary to map URLs, transferred in HTTP messages, appropriately following to the mapping of protocol and host-name from "http://server/" to "https://dghost/". It is also necessary to enable caching of response messages.
(*2) You need to use SERVER=ftp instead of SERVER=tcprelay because the FTP protocol uses data-connections to be created dynamically of which usage is negotiated in the protocol, which needs to be interpreted by DeleGate of SERVER=ftp.
When using DeleGate as a proxy on a multi-homed host, with different network interface for an external (xx.xx.xx.xx) and an internal (ii.ii.ii.ii) network respectively, the simplest configuration to allow access only from the inside is specifying the interface of port to accept clients as this:
By default, DeleGate allows access from a client-host only if the host is on "local network". What the "local network" is is pre-defined as the special host-list named ".localnet". It can be redefined with a HOSTLIST parameter as this for example:
When it is difficult or insufficient to control access based on the IP address or host-name of clients, you can use password based authentications, or certificate based authentication when using SSL. For example, PAM based password authentication can be done as this:
To enable the certificate based authentication, specify "-Vrfy" option of the SSLway filter.
When using DeleGate as a "reverse proxy", it should be configured not to be utilized to access arbitrary ports and/or hosts not amied by the administrator. The REACHABLE parameter can be used combined with any application protocols to restrict reachable host (and port).
A HTTP proxy server is designed to allow very wide range of protocols over it. So it should be configured not to be utilized in the way which you don't aimed. Therefore, by default, DeleGate restricts the protocols to be carried over it when it acts as a HTTP proxy. It can be configured to allow only access strictly to HTTP and HTTPS servers on each statndard port as this:
See the reference manual for more details about access control.
When you created it from the source distribution, you will get an executable file named delegated (or delegated.exe on Windows) under the src/ directory. Or you can get it from binary distributions for several platforms (MacOSX, Linux, FreeBSD, Windows, Zaurus, and OS/2). Each executable file for each platform is named as macosx-dg, dg9_2_0.exe or so. You can rename it to any name like delegated or dg.exe.
On the first invocation of DeleGate, it creates directories to hold files for log, cache, administration data, and so on under a directory. The root directory of DeleGate is called DGROOT. DGROOT can be specified as a command line option as DGROOT=path. Otherwise it is selected automatically depending on the platform and user of DeleGate. See the start-up message from DeleGate to see which directory is selected as DGROOT.
To use SSL with DeleGate, using the latest version of shared libraries for SSL
might be desirable.
If the host's standard libraries is not installed, or not the latest,
install the library files under DGROOT/lib/.
The
binary distribution
of DeleGate contains the binary of shared libraries of OpenSSL
under directories named "sslway/".
See the note about TLS
for more details if necessary.
It is desirable to execute DeleGate in an isolated file space to be safer
from possible attacks. For example,
CHROOT="/" lets the
DGROOT as the root of file system on Unix.
You need to copy some library files and devices to the new root from
the original root. Files need to be copied and created depend on each
platform. An example for MacOSX and Linux is in
"subin/install.sh" in the source distribution.
The straight forward way to do so is running DeleGate with the privilege of the super-user (with OWNER=root). But running DeleGate under the super-user's privilege is not recommended in the consideration of security. You can escape the problem by installing files under DGROOT/subin/.
For example, the command subin/dgbind is invoked from DeleGate when a privileged port is required as -P80, or to bind the source port of a FTP data-connection. A file descriptor of an unbound socket is created by DeleGate and inherited to dgbind with the argument indicating the port number to be bound. On the invocation of dgbind, the effective user-ID of the process is set to the one of the super-user (root) so that it can execute the bind() system call for privileged ports.
Those executable files in subin is created automatically when you created DeleGate from the source distribution. They are available in the binary distribution for several platforms too.
To let the executable files in subin, dgbind for example, be executed with the privilege of the super-user, let the files be owned by root, and set the "set-user-ID-on-execution" bit and the "set-group-ID-on-execution" bit.
# chgrp group dgbind