DeleGate Usage Examples

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]

Index

1. A Short Tutorial
2. DeleGate as an Application Level Proxy
3. DeleGate as a Circuit Level Proxy (SOCKS, TCP, UDP)
4. DeleGate as a Gateway Between TLS/non-TLS clients/servers
5. DeleGate as a Gateway Between IPv6 and IPv4
6. DeleGate as an Application Level Router
7. DeleGate as an Application Level VPN Router
8. DeleGate as an Origin Server (HTTP, FTP, DNS, NNTP)
9. DeleGate as an Server-Integration Gateway
10. DeleGate as a Protocol Translation Gateway
11. DeleGate as a Caching Proxy
12. DeleGate as a Filtering Proxy
13. DeleGate as an Authenication Proxy
14. Access Control
15. Installation
16. Privileged operations without being super-user

The simplest command to run DeleGate as a HTTP proxy is as follows:

% delegated -P8080 SERVER=http

To test a command observing the progress, use "-v" option to make DeleGate run in foreground with logging on the console.

% delegated -P8080 SERVER=http -v

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.

% delegated -P8080 SERVER=http -v ADMIN=you@your.domain

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.

% sudo delegated -P80 SERVER=http ...

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

• how to use DeleGate as a HTTP proxy (possibly as a "transparent proxy") (*1)
  
  % delegated -P8080 SERVER=http
  
  
• how to use DeleGate as a HTTP gateway (or "reverse proxy")
  
  % delegated -P80 SERVER=http://server/
  
  
• how to use DeleGate as a HTTP caching proxy
  
  % delegated -P8080 SERVER=http CACHE=do
  
  
• how to use DeleGate as a FTP proxy (for FTP client) (*2)
  
  % delegated -P8021 SERVER=ftp
  
  
• how to use DeleGate as a POP3 proxy
  
  % delegated -P8110 SERVER=pop
  
  
• how to use DeleGate as a IMAP proxy
  
  % delegated -P8143 SERVER=imap
  
  
• how to use DeleGate as a LDAP proxy
  
  % delegated -P389 SERVER=ldap
  
  
• how to use DeleGate as a Telnet proxy
  
  % delegated -P8023 SERVER=telnet
  
  
• how to use DeleGate as a SMTP server
  
  % delegated -P25 SERVER=smtp
  
  
