13proxy.cfg(3) Universal proxy server 3proxy.cfg(3)
2
6 3proxy.cfg - 3proxy configuration file
7
9 Common structure:
10 Configuration file is a text file 3proxy reads configuration from. Each
11 line of the file is a command executed immediately, as it was given
12 from console. Sequence of commands is important. Configuration file as
13 actually a script for 3proxy executable. Each line of the file is
14 treated as a blank (space or tab) separated command line. Additional
15 space characters are ignored. Think about 3proxy as "application level
16 router" with console interface.
17 Comments:
18 Any string beginning with space character or ´#´ character is comment.
19 It´s ignored. <LF>s are ignored. <CR> is end of command.
20 Quotation:
22 Quotation character is " (double quote). Quotation must be used to
23 quote spaces or another special characters. To use quotation character
24 inside quotation character must be dubbed (BASIC convention). For exam‐
25 ple to use HELLO "WORLD" as an argument you should use it as "HELLO
26 ""WORLD""". Good practice is to quote any argument you use.
27 File inclusion:
28 You can include file by using $FILENAME macro (replace FILENAME with a
29 path to file, for example $/usr/local/etc/3proxy/conf.incl or
30 $"c:\Program Files\3proxy\include.cfg" Quotation is required in last
31 example because path contains space character. For included file <CR>
32 (end of line characters) is treated as space character (arguments
33 delimiter instead of end of command delimiter). Thus, include files
34 are only useful to store long signle-line commands (like userlist, net‐
35 work lists, etc). To use dollar sign somewhere in argument it must be
36 quoted. Recursion is not allowed.
37 Next commands start gateway services:
38 proxy [options]
39 socks [options]
40 pop3p [options]
41 ftppr [options]
42 admin [options]
43 dnspr [options]
44 tcppm [options] <SRCPORT> <DSTADDR> <DSTPORT>
45 udppm [options] <SRCPORT> <DSTADDR> <DSTPORT>
46 Descriptions:
47 proxy - HTTP/HTTPS proxy (default port 3128)
48 socks - SOCKS 4/4.5/5 proxy (default port 1080)
49 pop3p - POP3 proxy (default port 110)
50 ftppr - FTP proxy (default port 21)
51 admin - Web interface (default port 80)
52 dnspr - caching DNS proxy (default port 53)
53 tcppm - TCP portmapper
54 udppm - UDP portmapper
55 Options:
57 -pNUMBER change default server port to NUMBER
58 -n disable NTLM authentication (required if passwords are stored in
59 Unix crypt format.
60 -s (for admin) - allow only secure operations (currently only traffic
61 counters view without ability to reset).
62 -a (for proxy) - anonymous proxy (no information about client reported)
63 -a1 (for proxy) - anonymous proxy (random client information reported)
64 Also, all options mentioned for proxy(8) socks(8) pop3p(8) tcppm(8)
65 udppm(8) ftppr(8)
66 are also supported.
67 Portmapping services listen at SRCPORT and connect to DSTADDR:DSTPORT
68 HTTP and SOCKS proxies are standard.
69 POP3 proxy must be configured as POP3 server and requires username in
70 the form of: pop3username@pop3server. If POP3 proxy access must be
71 authenticated, you can specify username as proxy_username:proxy_pass‐
72 word:POP3_username@pop3server
73 DNS proxy resolves any types of records but only hostnames are cached.
74 It requires nserver/nscache to be configured.
75 FTP proxy can be used as FTP server in any FTP client or configured as
76 FTP proxy on a client with FTP proxy support. Username format is one of
77 FTPuser@FTPServer
78 FTPuser:FTPpassword@FTPserver
79 proxyuser:proxypassword:FTPuser:FTPpassword@FTPserver
80 Please note, if you use FTP client interface for FTP proxy do not add
81 FTPpassword and FTPServer to username, because FTP client does it for
82 you. That is, if you use 3proxy with authentication use proxyuser:prox‐
83 ypassword:FTPuser as FTP username, otherwise do not change original FTP
84 user name
85 include <path>
87 Include config file
88 config <path>
90 Path to configuration file to use on 3proxy restart or to save configu‐
91 ration.
92 writable
94 ReOpens configuration file for write access via Web interface, and re-
95 reads it. Usually should be first command on config file but in combi‐
96 nation with "config" it can be used anywhere to open alternate config
97 file. Think twice before using it.
98 end
100 End of configuration
101 log [[@|&]logfile] [<LOGTYPE>]
103 sets logfile for all gateways
104 @ - (for Unix) use syslog, filename is used as ident name
105 & - use ODBC, filename consists of comma-delimited datasource,user‐
106 name,password (username and password are optional)
107 LOGTYPE is one of:
108 M - Monthly
109 W - Weekly (starting from Sunday)
110 D - Daily
111 H - Hourly
112 if logfile is not specified logging goes to stdout. You can specify
113 individual logging options for gateway by using -l option in gateway
114 configuration.
115 "log" command supports same format specifications for filename template
116 as "logformat" (if filename contains '%' sign it's believed to be tem‐
117 plate). As with "logformat" filename must begin with 'L' or 'G' to
118 specify Local or Grinwitch time zone for all time-based format specifi‐
119 cators.
120 rotate <n> how many archived log files to keep
122 logformat <format>
124 Format for log record. First symbol in format must be L (local time) or
126 G (absolute Grinwitch time). It can be preceeded with -XXX+Y where XXX
127 is list of characters to be filtered in user input (any non-printable
128 characters are filtered too in this case) and Y is replacement charac‐
129 ter. For example, "-,%+ L" in the beginning of logformat means comma
130 and percent are replaced with space and all time based elemnts are in
131 local time zone.
132 You can use:
133 %y - Year in 2 digit format
135 %Y - Year in 4 digit format
136 %m - Month number
137 %o - Month abbriviature
138 %d - Day
139 %H - Hour
140 %M - Minute
141 %S - Second
142 %t - Timstamp (in seconds since 01-Jan-1970)
143 %. - milliseconds
144 %z - timeZone (from Grinvitch)
145 %D - request duration (in milliseconds)
146 %b - average send rate per request (in Bytes per second) this speed is
147 typically below connection speed shown by download manager.
148 %B - average receive rate per request (in Bytes per second) this speed
149 is typically below connection speed shown by download manager.
150 %U - Username
151 %N - service Name
152 %p - service Port
153 %E - Error code
154 %C - Client IP
155 %c - Client port
156 %R - Remote IP
157 %r - Remote port
158 %e - External IP used to establish connection
159 %Q - Requested IP
160 %q - Requested port
161 %n - requested hostname
162 %I - bytes In
163 %O - bytes Out
164 %h - Hops (redirections) count
165 %T - service specific Text
166 %N1-N2T - (N1 and N2 are positive numbers) - log only fields from N1
167 thorugh N2 of service specific text
168 in case of ODBC logging logformat specifies SQL statement, for exmam‐
169 ple:
170 logformat "-'+_Linsert into log (l_date, l_user, l_service, l_in,
171 l_out, l_descr) values ('%d-%m-%Y %H:%M:%S', '%U', '%N', %I, %O, '%T')"
172 logdump <in_traffic_limit> <out_traffic_limit>
174 Immediately creates additional log records if given amount of incom‐
175 ing/outgoing traffic is achieved for connection, without waiting for
176 connection to finish. It may be useful to prevent information about
177 long-lasting downloads on server shutdown.
178 archiver <ext> <commandline>
180 Archiver to use for log files. <ext> is file extension produced by
181 archiver. Filename will be last argument to archiver, optionally you
182 can use %A as produced archive name and %F as filename.
183 timeouts <BYTE_SHORT> <BYTE_LONG> <STRING_SHORT> <STRING_LONG> <CONNEC‐
185 TION_SHORT> <CONNECTION_LONG> <DNS> <CHAIN>
186 Sets timeout values
187 BYTE_SHORT - short timeout for single byte, is usually used for
188 receiving single byte from stream.
189 BYTE_LONG - long timeout for single byte, is usually used for receiv‐
190 ing first byte in frame (for example first byte in socks request).
191 STRING_SHORT - short timeout, for character string within stream (for
192 example to wait between 2 HTTP headers)
193 STRING_LONG - long timeout, for first string in stream (for example to
194 wait for HTTP request).
195 CONNECTION_SHORT - inactivity timeout for short connections (HTTP,
196 POP3, etc).
197 CONNECTION_LONG - inactivity timeout for long connection (SOCKS,
198 portmappers, etc).
199 DNS - timeout for DNS request before requesting next server
200 CHAIN - timeout for reading data from chained connection
201 nserver
203 <ipaddr>
204 Nameserver to use for name resolutions. If none spcified system or name
205 server fails system routines for name resolution will be used. It's
206 better to specify nserver because gethostbyname() may be thread unsafe.
207 nscache <cachesize>
209 Cache <cachesize> records for name resolution. Cachesize usually should
211 be large enougth (for example 65536).
212 nsrecord <hostname> <hostaddr> Adds static record to nscache. nscache
214 must be enabled. If 0.0.0.0 is used as a hostaddr host will never
215 resolve, it can be used to blacklist something or together with dialer
216 command to set up UDL for dialing.
217 fakeresolve All names are resolved to 127.0.0.2 address. Usefull if
219 all requests are redirected to parent proxy with http, socks4+, con‐
220 nect+ or socks5+.
221 dialer <progname>
223 Execute progname if external name can't be resolved. Hint: if you use
224 nscache, dialer may not work, because names will be resolved through
225 cache. In this case you can use something like http://dial.right.now/
226 from browser to set up connection.
227 internal <ipaddr>
230 sets ip address of internal interface. This IP address will be used to
231 bind gateways. Alternatively you can use -i option for individual gate‐
232 ways
233 external <ipaddr>
235 sets ip address of external interface. This IP address will be source
236 address for all connections made by proxy. Alternatively you can use -e
237 option to specify individual address for gateway.
238 maxconn <number>
240 sets maximum number of simulationeous connections to each services
241 started after this command. Default is 100.
242 service
244 (depricated). Indicates 3proxy to behave as Windows 95/98/NT/2000/XP
245 service, no effect for Unix. Not required for 3proxy 0.6 and above. If
246 you upgraded from previous version of 3proxy use --remove and --install
247 to reinstall service.
248 daemon
250 Should be specified to close console. Do not use 'daemon' with 'ser‐
251 vice'. At least under FreeBSD 'daemon' should preceed any proxy ser‐
252 vice and log commands to avoid sockets problem. Always place it in the
253 beginning of the configuration file.
254 auth <authtype> [...]
256 Type of user authorization. Currently supported:
257 none - no authentication or authorization required.
258 Note: is auth is none any ip based limitation, redirection, etc will
259 not work.
260 This is default authentication type
261 iponly - authentication by access control list with username ignored.
262 Appropriate for most cases
263 username - authentication by username without checking for any pass‐
264 word with authorization by ACLs. Usefule for e.g. SOCKSv4 proxy.
265 nbname - authentication by NetBIOS name with authorization by ACLs.
266 Messanger service should be started on user's machine. Note, that Win‐
267 dows 95/98 hosts do not have messanger service by default, WinPopup
268 program need to be started. NB: there is no any password check, name
269 may be spoofed. Think about it as about ident for Windows.
270 Q: Will ident authorization be implemented?
271 A: Yes, as soon as it will be required by someone.
272 strong - username/password authentication required. It will work with
273 SOCKSv5, FTP, POP3 and HTTP proxy.
274 cache - cached authentication, may be used with 'authcache'.
275 Plugins may add additional authentication types.
276 It's possible to use few authentication types in the same commands.
278 E.g.
279 auth iponly strong
280 In this case 'strong' authentication will be used only in case resource
281 access can not be performed with 'iponly' authentication, that is user‐
282 name is required in ACL. It's usefull to protect access to some
283 resources with password allowing passwordless access to another
284 resources, or to use IP-based authentication for dedicated laptops and
285 request username/password for shared ones.
286 authcache <cachtype> <cachtime>
287 Cache authentication information to given amount of time (cachetime) in
288 seconds. Cahtype is one of:
289 ip - after successful authentication all connections during caching
290 time from same IP are assigned to the same user, username is not
291 requested.
292 ip,user username is requested and all connections from the same IP are
293 assigned to the same user without actual authentication.
294 user - same as above, but IP is not checked.
295 user,password - both username and password are checked against cached
296 ones.
297 Use auth type 'cache' for cached authentication
298 allow <userlist> <sourcelist> <targetlist> <targetportlist> <opera‐
299 tionlist> <weekdayslist> <timeperiodslist>
300 deny <userlist> <sourcelist> <targetlist> <targetportlist> <opera‐
301 tionlist> <weekdayslist> <timeperiodslist>
302 Access control entries. All lists are comma-separated, no spaces are
303 allowed. Usernames are case sensitive (if used with authtype nbname
304 username must be in uppercase). Source and target lists may contain IP
305 addresses (W.X.Y.Z) or CIDRs (W.X.Y.Z/L). Since 0.6, targetlist may
306 also contain host names, instead of addresses. It's possible to use
307 wildmask in the begginning and in the the end of hostname, e.g. *bad‐
308 site.com or *badcontent*. Hostname is only checked if hostname presents
309 in request. Targetportlist may contain ports (X) or port ranges lists
310 (X-Y). For any field * sign means "ANY" If access list is empty it's
311 assumed to be
312 allow *
313 If access list is not empty last item in access list is assumed to be
314 deny *
315 You may want explicitly add "deny *" to the end of access list to pre‐
316 vent HTTP proxy from requesting user's password. Access lists are
317 checked after user have requested any resource. If you want 3proxy to
318 reject connections from specific addresses immediately without any con‐
319 ditions you should either bind proxy to appropriate interface only or
320 to use ip filters.
321 Operation is one of:
323 CONNECT - establish outgoing TCP connection
324 BIND - bind TCP port for listening
325 UDPASSOC - make UDP association
326 ICMPASSOC - make ICMP association (for future use)
327 HTTP_GET - HTTP GET request
328 HTTP_PUT - HTTP PUT request
329 HTTP_POST - HTTP POST request
330 HTTP_HEAD - HTTP HEAD request
331 HTTP_CONNECT - HTTP CONNECT request
332 HTTP_OTHER - over HTTP request
333 HTTP - matches any HTTP request except HTTP_CONNECT
334 HTTPS - same as HTTP_CONNECT
335 FTP_GET - FTP get request
336 FTP_PUT - FTP put request
337 FTP_LIST - FTP list request
338 FTP_DATA - FTP data connection. Note: FTP_DATA requires access to
339 dynamic
340 non-ptivileged (1024-65535) ports on remote side.
341 FTP - matches any FTP/FTP Data request
342 ADMIN - access to administration interface
343 Weeksdays are week days numbers or periods (0 or 7 means Sunday, 1 is
345 Monday, 1-5 means Monday through Friday). Timeperiodlists is a list of
346 time periods in HH:MM:SS-HH:MM:SS format. For example,
347 00:00:00-08:00:00,17:00:00-24:00:00 lists non-working hours.
348 parent <weight> <type> <ip> <port> <username> <password>
349 this command must follow "allow" rule. It extends last allow rule to
350 build proxy chain. Proxies may be grouped. Proxy inside the group is
351 selected randomly. If few groups are specified one proxy is randomly
352 picked from each group and chain of proxies is created (that is second
353 proxy connected through first one and so on). Weight is used to group
354 proxies. Weigt is a number between 1 and 1000. Weights are summed and
355 proxies are grouped together untill weight of group is 1000. That is:
356 allow *
357 parent 500 socks5 192.168.10.1 1080
358 parent 500 connect 192.168.10.1 3128
359 makes 3proxy to randomly choose between 2 proxies for all outgoing
360 connections. These 2 proxies form 1 group (summarized weight is 1000).
361 allow * * * 80
362 parent 1000 socks5 192.168.10.1 1080
363 parent 1000 connect 192.168.20.1 3128
364 parent 300 socks4 192.168.30.1 1080
365 parent 700 socks5 192.168.40.1 1080
366 creates chain of 3 proxies: 192.168.10.1, 192.168.20.1 and third is
367 (192.168.30.1 with probability of 0.3 or 192.168.40.1 with probability
368 of 0.7) for outgoing web connections.
369 type is one of:
371 tcp - simply redirect connection. TCP is always last in chain.
372 http - redirect to HTTP proxy. HTTP is always last chain.
373 pop3 - redirect to POP3 proxy (only local redirection is supported,
374 can not be used for chaining)
375 ftp - redirect to FTP proxy (only local redirection is supported, can
376 not be used for chaining)
377 connect - parent is HTTP CONNECT method proxy
378 connect+ - parent is HTTP CONNECT proxy with name resolution
379 socks4 - parent is SOCKSv4 proxy
380 socks4+ - parent is SOCKSv4 proxy with name resolution (SOCKSv4a)
381 socks5 - parent is SOCKSv5 proxy
382 socks5+ - parent is SOCKSv5 proxy with name resolution
383 socks4b - parent is SOCKS4b (broken SOCKSv4 implementation with short‐
384 ened server reply. I never saw this kind ofservers byt they say there
385 are). Normally you should not use this option. Do not mess this option
386 with SOCKSv4a (socks4+).
387 socks5b - parent is SOCKS5b (broken SOCKSv5 implementation with short‐
388 ened server reply. I think you will never find it useful). Never use
389 this option unless you know exactly you need it.
390 admin - redirect request to local 'admin' service (with -s parameter).
391 Use "+" proxy only with "fakeresolve" option
392 IP and port are ip addres and port of parent proxy server. If IP is
394 zero, ip is taken from original request, only port is changed. If port
395 is zero, it's taken from original request, only IP is changed. If both
396 IP and port are zero - it's a special case of local redirection, it
397 works only with socks proxy. In case of local redirection request is
398 redirected to different service, ftp locally redirects to ftppr pop3
399 locally redirects to pop3p http locally redurects to proxy admin
400 locally redirects to admin -s service.
401 Main purpose of local redirections is to have requested resource (URL
403 or POP3 username) logged and protocol-specific filters to be applied.
404 In case of local redirection ACLs are revied twice: first, by SOCKS
405 proxy up to redirected (HTTP, FTP or POP3) after 'parent' command. It
406 means, additional 'allow' command is required for redirected requests,
407 for example:
408 allow * * * 80
409 parent 1000 http 0.0.0.0 0
410 allow * * * 80 HTTP_GET,HTTP_POST
411 socks
412 redirects all SOCKS requests with target port 80 to local HTTP proxy,
413 local HTTP proxy parses requests and allows only GET and POST requests.
414 parent 1000 http 1.2.3.4 0
415 Changes external address for given connection to 1.2.3.4 (an equivalent
416 to -e1.2.3.4)
417 Optional username and password are used to authenticate on parent
419 proxy. Username of '*' means username must be supplied by user.
420 nolog <n> extends last allow or deny command to prevent logging, e.g.
423 allow * * 192.168.1.1
424 nolog
425 weight <n> extends last allow or deny command to set weight for this
428 request
429 allow * * 192.168.1.1
430 weight 100
431 Weight may be used for different purposes.
432 bandlimin <rate> <userlist> <sourcelist> <targetlist> <targetportlist>
434 <operationlist>
435 nobandlimin <userlist> <sourcelist> <targetlist> <targetportlist>
436 <operationlist> bandlimout <rate> <userlist> <sourcelist> <targetlist>
437 <targetportlist> <operationlist>
438 nobandlimout <userlist> <sourcelist> <targetlist> <targetportlist>
439 <operationlist>
440 bandlim sets bandwith limitation filter to <rate> bps (bits per sec‐
441 ond) (if you want to specife bytes per second - multiply your value to
442 8). bandlim rules act in a same manner as allow/deny rules except one
443 thing: bandwidth limiting is applied to all services, not to some spe‐
444 cific service. bandlimin and nobandlimin applies to incoming traffic
445 bandlimout and nobandlimout applies to outgoing traffic If tou want to
446 ratelimit your clients with ip's 192.168.10.16/30 (4 addresses) to
447 57600 bps you have to specify 4 rules like
448 bandlimin 57600 * 192.168.10.16
449 bandlimin 57600 * 192.168.10.17
450 bandlimin 57600 * 192.168.10.18
451 bandlimin 57600 * 192.168.10.19
452 and every of you clients will have 56K channel. if you specify
453 bandlimin 57600 * 192.168.10.16/30
454 you will have 56K channel shared between all clients. if you want,
455 for example, to limit all speed ecept access to POP3 you can use
456 nobandlimin * * * 110
457 before the rest of bandlim rules.
458 counter <filename> <reporttype> <repotname>
460 countin <number> <type> <limit> <userlist> <sourcelist> <targetlist>
461 <targetportlist> <operationlist>
462 nocountin <userlist> <sourcelist> <targetlist> <targetportlist> <opera‐
463 tionlist>
464 countout <number> <type> <limit> <userlist> <sourcelist> <targetlist>
465 <targetportlist> <operationlist>
466 nocountout <userlist> <sourcelist> <targetlist> <targetportlist> <oper‐
467 ationlist>
468 counter, countin, nocountin, countout, noucountout commands are used
470 to set traffic limit in MB for period of time (day, week or month).
471 Filename is a path to a special file where traffic information is per‐
472 manently stored. number is sequential number of record in this file.
473 If number is 0 no traffic information on this counter is saved in file
474 (that is if proxy restarted all information is loosed) overwise it
475 should be unique sequential number. Type specifies a type of counter.
476 Type is one of:
477 D - counter is resetted daily
478 W - counter is resetted weekly
479 M - counter is resetted monthely
480 reporttype/repotname may be used to generate traffic reports. Report‐
481 type is one of D,W,M,H(hourly) and repotname specifies filename tem‐
482 plate for reports. Report is text file with counter values in format:
483 <COUNTERNUMBER> <TRAF*4GB> <TRAF>
484 The rest of parameters is identical to bandlim/nobandlim.
485 users username[:pwtype:password] ...
487 pwtype is one of:
488 none (empty) - use system authentication
489 CL - password is cleartext
490 CR - password is crypt-style password
491 NT - password is NT password (in hex)
492 example:
493 users test1:CL:password1 "test2:CR:$1$lFDGlder$pLRb4cU2D7GAT58YQvY49."
494 users test3:NT:BD7DFBF29A93F93C63CB84790DA00E63
495 (note: double quotes are requiered because password contains $ sign).
496 flush
498 empty active access list. Access list must be flushed avery time you
499 creating new access list for new service. For example:
500 allow *
501 pop3p
502 flush
503 allow * 192.168.1.0/24
504 socks
505 sets different ACLs for pop3p and socks
506 system
508 execute system command
509 pidfile <filename>
511 write pid of current process to file. It can be used to manipulate
512 3proxy with signals under Unix. Currently next signals are available:
513 monitor <filename>
515 If file monitored changes in modification time or size, 3proxy reloads
516 configuration within one minute. Any number of files may be monitored.
517 setuid <uid>
519 calls setuid(uid), uid must be numeric. Unix only. Warning: under some
520 Linux kernels setuid() works onle for current thread. It makes it
521 impossible to suid for all threads.
522 setgid <gid>
524 calls setgid(gid), gid must be numeric. Unix only.
525 chroot <path>
527 calls chroot(path). Unix only.
528
530 plugin <path_to_shared_library> <function_to_call> [<arg1> ...]
531 Loads specified library and calls given export function with given
532 arguments, as
533 int functions_to_call(struct pluginlink * pl, int argc, char * argv[]);
534 function_to_call must return 0 in case of success, value > 0 to indi‐
535 cate error.
536 filtermaxsize <max_size_of_data_to_filter>
538 If Content-length (or another data length) is greater than given value,
539 no data filtering will be performed thorugh filtering plugins to avoid
540 data corruption and/or Content-Length chaging. Default is 1MB
541 (1048576).
542
546 3proxy(8), proxy(8), ftppr(8), socks(8), pop3p(8), tcppm(8), udppm(8),
547 syslogd(8),
548 http://3proxy.ru/
549
551 3APA3A is pronounced as ``zaraza´´.
552
554 3proxy is designed by 3APA3A (3APA3A@security.nnov.ru), Vladimir
555 Dubrovin (vlad@sandy.ru)
5563proxy 0.6 July 2009 3proxy.cfg(3)