3proxy.cfg - 3proxy configuration file
Common
structure:
Configuration file is a text file 3proxy reads configuration
from. Each line of the file is a command executed
immediately, as it was given from console. Sequence of
commands is important. Configuration file as actually a
script for 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 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 " (double quote). Quotation must
be used to quote spaces or another special characters. To
use quotation character inside quotation character must be
dubbed (BASIC convention). For example to use HELLO
"WORLD" as an argument you should use 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 signle-line
commands (like userlist, network lists, etc). To use dollar
sign somewhere in argument it must be quoted. Recursion is
not allowed.
Next commands start gateway services:
proxy
[options]
socks [options]
pop3p [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)
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.
-n1 enable NTLMv1 authentication.
-s (for admin) - secure, allow only secure operations
(currently only traffic counters view without ability to
reset).
(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 (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-Forwared-For:
instead of Forwarded:
-6 Only resolve IPv6 addresses. IPv4 addresses are
packed in IPv6 in IPV6_V6ONLY compatible way.
-4 Only resolve IPv4 addresses
-46 Resolve IPv6 addresses if IPv4 address is not
resolvable
-64 Resolve IPv4 addresses if IPv6 address is not
resolvable
-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.
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 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 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.
"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 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
%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 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’)"
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.
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>[:port][/tcp]
Nameserver to use for name resolutions. If none specified or
name server fails system routines for name resolution will
be used. It’s better to specify nserver because
gethostbyname() may be thread unsafe. Optional port number
may be specified. If optional /tcp is added to IP address,
name resolution will be performed over TCP.
nscache
<cachesize> nscache6 <cachesize>
Cache <cachesize> records for name resolution (nscache
for IPv4, nscache6 for IPv6). 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.
fakeresolve
All names are resolved to 127.0.0.2 address. Usefull if all
requests are redirected to 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.
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 maximum number of simulationeous connections to each
services started after this command. Default is 100.
service
(depricated). Indicates 3proxy to behave as Windows
95/98/NT/2000/XP service, no effect for Unix. Not required
for 3proxy 0.6 and above. If you upgraded from previous
version of 3proxy use --remove and --install to reinstall
service.
daemon
Should be specified to close console. Do not use
’daemon’ with ’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
<authtype> [...]
Type of user authorization. Currently supported:
none - no authentication or authorization required.
Note: is auth is none any ip based limitation, redirection,
etc will not work. This is 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 and icqpr (icqpr set UIN / AOL screen name as
a username)
dnsname - authentication by DNS hostnname with authorization
by ACLs. DNS hostname is resolved via PTR (reverse) record
and validated (resolved name must resolve to same IP
address). It’s recommended to use authcache by ip for
this authentication. NB: there is no any password check,
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’.
Plugins may add additional authentication types.
It’s
possible to use few authentication types in the same
commands. E.g.
auth iponly strong
In this case ’strong’ authentication will be
used only in case resource access can not be performed with
’iponly’ authentication, that is username is
required in ACL. It’s usefull to protect access to
some resources with password allowing passwordless access to
another resources, or to use IP-based authentication for
dedicated laptops and request username/password for shared
ones.
authcache
<cachtype> <cachtime>
Cache authentication information to given amount of time
(cachetime) in seconds. Cahtype 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.
Use auth type ’cache’ for cached
authentication
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), ranges
A.B.C.D - W.X.Y.Z (since 0.8) or CIDRs (W.X.Y.Z/L). Since
0.6, targetlist may also contain host names, instead of
addresses. It’s possible to use wildmask in the
begginning and in the the end of hostname, e.g. *badsite.com
or *badcontent*. Hostname is only checked if hostname
presents in request. 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-ptivileged (1024-65535) ports on
remote side.
FTP - matches any FTP/FTP Data request
ADMIN - access to administration interface
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 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. 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 randomly choose between 2 proxies for all
outgoing connections. These 2 proxies form 1 group
(summarized weight is 1000).
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
connect+ - parent is HTTP CONNECT proxy with name resolution
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 ofservers
byt they say there are). Normally you should not use this
option. Do not mess 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).
Use "+" proxy only with "fakeresolve"
option
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 http locally redurects to proxy admin locally redirects to admin -s service.
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.
parent 1000 http 1.2.3.4 0
Changes external address for given connection to 1.2.3.4 (an
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.
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>
nobandlimin <userlist> <sourcelist>
<targetlist> <targetportlist>
<operationlist>
bandlimout <rate> <userlist>
<sourcelist> <targetlist> <targetportlist>
<operationlist>
nobandlimout <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>
countout <number> <type> <limit>
<userlist> <sourcelist> <targetlist>
<targetportlist> <operationlist>
nocountout <userlist> <sourcelist>
<targetlist> <targetportlist>
<operationlist>
counter,
countin, nocountin, countout, noucountout 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:
H - counter is resetted hourly
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>
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
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
<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 must be numeric. Unix only. Warning:
under some Linux kernels setuid() works onle for current
thread. It makes it impossible to suid for all threads.
setgid
<gid>
calls setgid(gid), gid must be numeric. Unix only.
chroot
<path>
calls chroot(path). Unix only.
stacksize
<value_to_add_to_default_stack_size>
Change default size for threads stack. May be required in
some situation,
e.g. with non-default plugins, on on some platforms (some
FreeBSD version
may require adjusting stack size due to invalid defined
value in system
header files, this value is also oftent reqruied 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 service to work. If you
experience
memory shortage, you can try to experiment with negative
values.
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
given value, no data filtering will be performed thorugh
filtering plugins to avoid data corruption and/or
Content-Length chaging. Default is 1MB (1048576).
Report all bugs to 3proxy@3proxy.ru
3proxy(8),
proxy(8), ftppr(8), socks(8), pop3p(8), tcppm(8), udppm(8),
syslogd(8),
http://3proxy.ru/
3APA3A is pronounced as ``zaraza´´.
3proxy is designed by Vladimir 3APA3A Dubrovin (3proxy@3proxy.ru)