• how to use DeleGate as a DNS (proxy) server
  
  % delegated -P53 SERVER=dns
  
  

  ---

  (*1) So called "transparent proxy" can be realized by two phases; (a) detecting and forwarding a TCP/IP packet in HTTP protocol to a HTTP proxy server and (b) a HTTP proxy server which forwards a message to the server indicated by the "Host:" field in its. DeleGate as a HTTP proxy allows (b) by default for the client hosts in its local-network. This behavior can be controlled by RELAY=vhost parameter.

  (*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.

  ---

• how to use DeleGate as a SOCKS proxy
  
  % delegated -P1080 SERVER=socks
  
  
• how to use DeleGate to relay UDP packets
  
  % delegated -Pport SERVER=udprelay://svhost:svport
  
  
• how to use DeleGate to relay UDP packets via a SOCKS proxy
  
  % delegated -Pport SERVER=udprelay://svhost:svport SOCKS=socksHost:socksPort
  
  
• how to use DeleGate to relay TCP connections
  
  % delegated -Pport SERVER=tcprelay://svhost:svport
  
  
• how to use DeleGate as a tunnel for TCP connections via a SOCKS proxy
  
  % delegated -Pport SERVER=tcprelay://svhost:svport SOCKS=socksHost:socksPort
  
  
• how to use DeleGate as a tunnel for TCP connections via a HTTP proxy (SSL-tunnel)
  
  % delegated -Pport SERVER=tcprelay://svhost:svport SSLTUNNEL=proxyHost:proxyPort
  
  

• how to use DeleGate as a SSL or TLS wrapper for an arbitrary protocol on TCP
  
  % delegated -Pport SERVER=tcprelay://svhost:svport STLS=fcl
  
  
• how to use DeleGate as a gateway for HTTPS clients to a HTTP server (*1)
  
  % delegated -P443 SERVER=https MOUNT="/* http://server/*" STLS=fcl
  
  
• how to use DeleGate as a gateway for HTTP clients to a HTTPS server
  
  % delegated -P80 SERVER=http MOUNT="/* https://server/*" STLS=fsv:https
  
  
• how to use DeleGate as a POP over HTTPS gateway
  
  % delegated -P443 SERVER=https MOUNT="/mail/* pop://server/*" STLS=fcl
  
  
• how to use DeleGate as a gateway for FTP clients to a FTPS server (*2)
  
  % delegated -P21 SERVER=ftp MOUNT="/* ftps://server/*" STLS=fsv
  
  
• how to use DeleGate as a gateway for FTPS clients to a FTP server
  
  % delegated -P990 SERVER=ftps MOUNT="/* ftp://server/*" STLS=fsv
  
  

  ---

  (*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.

  ---

• how to use DeleGate as a SOCKS proxy from IPv4 clients to IPv6 servers
  
  % delegated -P1080 SERVER=socks
  
  
• how to use DeleGate as a HTTP proxy from IPv4 clients to IPv6 servers
  
  % delegated -P8080 SERVER=http
  
  
• how to use DeleGate to accept connections on IPv6 port
  
  % delegated -P__:80 SERVER=http
  
  
• how to use DeleGate as a gateway from IPv6 clients to a IPv4 server
  
  % delegated -P__:80 SERVER=http://192.168.1.1/
  
  
• how to use DeleGate as a gateway from IPv4 clients to a IPv6 server
  
  % delegated -P192.168.1.1:80 SERVER=http://fe80__12_34%en0/
  
  

• how to use DeleGate as a proxy to switch upstream proxy by destination site
  
  % delegated -P8080 SERVER=http PROXY="proxy:8080:*.dom1,*.dom2"
  
  
• how to use DeleGate as a proxy to switch upstream proxy based on URL path
  
  % delegated -P8080 SERVER=http MOUNT="http://host/path1/* = PROXY=proxy:8080"
  
  
• how to use DeleGate as a proxy to switch upstream proxies based on protocol
  
  % delegated -P8080 SERVER=http PROXY="proxy:8080" SOCKS="socks:1080" CONNECT="proxy:http,socks:ftp,direct"
  
  
• how to use DeleGate as a proxy to switch upstream proxies by destination
  
  % delegated -P8080 SERVER=http PROXY="proxy:8080" SOCKS="socks:1080" CONNECT="proxy:*:*.dom1,socks:*:*.dom2,direct"
  
  
• how to use DeleGate as a proxy to switch upstream DNS server based on query
  
  % delegated -P53 SERVER=dns RESOLV="dns:192.168.1.123:*.localdomain,dns:192.168.1.1"
  
  

• how to chain DeleGate to relay SOCKS over SSL
  hostA% delegated -P1080 STLS=fsv SERVER=socks SOCKS=hostB:2080
  hostB% delegated -P2080 STLS=fcl SERVER=socks
  
  
• how to chain DeleGate to relay SOCKS over SSL (two hops)
  hostA% delegated -P1080 SERVER=socks SOCKS=hostB:2080 STLS=fsv
  hostB% delegated -P2080 SERVER=socks SOCKS=hostC:2080 STLS=fcl,fsv
  hostC% delegated -P2080 SERVER=socks STLS=fcl

• how to use DeleGate as a HTTP gateway (or "reverse proxy")(*1)
  
  % delegated -P80 SERVER=http MOUNT="/p1/* http://sv1/*" MOUNT="/p2/* http://sv2/*"
  
  
• how to use DeleGate as a HTTP virtual hosting server (*1)
  
  % delegated -P80 SERVER=http MOUNT="/* http://sv1/* vhost=-www1" MOUNT="/* http://sv2/* vhost=-www2"
  
  
• how to use DeleGate as a FTP gateway (for FTP client)
  
  % delegated -P21 SERVER=ftp MOUNT="/sv1/* ftp://sv1/*" MOUNT="/sv2/* ftp://sv2/*"
  
  
• how to use DeleGate as a NNTP proxy to merge multiple servers
  
  % delegated -P119 SERVER=nntp MOUNT="* nntp://sv1/*" MOUNT="* nntp://sv2/*"
  
  

  ---

  (*1) The features of DeleGate for "reverse proxy", "virtual hosting" and "transparent proxy" are totally revised in DeleGate/9.8.2 as described in http://www.delegate.org/delegate/nvproxy/

  ---

  
  

• how to use DeleGate as a gateway for HTTP clients to other protocols
  
  % delegated -P80 SERVER=http MOUNT="/file/* ftp://ftpsv/*" MOUNT="/mail/* pop://popsv/*"
  
  
• how to use DeleGate as a gateway for FTP client to sftp/SSH server
  
  % delegated -P21 SERVER=ftp MOUNT="/* sftp://server/*"
  
  
• how to use DeleGate as a gateway for FTP or FTPS client to sftp/SSH server
  
  % delegated -P21 SERVER=ftp MOUNT="/* sftp://server/*" STLS=-fcl
  
  
• how to use DeleGate as a gateway for DNS client to NIS server
  
  % delegated -P53 SERVER=dns RESOLV=nis
  
  
• how to use DeleGate as a PASV/EPSV/PORT/EPRT translation gateway
  
  % delegated -P8021 SERVER=ftp
  
  
• how to use DeleGate as a PASS / APOP translation gateway
  
  % delegated -P8110 SERVER=pop
  
  
• how to use DeleGate as a gateway for TCP clients to a UDP server
  
  % delegated -Pport SERVER=tcprelay://svhost:svport CONNECT=udp
  
  
• how to use DeleGate as a gateway for UDP clients to a TCP server
  
  % delegated -Pport SERVER=udprelay://svhost:svport CONNECT=tcp
  
  

• How to use DeleGate for caching HTTP messages
  % delegated -P8080 SERVER=http CACHE=do
  
  
• How to use DeleGate for caching FTP directories and files
  % delegated -P8021 SERVER=ftp CACHE=do
  
  
• How to use DeleGate for caching NNTP articles
  % delegated -P8119 SERVER=nntp://server CACHE=do
  
  

• How to use DeleGate for filtering response data to the client
  % delegated -Pport SERVER=protocol FTOCL=filterCommand
  
  
• How to use DeleGate for filtering request data to the server
  % delegated -Pport SERVER=protocol FTOSV=filterCommand
  
  
• How to use DeleGate for filtering HTTP request header fields
  % delegated -P8080 SERVER=http HTTPCONF=kill-qhead:Referer,Via,From,Cookie
  
  
• How to use DeleGate for filtering HTTP response header fields
  % delegated -P8080 SERVER=http HTTPCONF=kill-rhead:Server,Set-Cookie
  
  
• How to use DeleGate for filtering HTML tags in a HTTP response
  % delegated -P8080 SERVER=http HTTPCONF=kill-tag:SCRIPT,APPLET
  
  

• How to use DeleGate as a HTTP proxy which asks authentication
  % delegated -P8080 SERVER=http AUTHORIZER=-pam
  
  
• How to use DeleGate as a HTTP proxy which asks authentication for POST
  % delegated -P8080 SERVER=http MOUNT="http://server/* = AUTHORIZER=-pam://POST"
  
  
• How to use DeleGate as a SMTP proxy which asks authentication
  % delegated -P25 SERVER=smtp://server AUTHORIZER=-pam
  
  
• How to use DeleGate as a SMTP proxy which sends authentication by proxy
  % delegated -P25 SERVER=smtp://server MYAUTH=username:password
  
  

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:

-Pii.ii.ii.ii:8080

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:

HOSTLIST=.localnet:127.0.0.1,192.168.1.0/24

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:

AUTHORIZER=-pam

To enable the certificate based authentication, specify "-Vrfy" option of the SSLway filter.

STLS="fcl,sslway -Vrfy -CAfile file"

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).

REACHABLE=192.168.1.1:80,127.0.0.1

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:

REMITTABLE=http/80,https/443

See the reference manual for more details about access control.

The minimum installation of DeleGate is just getting the executable file of DeleGate and putting it to somewhere on your host.

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.

% delegated -P8080 SERVER=http
[12345] -P8080 READY
DGROOT=/home/dgowner/delegate
...

Optionally, you should install DGROOT/subin/ when you use DeleGate on Unix, in a usage requiring super-user's privilege.

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.

On Unix, DeleGate needs the privilege of super-user when it use privileged port number as -P80, PAM based authentication with AUTHORIZER=-pam, or changing the root directory with CHROOT=path.

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.

% su
# chown root dgbind
# chmod 6550 dgbind

The group ownership of the executable files in subin must be the same with the run-time group-ID of your DeleGate (delegated) process.

# chgrp group dgbind