3proxy.conf

Section: Universal proxy server (5)
Updated: December 2004
Index Return to Main Contents

NAME

3proxy.conf - 3proxy configuration file

DESCRIPTION

Common structure: Configuration file is a text file 3proxy reads configuration from. Each line of the file is command and is executed immediately, as it was given from console. Each line of the file is treated as a blank (space or tab) separated command line. Additional space characters are ignored. Think about 3proxy as "application level router" with console interface. Comments: Any string beginning with space character or '#' character is comment. It's ignored. <LF>s are ignored. <CR> is end of command. Quotation: Quotation character is spaces or another special characters. To use quotation character inside quotation character must be dubbed (BASIC convention). For example to use HELLO Good practice is to quote any argument you use. File inclusion: You can include file by using $FILENAME macro (replace FILENAME with a path to file, for example $/usr/local/etc/3proxy/conf.incl or
$"c:\Program Files\3proxy\include.cfg" Quotation is required in last example because path contains space character. For included file <CR> (end of line characters) is treated as space character (arguments delimiter instead of end of command delimiter). Thus, include files are only useful to store long signle-line commands (like userlist, network lists, etc). To use dollar sign somewhere in argument it must be quoted. Recursion is not allowed. Commands: proxy [options]
socks [options]
pop3p [options]
ftppr [options]
admin [options]
dnspr [options]
tcppm [options] <SRCPORT> <DSTADDR> <DSTPORT>
udppm [options] <SRCPORT> <DSTADDR> <DSTPORT> starts gateway services proxy - HTTP/HTTPS proxy (default port 3128)
socks - SOCKS 4/4.5/5 proxy (default port 1080)
pop3p - POP3 proxy (default port 110)
ftppr - FTP proxy (default port 21)
admin - Web interface (default port 80)
dnspr - caching DNS proxy (default port 53)
tcppm - TCP portmapper
udppm - UDP portmapper Options:
-pNUMBER change default server port to NUMBER
-n disable NTLM authentication (required if passwords are stored in Unix crypt format.
Also, all options mentioned for proxy(8) socks(8) pop3p(8) tcppm(8) udppm(8) ftppr(8) are also supported. Portmapping services listen at SRCPORT and connect to DSTADDR:DSTPORT HTTP and SOCKS proxies are standard. POP3 proxy must be configured as POP3 server and requires username in the form of: pop3username@pop3server. If POP3 proxy access must be authenticated, you can specify username as proxy_username:proxy_password:POP3_username@pop3server DNS proxy is only capable to resolve hostnames (no MX, PTR, SRV, etc) and requires nserver/nscache to be configured. FTP proxy can be used as FTP server in any FTP client or configured as FTP proxy on a client with FTP proxy support. Username format is one of
FTPuser@FTPServer
FTPuser:FTPpassword@FTPserver
proxyuser:proxypassword:FTPuser:FTPpassword@FTPserver
Please note, if you use FTP client interface for FTP proxy do not add FTPpassword and FTPServer to username, because FTP client does it for you. That is, if you use 3proxy with authentication use proxyuser:proxypassword:FTPuser as FTP username, otherwise do not change original FTP user name
config <path>
Path to configuration file to use on 3proxy restart or to save configuration. writable
ReOpens configuration file for write access via Web interface, and re-reads it. Usually should be first command on config file but in combination with "config" it can be used anywhere to open alternate config file. Think twice before using it. end
End of configuration log [[@|&]logfile] [<LOGTYPE>]
sets logfile for all gateways
@ - (for Unix) use syslog, filename is used as ident name
& - use ODBC, filename consists of comma-delimited datasource,username,password (username and password are optional)
LOGTYPE is one of:
  M - Monthly
  W - Weekly (starting from Sunday)
  D - Daily
  H - Hourly if logfile is not specified logging goes to stdout. You can specify individual logging options for gateway by using -l option in gateway configuration. rotate <n> how many archived log files to keep logformat <format> Format for log record. First symbol in format must be L (local time) or G (absolute Grinwitch time). It can be preceeded with -XXX+Y where XXX is list of characters to be filtered in user input (any non-printable characters are filtered too in this case) and Y is replacement character. For example, "-,%+ L" in the beginning of logformat means comma and percent are replaced with space and all time based elemnts are in local time zone. You can use:
%y - Year in 2 digit format
%Y - Year in 4 digit format
%m - Month number
%o - Month abbriviature
%d - Day
%H - Hour
%M - Minute
%S - Second
%t - Timstamp (in seconds since 01-Jan-1970)
%. - milliseconds
%z - timeZone (from Grinvitch)
%D - request duration (in milliseconds)
%b - average send rate per request (in Bytes per second) this speed is typically below connection speed shown by download manager.
%B - average receive rate per request (in Bytes per second) this speed is typically below connection speed shown by download manager.
%U - Username
%N - service Name
%p - service Port
%E - Error code
%C - Client IP
%c - Client port
%R - Remote IP
%r - Remote port
%n - requested hostname
%I - bytes In
%O - bytes Out
%h - Hops (redirections) count
%T - service specific Text
%N1-N2T - (N1 and N2 are positive numbers) - log only fields from N1 thorugh N2 of service specific text in case of ODBC logging logformat specifies SQL statement, for exmample:
   logformat "-'+_Linsert into log (l_date, l_user, l_service, l_in, l_out, l_descr) values ('%d-%m-%Y %H:%M:%S', '%U', '%N', %I, %O, '%T')" archiver <ext> <commandline>
Archiver to use for log files. <ext> is file extension produced by archiver. Filename will be last argument to archiver, optionally you can use %A as produced archive name and %F as filename. timeouts <BYTE_SHORT> <BYTE_LONG> <STRING_SHORT> <STRING_LONG> <CONNECTION_SHORT> <CONNECTION_LONG> <DNS> <CHAIN> Sets timeout values
BYTE_SHORT - short timeout for single byte, is usually used for receiving single byte from stream.
BYTE_LONG - long timeout for single byte, is usually used for receiving first byte in frame (for example first byte in socks request).
STRING_SHORT - short timeout, for character string within stream (for example to wait between 2 HTTP headers)
STRING_LONG - long timeout, for first string in stream (for example to wait for HTTP request).
CONNECTION_SHORT - inactivity timeout for short connections (HTTP, POP3, etc).
CONNECTION_LONG - inactivity timeout for long connection (SOCKS, portmappers, etc).
DNS - timeout for DNS request before requesting next server
CHAIN - timeout for reading data from chained connection nserver
<ipaddr>
Nameserver to use for name resolutions. If none spcified system or name server fails system routines for name resolution will be used. It's better to specify nserver because gethostbyname() may be thread unsafe. nscache <cachesize>
Cache <cachesize> records for name resolution. Cachesize usually should be large enougth (for example 65536). nsrecord <hostname> <hostaddr> Adds static record to nscache. nscache must be enabled. If 0.0.0.0 is used as a hostaddr host will never resolve, it can be used to blacklist something or together with dialer command to set up UDL for dialing. dialer <progname>
Execute progname if external name can't be resolved. Hint: if you use nscache, dialer may not work, because names will be resolved through cache. In this case you can use something like http://dial.right.now/ from browser to set up connection. internal <ipaddr>
sets ip address of internal interface. This IP address will be used to bind gateways. Alternatively you can use -i option for individual gateways external <ipaddr>
sets ip address of external interface. This IP address will be source address for all connections made by proxy. Alternatively you can use -e option to specify individual address for gateway.
    maxconn <number>
sets maximum number of simulationeous connections to each services started after this command. Default is 100. service
(depricated) Should be specified to launch as Windows 95/98/NT/2000/XP service, no effect for Unix. Is not reqired since 0.6, but you must re-install 3proxy service with --remove and --install. daemon
Should be specified to close console (not required for 'service'). At least under FreeBSD 'daemon' should preceed any proxy service and log commands to avoid sockets problem. Always place it in the beginning of the configuration file. auth
Type of user authorization. Currently supported:
none - no authorization required. Note: is auth is none any ip based limitation, redirection, etc will not work.
iponly - authorization by source/destination IP and ports. Appropriate for most cases
nbname - iponly + authorization by NetBIOS name. Messanger service should be started on user's machine. Note, that Windows 95/98 hosts do not have messanger service by default, WinPopup program need to be started. NB: there is no any password check, name may be spoofed. Think about it as about ident for Windows.
Q: Will ident authorization be implemented?
A: Yes, as soon as it will be required by someone.
strong - username/password authentication required. It will work with SOCKSv5, FTP, POP3 and HTTP proxy. allow <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
deny <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
Access control entries. All lists are comma-separated, no spaces are allowed. Usernames are case sensitive (if used with authtype nbname username must be in uppercase). Source and target lists may contain IP addresses (W.X.Y.Z) or CIDRs (W.X.Y.Z/L). Targetportlist may contain ports (X) or port lists (X-Y).  For any field * sign means "ANY"
If access list is empty it's assumed to be
allow * If access list is not empty last item in access list is assumed to be
deny * You may want explicitly add "deny *" into the end of access list to prevent HTTP proxy from requesting user's password. Access lists are checked after user have requested any resource. If you want 3proxy to reject connections from specific addresses immediately without any conditions you should either bind proxy to appropriate interface only or to use ip filters. Operation is one of:
CONNECT        - establish outgoing TCP connection

BIND - bind TCP port for listening
UDPASSOC - make UDP association
ICMPASSOC - make ICMP association (for future use)
HTTP_GET - HTTP GET request
HTTP_PUT - HTTP PUT request
HTTP_POST - HTTP POST request
HTTP_HEAD - HTTP HEAD request
HTTP_CONNECT - HTTP CONNECT request
HTTP_OTHER - over HTTP request
HTTP - matches any HTTP request except HTTP_CONNECT
HTTPS - same as HTTP_CONNECT
FTP_GET - FTP get request
FTP_PUT - FTP put request
FTP_LIST - FTP list request
FTP - matches any FTP request Weeksdays are week days numbers or periods (0 or 7 means Sunday, 1 is Monday, 1-5 means Monday through Friday). Timeperiodlists is a list of time periods in HH:MM:SS-HH:MM:SS format. For example,
00:00:00-08:00:00,17:00:00-24:00:00 lists non-working hours.
parent <weight> <type> <ip> <port> <username> <password>
this command may follow "allow" rule. It extends last allow rule to build proxy chain. Proxy may be grouped. Proxy inside the group is selected randomely. If few groups are specified one proxy is randomely picked from each group and chain of proxies is created (that is second proxy connected through first one and so on). Weight is used to group proxies. Weigt is a number between 1 and 1000. Weights are summed and proxies are grouped together untill weight of group is 1000. That is:
allow *
parent 500 socks5 192.168.10.1 1080
parent 500 connect 192.168.10.1 3128 makes 3proxy to randomely choose between 2 proxies for all outgoing connections
allow * * * 80
parent 1000 socks5 192.168.10.1 1080
parent 1000 connect 192.168.20.1 3128
parent 300 socks4 192.168.30.1 1080
parent 700 socks5 192.168.40.1 1080 creates chain of 3 proxies: 192.168.10.1, 192.168.20.1 and third is (192.168.30.1 with probability of 0.3 or 192.168.40.1 with probability of 0.7) for outgoing web connections. type is one of:
tcp - simply redirect connection. TCP is always last in chain.
http - redirect to HTTP proxy. HTTP is always last chain.
pop3 - redirect to POP3 proxy (only local redirection is supported, can not be used for chaining)
ftp - redirect to FTP proxy (only local redirection is supported, can not be used for chaining)
connect - parent is HTTP CONNECT method proxy
socks4 - parent is SOCKSv4 proxy
socks5 - parent is SOCKSv5 proxy IP and port are ip addres and port of parent proxy server. If IP is zero, ip is taken from original request, only port is changed. If port is zero, it's taken from original request, only IP is changed. If both IP and port are zero - it's a special case of local redirection, it works only with socks proxy. In case of local redirection request is redirected to different service, ftppr pop3p proxy . Main purpose of local redirections is to have requested resource (URL or POP3 username) logged and protocol-specific filters to be applied. In case of local redirection ACLs are revied twice: first, by SOCKS proxy up to redirected (HTTP, FTP or POP3) after 'parent' command. It means, additional 'allow' command is required for redirected requests, for example:
allow * * * 80
parent 1000 http 0.0.0.0 0
allow * * * 80 HTTP_GET,HTTP_POST
socks redirects all SOCKS requests with target port 80 to local HTTP proxy, local HTTP proxy parses requests and allows only GET and POST requests. Optional username and password are used to authenticate on parent proxy. Username of '*' means username must be supplied by user. bandlimin <rate> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist>
nobandlimin <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist>
bandlim sets bandwith limitation filter to <rate> bps (bits per second) (if you want to specife bytes per second - multiply your value to 8). bandlim rules act in a same manner as allow/deny rules except one thing: bandwidth limiting is applied to all services, not to some specific service. bandlimin and nobandlimin applies to incoming traffic bandlimout and nobandlimout applies to outgoing traffic If tou want to ratelimit your clients with ip's 192.168.10.16/30 (4 addresses) to 57600 bps you have to specify 4 rules like
bandlimin 57600 * 192.168.10.16
bandlimin 57600 * 192.168.10.17
bandlimin 57600 * 192.168.10.18
bandlimin 57600 * 192.168.10.19 and every of you clients will have 56K channel. if you specify

bandlimin 57600 * 192.168.10.16/30 you will have 56K channel shared between all clients. if you want, for example, to limit all speed ecept access to POP3 you can use
nobandlimin * * * 110 before the rest of bandlim rules. counter <filename> <reporttype> <repotname>
countin <number> <type> <limit> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist>
nocountin <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist>
counter, countin, nocountin commands are used to set traffic limit in MB for period of time (day, week or month). Filename is a path to a special file where traffic information is permanently stored. number is sequential number of record in this file. If number is 0 no traffic information on this counter is saved in file (that is if proxy restarted all information is loosed) overwise it should be unique sequential number. Type specifies a type of counter. Type is one of:
D - counter is resetted daily
W - counter is resetted weekly
M - counter is resetted monthely reporttype/repotname may be used to generate traffic reports. Reporttype is one of D,W,M,H(hourly) and repotname specifies filename template for reports. Report is text file with counter values in format:
<COUNTERNUMBER> <TRAF*4GB> <TRAF> The rest of parameters is identical to bandlim/nobandlim. users username[:pwtype:password] ...
pwtype is one of:
none (empty) - use system authentication
CL - password is cleartext
CR - password is crypt-style password
NT - password is NT password (in hex) example:
users test1:CL:password1 "test2:CR:$1$lFDGlder$pLRb4cU2D7GAT58YQvY49."
users test3:NT:BD7DFBF29A93F93C63CB84790DA00E63
(note: double quotes are requiered because password contains $ sign).
flush
empty active access list. Access list must be flushed avery time you creating new access list for new service. For example:
allow *
pop3p
flush
allow * 192.168.1.0/24
socks sets different ACLs for pop3p and socks system
execute system command pidfile <filename>
write pid of current process to file. It can be used to manipulate 3proxy with signals under Unix. Currently next signals are available: setuid <uid>
calls setuid(uid), uid must be numeric. Unix only. setgid <gid>
calls setgid(gid), gid must be numeric. Unix only. chroot <path>
calls chroot(path). Unix only.

TRIVIA

3APA3A is pronounced as ``zaraza''.

AUTHORS

3proxy is designed by 3APA3A (3APA3A@security.nnov.ru), Vladimir Dubrovin (vlad@sandy.ru)