NAME¶

3proxy.cfg 3proxy configuration file

DESCRIPTION¶

Common structure:
Configuration file is a text file 3proxy reads configuration from. Each line of the file is a command executed immediately, as if it were given from the console. The sequence of commands is important. The configuration file is actually a script for the 3proxy executable. 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 line beginning with a space character or ´#´ character is a comment. It´s ignored. <LF>s are ignored. <CR> is the end of a command.

Quotation:
The quotation character is " (double quote). Quotation must be used to quote spaces or other special characters. To use a quotation character inside a quoted string, the character must be doubled (BASIC convention). For example, to use HELLO "WORLD" as an argument, you should write it as "HELLO ""WORLD""". 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 single-line commands (like userlist, network lists, etc). To use dollar sign somewhere in argument it must be quoted or doubled: inside quotes a dollar is ordinary text, and $$ stands for a single dollar and is not read as an include. Recursion is not allowed.

Next commands start gateway services:

proxy [options]
socks [options]
pop3p [options]
imapp [options]
smtpp [options]
ftppr [options]
admin [options]
dnspr [options]
tcppm [options] <SRCPORT> <DSTADDR> <DSTPORT>
udppm [options] <SRCPORT> <DSTADDR> <DSTPORT>
Descriptions:
proxy HTTP/HTTPS proxy (default port 3128)
socks SOCKS 4/4.5/5 proxy (default port 1080)
tlspr SNI proxy (destination address is taken from TLS handshake), may be used to redirect any TLS-based traffic
auto Proxy with protocol autoselection between proxy / socks / tlspr
pop3p POP3 proxy (default port 110), in a build which has one: otherwise the service is tlspr speaking POP3 to negotiate STARTTLS, under this name.
imapp IMAPv4 proxy (default port 143), or tlspr speaking IMAP, as above.
smtpp SMTP proxy (default port 25), or tlspr speaking SMTP, as above.
ftppr FTP proxy (default port 21), in a build with FTP support. Without it the service is known but answers nothing, and ftp:// is not a URL the HTTP proxy fetches.
admin Web interface (default port 80)
dnspr caching DNS proxy (default port 53)
tcppm TCP portmapper. Destination address (DSTADDR) can be a Unix domain socket using the syntax unix:/path/to/socket (e.g., tcppm 8080 unix:/var/run/app.sock 0). On Linux, abstract sockets use unix:@socketname syntax. When using Unix socket destination, the port number is ignored but must be specified for syntax compatibility.
udppm UDP portmapper

Options:
-pNUMBER change default server port to NUMBER
-6 Only resolve IPv6 addresses. IPv4 addresses are packed in IPv6 in IPV6_V6ONLY compatible way.
-4 Only resolve IPv4 addresses. This is the default: a service reaches an IPv6 address only when told to with -6, -46 or -64.
-46 Prefer IPv4. Resolve IPv6 addresses if IPv4 address is not resolvable
-64 Prefer IPv6. Resolve IPv4 addresses if IPv6 address is not resolvable
-e External address. IP address of the interface the proxy should initiate connections from. External IP must be specified if you need incoming connections. By default the system will decide which address to use in accordance with the routing table.
-i Internal address. IP address the proxy accepts connections to. By default, connections to any interface are accepted. Unix domain sockets can be specified with -iunix:/path/to/socket syntax. On Linux, abstract sockets use -iunix:@socketname syntax.
-DiINTERFACE, -DeINTERFACE bind internal (-Di) / external (-De) interface to given INTERFACE (e.g. eth0) if SO_BINDTODEVICE is supported by the system. You may need to run as root or have CAP_NET_RAW capability in order to bind to an interface, depending on the system, so this option may require root privileges and can be incompatible with some configuration commands like chroot and setuid (and daemon if setcap is used).
-niPATH, -nePATH (Linux only) Switch to the network namespace identified by the filesystem path PATH (e.g. /var/run/netns/myns or /proc/PID/ns/net) for the listening socket (-ni) or for outgoing connections (-ne). With -ni the current namespace is saved before opening the listening socket and restored immediately after binding, so that the rest of the process (outgoing connections, child threads) runs in the original namespace unless -ne is also given. With -ne the process switches to the specified namespace after the listening socket is bound (and after restoring from -ni if applicable). Requires CAP_SYS_ADMIN (or CAP_NET_ADMIN on recent kernels) and is incompatible with chroot/setuid/daemon if privileges are dropped before the switch takes effect.
-Ne (for socks) External NAT address (between 3proxy and destination server) to report to client for CONNECT and BIND. By default external address is reported. It's only useful in the case of IP-IP NAT (will not work for PAT).
-Ni (for socks) Internal NAT address (between client and 3proxy) to report to client for UDPASSOC. By default internal address is reported. It's only useful in the case of IP-IP NAT (will not work for PAT).
-RHOST:port listen on given local HOST:port for incoming connections instead of making remote outgoing connection. Can be used with another 3proxy service running -r option for connect back functionality. Most commonly used with tcppm. HOST can be given as IP or hostname, useful in case of dynamic DNS.
-rHOST:port connect to given remote HOST:port instead of listening local connection on -p or default port. Can be used with another 3proxy service running -R option for connect back functionality. Most commonly used with proxy or socks. HOST can be given as IP or hostname, useful in case of dynamic DNS.
-ocOPTIONS, -osOPTIONS, -olOPTIONS, -orOPTIONS, -oROPTIONS options for proxy-to-client (-oc), proxy-to-server (-os), proxy listening (-ol), connect back client (-or), connect back listening (-oR) sockets. OPTIONS is a comma separated list of NAME or NAME=VALUE; a name alone sets the option to 1 (TCP_MAXSEG to the value of maxseg), and NAME=0 turns it off. Options add to the defaults and to the options given earlier for the same socket. An unknown name or a value which is not a number is an error. TCP_NODELAY is set by default on proxy-to-client and proxy-to-server sockets, so a reply written in several parts is not delayed by Nagle's algorithm; use -ocTCP_NODELAY=0 or -osTCP_NODELAY=0 to turn it off, e.g. to send fewer packets on slow links. Options like TCP_CORK, TCP_NODELAY, TCP_DEFER_ACCEPT, TCP_QUICKACK, TCP_TIMESTAMPS, TCP_FASTOPEN, SO_REUSEADDR, SO_REUSEPORT, SO_EXCLUSIVEADDRUSE, SO_PORT_SCALABILITY, SO_REUSE_UNICASTPORT, SO_KEEPALIVE, SO_DONTROUTE may be supported depending on OS. SO_REUSEADDR and SO_REUSEPORT are set by default on the listening sockets (-ol, -oR) on Unix; -olSO_REUSEPORT=0 turns one off. On Windows SO_REUSEADDR is not set: it is not required to rebind a listening port and it only lets another local process bind the same address and port. Use SO_EXCLUSIVEADDRUSE (Windows) on the listening socket (-ol) to prevent that.
-H (for all services) Expect HAProxy PROXY protocol v1 header on incoming connection. This allows the proxy to receive real client IP address from HAProxy or other load balancer that supports the PROXY protocol. The header must be sent before any protocol-specific data.
-g(GRACE_TRAFF,GRACE_NUM,GRACE_DELAY) delay GRACE_DELAY milliseconds before polling if average polling size is below GRACE_TRAFF bytes and GRACE_NUM read operations in a single direction are detected within 1 second. Useful to minimize polling
-s
(for admin) secure, allow only secure operations, currently only traffic counters view without ability to reset.
(for TCP services, Linux) use splice() to pass data between the client and the server without copying it through 3proxy. -s alone splices both directions where it pays: a body of known length if at least 16K of it is left to read, a stream once it carries large reads, back to copying when they turn small. -s1 always splices what the server sends to the client (downloads), -s2 what the client sends (uploads), -s3 both; adding 4 (-s5, -s6, -s7, the last the same as -s) splices those directions only where it pays. -s0, the default, turns it off. splice() suits large transfers: they go faster and use less CPU; small requests go slower with it. A spliced direction needs a pipe (two file descriptors), made when first needed and kept for the connection, and more kernel memory; data filters are not applied to spliced data. Available in builds with WITHSPLICE, the default on Linux.
-C
(for TCP services) a connection closed by any of the sides terminates the session, buffered data is delivered before the sockets are closed. By default the session is kept until both sides close the connection (TCP half-close). Half-close is required for the protocols where one of the sides closes its sending side and expects the answer, but it keeps the socket of the side which has already closed the connection in CLOSE_WAIT state. Use -C to close both sockets as soon as any of the sides closes the connection, -C1 to request the default behaviour explicitly.
-U[MODE]
(for socks) what to do when the destination changes within an UDP association: 1 - log it, 2 - authorize it, 3 - both, the default, 0 (same as bare -U) - neither. The destination of the first datagram is always authorized and logged. With -U0 and -U1 the destination is not authorized again, so ACLs limiting the destination only apply to the first destination of the association, and the parent proxy and the external address selected for it are kept for the whole association. Use -U2 to keep the authorization and to drop the per-destination log records only.
(for dnspr) simple, do not use resolver and 3proxy cache, always use external DNS server.
(for udppm) singlepacket, expect only one packet from both client and server
-u Never ask for username/password
-u2 (for socks) require username/password in authentication methods
-a (for proxy) anonymous proxy (no information about client reported)
-a1 (for proxy) anonymous proxy (random client information reported)
-a2 (for proxy) generate Via: and X-Forwarded-For: instead of Forwarded:
-Xftp (for proxy) fetch ftp:// URLs, in a build with FTP support. Without this the scheme is not one the service knows, whatever the build: fetching it opens a second connection and builds a listing, which a service serving http has no use for.
Also, all options mentioned for proxy(8) socks(8) pop3p(8) imapp(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 resolves any types of records but only hostnames are cached. It requires nserver/nscache to be configured. If nserver is configured as TCP, redirections are applied on connection, so parent proxy may be used to resolve names to IP.
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

include <path>
Include config file

config <path>
Path to configuration file to use on 3proxy restart.

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)
radius - use RADIUS for logging
LOGTYPE is one of:
c Minutely
H Hourly
D Daily
W Weekly (starting from Sunday)
M Monthly
Y Annually
if logfile is not specified logging goes to stdout. You can specify individual logging options for gateway by using -l option in gateway configuration.
log command supports same format specifications for filename template as "logformat" (if filename contains ´%´ sign it´s believed to be template). As with "logformat" filename must begin with ´L´ or ´G´ to specify Local or Grinwitch time zone for all time-based format specificators.

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 abbreviation
%d Day
%H Hour
%M Minute
%S Second
%t Timestamp (in seconds since 01-Jan-1970)
%. milliseconds
%z time zone (from Greenwich)
%D request duration (in milliseconds)
%b average send rate per request (in bytes per second); this speed is typically below the connection speed shown by the download manager.
%B average receive rate per request (in bytes per second); this speed is typically below the connection speed shown by the 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
%i Internal IP used to accept client connection
%e External IP used to establish connection
%Q Requested IP
%q Requested 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 through N2 of service-specific text
In the case of ODBC logging, logformat specifies an SQL statement, for example:
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´)"

logdump <in_traffic_limit> <out_traffic_limit>
Immediately creates additional log records if given amount of incoming/outgoing traffic is achieved for connection, without waiting for connection to finish. It may be useful to prevent information about long-lasting downloads on server shutdown.

delimchar <char>
Sets the delimiter character used to separate username from hostname in proxy authentication strings (e.g. for FTP, POP3 proxies). Default is ´@´. For example, to use ´#´ instead: delimchar #. This allows usernames to contain the ´@´ character.

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> <CONNECT> <CONNECTBACK> <LINGER>
Sets timeout values, defaults 1, 5, 30, 60, 180, 1800, 15, 60, 15, 5, 5.
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
LINGER timeout to deliver buffered data after one of the sides has closed its sending side, also used as SO_LINGER value on outgoing connections. Too small value may cause the tail of the data to be lost on slow connections, too large one delays release of the sockets.
default timeouts 1 5 30 60 180 1800 15 60 15 5 5

maxseg <value>
Sets TCP maximum segment size (MSS) for outgoing connections. This can be used to work around path MTU discovery issues or to optimize traffic for specific network conditions.

radius <NAS_SECRET> <radius_server_1[:port][/local_address_1] <radius_server_2[:port][/local_address_2]
Configures RADIUS servers to be used for logging and authentication (log and auth types must be set to radius). port and local address to use with given server may be specified.
Attributes within request: User-Name, Password: (username and password if presented by client), Service Type: Authenticate-Only, NAS-Port-Type: NAS-Port-Virtual, NAS-Port-ID: (proxy service port, e.g. 1080), NAS-IPv6-Address / NAS-IP-Address: (proxy interface accessed by client), NAS-Identifier: (text identifing proxy, e.g. PROXY or SOCKSv5), Framed-IPv6-Address / Framed-IP-Address: (IP address of the client), Called-Station-ID: (requested Hostname, if presents), Login-Service: (type of request, e.g. 1001 - SOCKS CONNECT, 1010 - HTTP GET, 1013 - HTTP CONNECT), Login-TCP-Port: (requested port), Login-IPv6-Host / Login-IP-Host: (requested IP).
Supported reply attributes for authentication: Framed-IP-Address / Framed-IPv6-Address (IP to assign to user), Reply-Message. Use authcache to speedup authentication. RADIUS feature is currently experimental.

nserver <ipaddr>[:port][/tcp]
Nameserver to use for name resolutions. If none specified system routines for name resolution is used. Optional port number may be specified. If optional /tcp is added to IP address, name resolution is performed over TCP. An IPv6 address has to be enclosed in square brackets:
nserver 1.1.1.1
nserver [2001:4860:4860::8844]
nserver [2001:4860:4860::8844]:5353/tcp

authnserver <ipaddr>[:port][/tcp]
Nameserver to use for DNS-based authentication (e.g. dnsname auth type). If not specified, nserver is used. The syntax is the same as for nserver.

nscache <cachesize> nscache6 <cachesize>
Cache <cachesize> records for name resolution (nscache for IPv4, nscache6 for IPv6). The cache size should usually be large enough (for example, 65536). The two are separate: a name that resolves to an IPv6 address, including one given with nsrecord, is only held when nscache6 is configured, and nscache does nothing for it. Both caches are global rather than per-service.

nsrecord <hostname> <hostaddr>
Adds static record to nscache. nscache must be enabled and must come first, because the record is placed in the table it allocates - nscache6 for a record naming an IPv6 address - and nserver must be set as well: without it the system resolver is used and static records are never consulted. 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.

fakeresolve
All names are resolved to the 127.0.0.2 address. Useful if all requests are redirected to a parent proxy with http, socks4+, connect+ or socks5+.

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. Since 0.8 version, IPv6 address may be used.
Unix domain sockets are supported with the syntax unix:/path/to/socket (e.g., internal unix:/var/run/3proxy.sock). On Linux, abstract (fileless) Unix sockets are supported with the syntax unix:@socketname (e.g., internal unix:@3proxy). When using Unix sockets, the socket file is automatically created and removed on service start/stop.

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. Since 0.8 version External or -e can be given twice: once with IPv4 and once with IPv6 address.

maxconn <number>
sets the maximum number of simultaneous connections to each service started after this command at the network level. Default is 100.
To limit clients, use connlim instead. maxconn will silently ignore new connections, while connlim will report back to the client that the connection limit has been reached.

backlog
sets the listening socket backlog of new connections. Default is 1 + maxconn/8. Maximum value is capped by kernel tunable somaxconn.

service
(deprecated). Indicates that 3proxy should behave as a Windows 95/98/NT/2000/XP service; has no effect under Unix. Not required for 3proxy 0.6 and above. If you upgraded from a previous version of 3proxy, use --remove and --install to reinstall the service.

daemon
Should be specified to close the console. Do not use ´daemon´ with ´service´. At least under FreeBSD, daemon should precede any proxy service and log commands to avoid socket problems. Always place it in the beginning of the configuration file.

auth <authtype> [...]
Type of user authorization. Currently supported:
none - no authentication or authorization required.
Note: if auth is none, any IP-based limitation, redirection, etc. will not work. This is the default authentication type
iponly - authentication by access control list with username ignored.
Appropriate for most cases
useronly - authentication by username without checking for any password with authorization by ACLs. Useful for e.g. SOCKSv4 proxy.
dnsname - authentication by DNS hostname with authorization by ACLs. The DNS hostname is resolved via a PTR (reverse) record and validated (the resolved name must resolve to the same IP address). It´s recommended to use authcache by IP for this authentication. NB: there is no password check; the name may be spoofed.
strong - username/password authentication required. It will work with SOCKSv5, FTP, POP3 and HTTP proxy.
cache - cached authentication, may be used with ´authcache´.
cacheacl - cached authentication, same as cache but the ACL authorization result is also cached and not re-evaluated on each request. Faster than cache, but ACL changes do not take effect for cached users until the cache entry expires. Use cache if ACLs may change during the cache lifetime. Because the ACL is not walked on a cache hit, no redirection is applied to a request served from the cache: it is sent directly instead of through the parent proxy of the matching ACL entry, with no error reported. Do not use cacheacl together with parent proxies, use cache instead. The only redirection type which survives is extip, and only if ext is a part of the authcache key, because the external address is then restored from the cache entry.
radius - authentication with RADIUS.
Plugins may add additional authentication types.

It´s possible to use multiple authentication types in the same command. E.g.
auth iponly strong
In this case, ´strong´ authentication will be used only if resource access cannot be performed with ´iponly´ authentication, that is, a username is required in the ACL. It´s useful to protect access to some resources with a password while allowing passwordless access to other resources, or to use IP-based authentication for dedicated laptops and request a username/password for shared ones.

authcache <cachtype> <cachtime> <cachesize>
Cache authentication information for a given amount of time (cachetime) in seconds. cachesize limits number of cache entries. Cachetype is one of:
ip - after successful authentication all connections during caching time from same IP are assigned to the same user, username is not requested.
ip,user username is requested and all connections from the same IP are assigned to the same user without actual authentication.
user - same as above, but IP is not checked.
user,password - both username and password are checked against cached ones.
limit - limit user to use only one ip, ´ip´ and ´user´ are required
acl - only use cached auth if user access service with same ACL
ext - cache external IP
dstaddr - cache by destination IP address
dstport - cache by destination port
dsthost - cache by destination hostname
dstoper - cache by destination operation (e.g. HTTP method)
srvaddr - cache by service (listener) address
srvport - cache by service (listener) port
Multiple types can be combined (e.g. ip,user,dstaddr,dstport).
With cacheacl the ACL result is not re-evaluated on a cache hit, so every field the ACL limits must be a part of the cache key, otherwise the result cached for one request is applied to a different one: user/pass for the userlist, ip for the sourcelist, dstaddr/dsthost for the targetlist, dstport for the targetportlist and dstoper for the operationlist. It is especially important for SOCKSv5 UDP traffic, where the destination of every datagram is authorized: without dstaddr and dstport in the key the result cached for one destination is applied to any other destination and the destination is not checked at all, see allow.
Use auth type cache (or cacheacl) for cached authentication

allow <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
deny <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
redirect <ip> <port> <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), ranges A.B.C.D - W.X.Y.Z (since 0.8) or CIDRs (W.X.Y.Z/L). Since 0.6, the targetlist may also contain host names, instead of addresses. It´s possible to use a wildmask in the beginning and at the end of the hostname, e.g. *badsite.com or *badcontent*. The hostname is only checked if a hostname is present in the request. A name written with a pcre: prefix (regex: is the same thing) is a regular expression instead of a wildmask, in a build with PCRE support:
deny * * "pcre:^(ads|track)[0-9]*\.example\.(com|net)$"
The name is lowercased and any trailing dots are removed before it is matched, so patterns are written in lower case. A pattern ending in $ has to be quoted or written $$, since a lone dollar outside quotes begins the name of a file to include. The same patterns, and the same prefix, are used by the http command, see BUILT IN HTTP SERVER. Regular expressions are matched per request and cost more than a wildmask, which is enough for most rules. Targetportlist may contain ports (X) or port ranges 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 * to 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_DATA FTP data connection. Note: FTP_DATA requires access to dynamic non-privileged (1024-65535) ports on the remote side.
FTP matches any FTP/FTP Data request
ADMIN access to administration interface

Weekdays are week day 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.
A SOCKSv5 UDP ASSOCIATE request carries no destination, the destination of every datagram is taken from the datagram itself. 3proxy authorizes the destination of every datagram, so ACLs limiting the destination address, the destination host name or the destination port do apply to UDP traffic, unless the -U option of the socks service says otherwise.
ACLs are only checked for the datagrams sent by the client. A datagram received on the association is relayed to the client without an ACL check: with a parent proxy only the datagrams from the parent are accepted, an association without a parent accepts a datagram from any source. The source reported to the client is the actual source of the datagram. The address in the log record is the destination the client sent the datagrams to, the source of the datagrams received on the association is not logged.
A client may use a single association to reach many destinations. An ACL entry which limits the destination silently drops the datagrams to every other destination, so limiting the destination of UDP traffic can break such clients in a way which is hard to diagnose. Limit it only when it is really required.
Bandwidth limiters (bandlimin, bandlimout) and traffic counters (countin, countout) which limit the destination are selected when the destination is authorized, so within an UDP association they are selected for the destination of the first datagram and are not re-selected for every following destination. They can not be applied per destination to the incoming UDP traffic at all, because an incoming datagram is not matched against any destination.
Only socks5 and socks5+ parents can be used for UDP. Because every new destination is authorized, use authcache, especially with ´strong´, RADIUS or plugin authentication: cacheacl with the destination in the cache key if no parent proxy is used, cache otherwise, see cacheacl.

parent <weight> <type> <ip> <port> <username> <password>
this command must follow "allow" rule. It extends last allow rule to build proxy chain. Proxies may be grouped. Proxy inside the group is selected randomly. If few groups are specified one proxy is randomly 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. A weight is a share of the whole, written either as a fraction of one, anything beginning with 0 or with a point, or the old way, in thousandths:
.5 and 0.5 and 500 are all a half
.333 and 333 are both 333 thousandths
1000 and 1.0 and 100% are all the whole share
50.5% and .505 and 505 are all the same share
0 is a fallback, described below
A fraction takes up to nine digits after the point, .333333333 being the finest share there is, and the old notation may now carry further digits after a point of its own, so 123.456 means the same as .123456. Weights are scanned as integers, nothing is read as a floating point number. 1.0, with as many zeroes after the point as you care to write, is the one weight read as it looks rather than in thousandths, so that the whole share can be written as a fraction too: a bare 1 is still a thousandth of it, and 1.5 still one and a half of them. A weight ending in % is a percentage, and takes up to seven digits after the point.
Weights are summed and proxies are grouped together until the weight of the group is the whole share. A group which falls short of it by no more than a thousandth, which three weights of 333 do, is taken for a whole one rather than for a group with a remainder, so a share which cannot be divided evenly needs no adjusting by hand. That is:
allow *
parent 500 socks5 192.168.10.1 1080
parent 500 connect 192.168.10.1 3128
makes 3proxy to randomly choose between 2 proxies for all outgoing connections. These 2 proxies form 1 group (their weights are the whole share between them).
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. Chains are only applied to new connections, pipelined (keep-alive) requests in the same connection use the same chain.

type is one of:
extip does not actually redirect the request; it sets the external address for this request to <ip>. It can be chained with another parent type. It's useful to set the external IP based on ACL or make it random.
extport does not redirect the request; it sets the range the local port of outgoing connections is taken from, given as FIRST-LAST inclusive in place of the port argument, with 0.0.0.0 as the address, for example parent 1000 extport 0.0.0.0 40000-40100. Where the system can be asked to pick the port itself (Linux IP_LOCAL_PORT_RANGE) it does, otherwise a port is picked at random from the range and retried if it is already in use, up to ten times. A port which binds but whose pair with the destination is still closing from an earlier connection, which Windows refuses at the connect, is retried in the same way and out of the same ten tries, so a repeated connection to one destination does not fail for a port it has just used. On Linux the range has to lie within net.ipv4.ip_local_port_range, commonly 32768-60999: the kernel ignores a range outside it and picks an ordinary ephemeral port instead. If no port in the range can be bound, an ephemeral port is used rather than failing the connection. It can be chained with another parent type, and the access rule it belongs to decides which requests it applies to, so allow * * * * UDPASSOC followed by parent 1000 extport 0.0.0.0 40000-40100 limits it to UDP associations. The range is applied when the outgoing connection is made, so a kept alive connection carrying several requests uses the rule that matched when it was opened.
intport is the same for sockets bound on the side facing the client: the port a UDP association tells the client to send its datagrams to, and the FTP proxy data connection.
tcp simply redirect connection. TCP is always last in chain. This type of proxy is a simple TCP redirection, it does not support parent authentication.
http redirect to HTTP proxy. HTTP is always the last chain. It should only be used with http (proxy) service, if used with different service, it works as tcp redirection.
pop3 redirect to POP3 proxy (only local redirection is supported, can only be used as a first hop in chaining)
ftp redirect to FTP proxy (only local redirection is supported, can only be used as a first hop in chaining)
connect parent is HTTP CONNECT method proxy
connect+ parent is HTTP CONNECT proxy with name resolution (hostname is used instead of IP if available)
socks4 parent is SOCKSv4 proxy
socks4+ parent is SOCKSv4 proxy with name resolution (SOCKSv4a)
socks5 parent is SOCKSv5 proxy
socks5+ parent is SOCKSv5 proxy with name resolution
socks4b parent is SOCKS4b (broken SOCKSv4 implementation with shortened server reply; I never saw this kind of server, but they say there are some). Normally you should not use this option. Do not confuse this option with SOCKSv4a (socks4+).
socks5b parent is SOCKS5b (broken SOCKSv5 implementation with shortened server reply. I think you will never find it useful). Never use this option unless you know exactly you need it.
admin redirect request to local ´admin´ service (with -s parameter).
ha send HAProxy PROXY protocol v1 header to the next parent proxy (or to the destination if ha is used alone). Place ha before the parent that should receive the header; after the header is sent, negotiation of that parent protocol continues (SOCKS, CONNECT, etc.). Useful for passing client IP information to the parent proxy. Example:
parent 1000 ha 0.0.0.0 0
parent 1000 socks5 parent.example.com 1080
Use "+" proxy only with fakeresolve option
Any parent type above can be suffixed with s (e.g. https, tcps, socks5s, connect+s) to establish a TLS-encrypted connection to the parent proxy. Requires SSL/TLS support (WITH_SSL) and is used with ssl_client_mode 3, which only handshakes TLS for s-suffixed parents.

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, ftp locally redirects to ftppr pop3 locally redirects to pop3p imap locally redirects to imapp http locally redirects to proxy admin locally redirects to the admin -s service.
Unix domain sockets can be used instead of IP address with the syntax unix:/path/to/socket (e.g., parent 1000 socks5 unix:/var/run/parent.sock 1080). On Linux, abstract (fileless) Unix sockets are supported with unix:@socketname syntax (e.g., parent 1000 http unix:@parent.proxy 3128). When using Unix sockets, the port number is ignored but must be specified for syntax compatibility.

Main purpose of local redirections is to have the requested resource (URL or POP3 username) logged and protocol-specific filters applied. In case of local redirection, ACLs are reviewed twice: first, by the SOCKS proxy up to the ´parent´ command and then by the gateway service the connection is redirected to (HTTP, FTP or POP3) after the ´parent´ command. It means an 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.
parent 1000 http 1.2.3.4 0
Changes the external address for a given connection to 1.2.3.4 (equivalent to -e1.2.3.4)
Optional username and password are used to authenticate on parent proxy. Username of ´*´ means username must be supplied by user.
A parent which fails is taken out of the choice for the rest of that connection, so the next attempt, see parentretries, goes to another member of the group instead of the same parent again. Its share is spread over the parents of the group which are left, in proportion to their weights.
Weight 0 marks a fallback parent. Such a parent takes no share of the random choice, and none of the share left over by a parent which failed, and is only used once every weighted parent of its group has failed, which is how a parent used only when another one is down is configured:
allow *
parent 1000 socks5 192.168.10.1 1080
parent 0 socks5 192.168.20.1 1080
Several fallbacks are tried in the order they are written. Reaching a fallback costs an attempt, so parentretries has to be at least as large as the number of parents to try.
When every parent of a group has failed the request fails as well, rather than being sent without a parent.

parentretries <number>
Number of attempts to reach a parent proxy. Default is 2. Each attempt picks a parent again, leaving out the ones which already failed, so this is also the number of different parents a request may be tried through.

nolog <n>
extends last allow or deny command to prevent logging, e.g.
allow * * 192.168.1.1
nolog

weight <n>
extends last allow or deny command to set weight for this request
allow * * 192.168.1.1
weight 100
Weight may be used for different purposes.

force
noforce
If force is specified for service, configuration reload will require all current sessions of this service to be re-authenticated. If ACL is changed or user account is removed, old connections which do not match current are closed. noforce allows to keep previously authenticated connections.

bandlimin <rate> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
nobandlimin <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
bandlimout <rate> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
nobandlimout <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
bandlim sets a bandwidth limitation filter to <rate> bps (bits per second). If you want to specify bytes per second, multiply your value by 8. bandlim rules act in the same manner as allow/deny rules, except for one thing: bandwidth limiting is applied to all services, not to some specific service. bandlimin and nobandlimin apply to incoming traffic
bandlimout and nobandlimout apply to outgoing traffic
If you want to ratelimit your clients with IPs 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 each of your clients will have a 56K channel. If you specify
bandlimin 57600 * 192.168.10.16/30
you will have a 56K channel shared between all clients. If you want, for example, to limit all speed except access to POP3, you can use
nobandlimin * * * 110
before the rest of bandlim rules.

connlim <rate> <period> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
noconnlim <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
connlim sets connections rate limit per time period for traffic pattern controlled by ACL. Period is in seconds. If period is 0, connlim limits a number of parallel connections.
connlim 100 60 * 127.0.0.1
allows 100 connections per minute for 127.0.0.1.
connlim 20 0 * 127.0.0.1
allows 20 simultaneous connections for 127.0.0.1.
Like with bandlimin, if an individual limit is required per client, a separate rule must be added for every client. Like with nobandlimin, noconnlim adds an exception.

counter <filename> <reporttype> <reportname>
countin <number> <type> <limit> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
nocountin <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
countout <number> <type> <limit> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
nocountout <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
countall <number> <type> <limit> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
nocountall <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>

counter, countin, nocountin, countout, nocountout, countall, nocountall commands are used to set a traffic limit in MB for a period of time (day, week or month). Filename is a path to a special file where traffic information is permanently stored. The number is the sequential number of the record in this file. If the number is 0, this counter is not preserved in the counter file (that is, if the proxy is restarted, all counters with 0 are flushed); otherwise, it should be a unique sequential number which points to the position of the counter within the file. Type specifies a type of counter. Type is one of:
H - counter is reset hourly
D - counter is reset daily
W - counter is reset weekly
M - counter is reset monthly
reporttype/reportname may be used to generate traffic reports. Reporttype is one of D, W, M, H (hourly) and reportname specifies the filename template for reports. The report is a text file with counter values in the format:
<COUNTERNUMBER> <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. $1$ prefix uses MD5-crypt (requires OpenSSL), $3$ prefix uses BLAKE2b-crypt (always available, see 3proxy_crypt(8))
NT - password is NT password (in hex)
example:
users test1:CL:password1 "test2:CR:$1$lFDGlder$pLRb4cU2D7GAT58YQvY49."
users test3:NT:BD7DFBF29A93F93C63CB84790DA00E63
users "test4:CR:$3$salt$G47yV9w...."
Note: double quotes are required because the password contains a $ sign.

transparent [auto|netfilter|pf|socket]
Take the destination of a connection, both address and port, from the packet filter that redirected it, instead of from the request. It applies to services declared after it, and notransparent turns it off again for the services after that. Built into the binary since 1.0.1, and previously the separate TransparentPlugin.
On Linux the kernel is asked, so iptables or nftables redirection is enough. On the BSDs pf is asked through /dev/pf, which 3proxy must be able to read, so rdr rules work; a redirection that leaves the destination on the socket is used where there is one, as divert-to on OpenBSD and ipfw fwd on FreeBSD do. macOS ships no header for pf and has neither of those, so the commands exist in a macOS build but cannot be used.
The mechanism is chosen automatically. The optional argument pins it for an installation that has more than one: auto is the default, netfilter asks the Linux kernel, pf looks the connection up in the packet filter, and socket reads the address off the socket. A mode the build has no code for is refused rather than ignored.
A connection that reaches a socket mode service without having been redirected is refused: its destination is the address the service listens on, and using that would send the service to itself.
A redirected connection carries no destination of its own, so without this the service uses whatever it would use otherwise: the Host header for an HTTP request, or the address a port mapper was configured with. tlspr receives nothing at all unless traffic is redirected to it or the clients resolve names to it, and with a redirection it has the address as well as the name from the handshake, which is what allows access rules to be written with host names. With it, every service reaches the address the client was trying to reach, and access rules, parents, limits and logging apply to it as usual.
The redirection rules must not match the connections the proxy itself makes to those destinations, or the traffic returns to the proxy and loops. Give the service an outgoing address with -e and exclude that address in the rules, or run 3proxy as its own user and exclude that user. See the TRANSPARENT PROXYING section of the documentation for rules per platform.
notransparent
Stop taking the destination from the packet filter for the services declared after it.

flush
empty the active access list. The access list must be flushed every time you create a new access list for a new service. For example:
allow *
pop3p
flush
allow * 192.168.1.0/24
socks
sets different ACLs for pop3p and socks

system <command>
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:

monitor <filename>
If file monitored changes in modification time or size, 3proxy reloads configuration within one minute. Any number of files may be monitored.

setuid <uid>
calls setuid(uid), uid can be numeric or since 0.9 username. Unix only. Warning: under some Linux kernels setuid() works for current thread only. It makes it impossible to suid for all threads.

setgid <gid>
calls setgid(gid), gid can be numeric or since 0.9 groupname. Unix only.

chroot <path> [<uid>] [<gid>]
calls chroot(path) and sets gid/uid. Unix only. uid/gid supported since 0.9, can be numeric or username/groupname. The time zone and the syslog connection are set up before the call. Plugins which read their own configuration or load modules while running need them inside the chroot: PAM (/etc/pam.d and the modules it names, read for every authentication), LDAP (ldap.conf and, for ldaps, the CA certificates), ODBC (odbc.ini, odbcinst.ini and the driver libraries, loaded again whenever the connection is reopened).

stacksize <value_to_add_to_default_stack_size>
Change the default size for thread stacks. May be required in some situations, e.g. with non-default plugins, or on some platforms (some FreeBSD versions may require adjusting the stack size due to an incorrectly defined value in system header files; this value is also often required to be changed for ODBC and PAM support on Linux). If you experience 3proxy crash on request processing, try to set some positive value. You may start with stacksize 65536 and then find the minimal value for the service to work. If you experience memory shortage, you can try to experiment with negative values.
With SQL logging (log &ODBC_string) the value is automatically raised to 32768 if it is smaller, because ODBC drivers require more stack. A stacksize command placed after the log command overrides this.
The base stack size the value is added to is 49152. On FreeBSD, NetBSD, OpenBSD and DragonFly it is 65536, because libc functions such as vfprintf() called by syslog() use significantly more stack there. The result is never lowered below PTHREAD_STACK_MIN, so a large negative value can not disable the thread stack.

PLUGINS¶

plugin <path_to_shared_library> <function_to_call> [<arg1> ...]
Loads specified library and calls given export function with given arguments, as
int functions_to_call(struct pluginlink * pl, int argc, char * argv[]);
function_to_call must return 0 in case of success, value > 0 to indicate error.

filtermaxsize <max_size_of_data_to_filter>
If Content-length (or another data length) is greater than the given value, no data filtering will be performed through filtering plugins to avoid data corruption and/or Content-Length changing. Default is 1MB (1048576).

SSL/TLS SUPPORT¶

SSL/TLS support is built into 3proxy (since 0.9.7) when compiled with OpenSSL (WITH_SSL). Previously available as SSLPlugin, the functionality is now integrated into the main binary. The plugin line is no longer required.

SSL/TLS can be used for: - transparent MITM (Man-in-the-Middle) for TLS traffic inspection - https:// proxy (TLS-encrypted connection between client and proxy) - TLS client connections to upstream servers with certificate authentication - mTLS (mutual TLS) requiring client certificates

PCRE FILTERING¶

PCRE (Perl Compatible Regular Expressions) filtering is built into 3proxy (since 0.9.7) when compiled with PCRE2 support (WITH_PCRE). Previously available as PCREPlugin, the functionality is now integrated into the main binary. The plugin line is no longer required.

PCRE filtering allows creating matching and replacement rules with regular expressions for client requests, headers, and data.

OPTIONAL SERVICES¶

The mail proxies and FTP are built when they are asked for, and are not in a default build. MAILPROXY=true builds pop3p, imapp and smtpp, and FTP=true builds ftppr and the ftp:// scheme of the HTTP proxy, which a proxy service then still has to ask for with -Xftp; with CMake the switches are -D3PROXY_USE_MAILPROXY=ON and -D3PROXY_USE_FTP=ON. The standalone binaries of those services are built with them and not without.
A configuration naming a service which was not built is still read. The three mail proxies become tlspr negotiating STARTTLS in that protocol, which is what most of their use amounts to now that the mail protocols are used over TLS, and a parent chain naming pop3, imap or smtp does the same. ftppr is answered by nothing: a client reaching it is turned away and the refusal logged, since there is no protocol to fall back on.

BUILT IN HTTP SERVER¶

The httpsrv service answers requests itself instead of forwarding them. What it does with a request is decided by http rules, which are taken in the order they are written: the first whose host and URL both match handles the request. Rules belong to the service that follows them, the way access rules do, and admin is httpsrv with a set of rules already in place.

http OPERATION HOST URL [PARAMETERS]
Handle a request for URL on HOST with OPERATION. HOST is matched against the Host header, URL against the path, with the query string removed.

BUGS¶

Report all bugs to 3proxy@3proxy.org

SEE ALSO¶

3proxy(8), 3proxy_crypt(8), proxy(8), ftppr(8), socks(8), pop3p(8), imapp(8), smtpp(8), tlspr(8), tcppm(8), udppm(8), syslogd(8),
https://3proxy.org/

AUTHORS¶

3proxy is designed by Vladimir Dubrovin <vlad@3proxy.org>