3proxy.cfg(8)

📦
version 0.9.5 · 2 versions
, in opensuse-leap 16.0

🌸 NAME 🌸

3proxy.cfg — 3proxy configuration file. Also, hi bestie, this is the 3proxy.cfg(8) page from the Universal proxy server manual, and it's literally all about how to write your config file. 💖

💖 DESCRIPTION 💖

🧠 Common structure

Okay so picture this: the config file is just a plain text file that 3proxy reads its configuration from. Every single line is a command that gets executed immediately, exactly like you typed it into the console. The order of commands matters — sequence is important, no cap. The config file is actually a script for the 3proxy executable.

Each line is treated as a blank-separated command line — blank meaning space or tab. Extra space characters are ignored. Think of 3proxy as an "application level router" with a console interface. It's giving main-character router energy. 🦋

💬 Comments

Any string beginning with a space character or a # 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, bestie. Quotation must be used to quote spaces or other special characters. To use the quotation character inside quotation, it has to be doubled up (BASIC convention). For example, to use HELLO "WORLD" as an argument, you write it as:

"HELLO ""WORLD"""

Good practice is to quote any argument you use. Slay, honestly. ✨

📁 File inclusion

You can include a file by using the $FILENAME macro — replace FILENAME with a path to the file, for example $/usr/local/etc/3proxy/conf.incl or $"c:\\Program Files\3proxy\include.cfg". Quotation is required in that last example because the path contains a space character.

For an included file, <CR> — the end-of-line characters — is treated as a space character. That means it becomes an arguments delimiter instead of an end-of-command delimiter. So include files are only useful for storing long single-line commands (like userlist, network lists, etc.). To use a dollar sign somewhere in an argument, it must be quoted. Recursion is not allowed. Periodt. 🚫

🚪 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)
  • tlspr — SNI proxy (destination address is taken from the 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)
  • smtpp — SMTP proxy (default port 25)
  • 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.
  • -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 single directions 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 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-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.
  • -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 like TCP_CORK, TCP_NODELAY, TCP_DEFER_ACCEPT, TCP_QUICKACK, TCP_TIMESTAMPS, USE_TCP_FASTOPEN, SO_REUSEADDR, SO_REUSEPORT, SO_PORT_SCALABILITY, SO_REUSE_UNICASTPORT, SO_KEEPALIVE, SO_DONTROUTE may be supported depending on OS.
  • -DiINTERFACE, -DeINTERFACE — bind internal interface / external interface to given INTERFACE (e.g. eth0) if SO_BINDTODEVICE is supported by the system. You may need to run as root or to have CAP_NET_RAW capability in order to bind to an interface, depending on 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).
  • -e — External address. IP address of interface proxy should initiate connections from. External IP must be specified if you need incoming connections. By default system will decide which address to use in accordance with routing table.
  • -i — Internal address. IP address proxy accepts connections to. By default connection to any interface is accepted.
  • -N — (for socks) External NAT address 3proxy reports to client for BIND and UDPASSOC. By default external address is reported. It's only useful in the case of IP-IP NAT (will not work for PAT)

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 rereads it. Usually should be first command on config file, but in combination with config it can be used anywhere to open an 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)
  • radius — use RADIUS for logging

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 a gateway by using the -l option in gateway configuration.

The log command supports the same format specifications for filename template as logformat (if filename contains a % sign, it's believed to be a 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 preceded with -XXX+Y where XXX is a list of characters to be filtered in user input (any non-printable characters are filtered too in this case) and Y is the replacement character. For example, "-,%+ L" in the beginning of logformat means comma and percent are replaced with space, and all time-based elements 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 — 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 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 the given amount of incoming/outgoing traffic is achieved for a connection, without waiting for the 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 the file extension produced by the archiver. Filename will be the last argument to the archiver; optionally you can use %A as produced archive name and %F as filename.

⏱️ timeouts

timeouts <BYTE_SHORT> <BYTE_LONG> <STRING_SHORT> <STRING_LONG> <CONNECTION_SHORT> <CONNECTION_LONG> <DNS> <CHAIN> <CONNECT> <CONNECTBACK>

okay so this is the timeout command and it sets, you guessed it, timeout values ✨ the defaults are 1, 5, 30, 60, 180, 1800, 15, 60, 15, 5 — yes bestie that's ten numbers, they go in order, don't freak out 💅

  • BYTE_SHORT — short timeout for a single byte. Usually this is what you're using when you're receiving one single byte out of a stream.
  • BYTE_LONG — long timeout for a single byte. This one's for grabbing the first byte in a frame — like, the first byte of a socks request, that kind of situation.
  • STRING_SHORT — short timeout, but for a character string inside the stream. Think waiting between 2 HTTP headers 🎀
  • STRING_LONG — long timeout, for the first string in the stream — e.g. waiting for an HTTP request to show up.
  • CONNECTION_SHORT — inactivity timeout for short connections (HTTP, POP3, etc.).
  • CONNECTION_LONG — inactivity timeout for long connections (SOCKS, portmappers, etc.).
  • DNS — timeout for a DNS request before it goes and asks the next server.
  • CHAIN — timeout for reading data from a chained connection.
  • CONNECT — the connect timeout.
  • CONNECTBACK — the connect-back timeout.

and just so it's crystal clear, the defaults one more time for the people in the back:

default timeouts 1 5 30 60 180 1800 15 60 15 5

🔮 radius

radius <NAS_SECRET> <radius_server_1[:port][/local_address_1]> <radius_server_2[:port][/local_address_2]>

sets up the RADIUS servers you wanna use for logging and authentication — and heads up, your log and auth types both gotta be set to radius for this to do anything 🫶 you can also tack on a port and a local address for each server if you're feeling fancy.

Attributes that go out in the request: User-Name, Password: (username and password, if the client actually presented them), Service Type: Authenticate-Only, NAS-Port-Type: NAS-Port-Virtual, NAS-Port-ID: (the proxy service port, e.g. 1080), NAS-IPv6-Address / NAS-IP-Address: (the proxy interface the client accessed), NAS-Identifier: (text identifying the proxy, e.g. PROXY or SOCKSv5), Framed-IPv6-Address / Framed-IP-Address: (the client's IP address), Called-Station-ID: (requested Hostname, if it's there), 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).

Reply attributes supported for authentication: Framed-IP-Address / Framed-IPv6-Address (the IP to assign to the user) and Reply-Message. Use authcache to speed up authentication. RADIUS feature is currently experimental — you've been warned, don't come for me 😭

🌐 nserver

nserver <ipaddr>[:port][/tcp]

the nameserver to use for name resolutions. If you don't specify any, the system routines for name resolution get used instead. Optional port number? allowed 💅 and if you slap /tcp onto the IP address, name resolution happens over TCP.

🗄️ nscache / nscache6

nscache <cachesize> nscache6 <cachesize>

caches <cachesize> records for name resolution — nscache for IPv4, nscache6 for IPv6 🌈 and honestly your cachesize should usually be big (like, 65536 big) — small cache is giving poverty.

📌 nsrecord

nsrecord <hostname> <hostaddr>

drops a static record into nscache, so nscache must be enabled first, no exceptions. If you use 0.0.0.0 as the hostaddr, that host will never ever resolve — which is lowkey iconic for blacklisting something, or you can pair it with the dialer command to set up UDL for dialing 🦋

🪄 fakeresolve

all names get resolved to the 127.0.0.2 address. Useful when every single request is being redirected to a parent proxy with http, socks4+, connect+ or socks5+.

☎️ dialer

dialer <progname>

runs progname if an external name can't be resolved. Hint (and this is a real one): if you're using nscache, dialer may not work, because the names get resolved through the cache. In that case you can do something like hitting http://dial.right.now/ from a browser to set up the connection 🌸

🏠 internal

internal <ipaddr>

sets the IP address of the internal interface. This IP gets used to bind gateways. Alternatively you can use the -i option for individual gateways. Since 0.8 version, an IPv6 address may be used 👑

🌍 external

external <ipaddr>

sets the IP address of the external interface. This IP becomes the source address for every connection the proxy makes. Alternatively there's the -e option to specify an individual address for a gateway. Since 0.8 version, External or -e can be given twice: once with an IPv4 and once with an IPv6 address ✨

👯 maxconn

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 — and this difference actually matters: maxconn will silently ignore new connections, while connlim actually reports 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 the kernel tunable somaxconn — so if you're trying to go huge, the kernel said no 🫶

🪟 service

(depricated). Tells 3proxy to behave as a Windows 95/98/NT/2000/XP service — no effect for 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 preceed any proxy service and log commands to avoid sockets problems. Always place it at the beginning of the configuration file — like, literally the first thing, bestie.

🔐 auth

auth <authtype> [...]

the 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 and icqpr (icqpr sets UIN / AOL screen name as a username).
  • dnsname — authentication by DNS hostnname with authorization by ACLs. The DNS hostname is resolved via PTR (reverse) record and validated (the resolved name must resolve back to the 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.
  • radius — authentication with RADIUS.
  • plugins may add additional authentication types.

It's possible to use a few authentication types in the same command. E.g.

auth iponly strong

In this case strong authentication will be used only when resource access can not be performed with iponly authentication — that is, the username is required in the ACL. It's usefull 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 username/password for the shared ones 💜

🧠 authcache

authcache <cachtype> <cachtime>

caches authentication info for a given amount of time (cachtime), in seconds. Cahtype is one of:

  • ip — after successful authentication, all connections during caching time from the 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 the cached ones.
  • limit — limit the user to using only one ip; ip and user are required.
  • acl — only use cached auth if the user accesses the service with the same ACL.
  • ext — cache external IP.

Use auth type cache for cached authentication ⭐

🚦 allow / deny

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 allowed, sorry. Usernames are case sensitive (if used with authtype nbname, the 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 a wildmask at the begginning and at the the end of a hostname, e.g. *badsite.com or *badcontent* 🦋 — hostname is only checked if hostname presents in the request. Targetportlist may contain ports (X) or port range lists (X-Y). For any field, * sign means ANY. If the access list is empty, it's assumed to be

allow *

If the access list is not empty, the last item in the access list is assumed to be

deny *

You may want to explicitly add deny * to the end of the access list to prevent the HTTP proxy from requesting the user's password 👀 Access lists are checked after the user has requested any resource. If you want 3proxy to reject connections from specific addresses immediately, with no conditions at all, you should either bind the proxy to the appropriate interface only or 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 the remote side 😭
  • FTP — matches any FTP/FTP Data request
  • ADMIN — access to administration interface

Weeksdays 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 🌙

okay so the parent command is where things get spicy — and by spicy I mean proxy-chain construction, bestie. 💅

parent <weight> <type> <ip> <port> <username> <password>

This one has to follow an allow rule, no cap. It extends the last allow rule so you can build a proxy chain. Proxies can be grouped, and a proxy inside the group is picked randomly. If you specify a few groups, one proxy is randomly picked from each group and a chain of proxies is created — that means the second proxy connects through the first one, and so on. weight is what groups the proxies together. weight is a number between 1 and 1000. Weights get summed, and proxies are grouped together until the group’s weight is 1000.

Like, check this:

allow *
parent 500 socks5 192.168.10.1 1080
parent 500 connect 192.168.10.1 3128

That makes 3proxy randomly choose between 2 proxies for all outgoing connections. These 2 proxies form 1 group (summarized weight is 1000). Slay.

And this one:

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 a chain of 3 proxies: 192.168.10.1, 192.168.20.1, and the 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. Periodt.

type is one of these, bestie:

  • 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 external IP based on ACL or make it random.
  • tcp — simply redirects the connection. TCP is always last in the chain. This type of proxy is a simple TCP redirection, and it does not support parent authentication.
  • http — redirects to an HTTP proxy. HTTP is always the last chain. It should only be used with the http (proxy) service; if you use it with a different service, it works as tcp redirection.
  • pop3 — redirects to a POP3 proxy (only local redirection is supported, and it can only be used as a first hop in chaining).
  • ftp — redirects to an FTP proxy (only local redirection is supported, and it can only be used as a first hop in chaining).
  • connect — parent is an HTTP CONNECT method proxy.
  • connect+ — parent is an HTTP CONNECT proxy with name resolution (hostname is used instead of IP if available).
  • socks4 — parent is a SOCKSv4 proxy.
  • socks4+ — parent is a SOCKSv4 proxy with name resolution (SOCKSv4a).
  • socks5 — parent is a SOCKSv5 proxy.
  • socks5+ — parent is a SOCKSv5 proxy with name resolution.
  • socks4b — parent is a SOCKS4b (broken SOCKSv4 implementation with shortened server reply. I never saw this kind of servers but they say there are). Normally you should not use this option. Do not mess this option with SOCKSv4a (socks4+).
  • socks5b — parent is a 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 — redirects the request to the local admin service (with the -s parameter).

Use "+" proxy only with the "fakeresolve" option.

IP and port are the IP address and port of the parent proxy server. If IP is zero, the IP is taken from the original request, and only the port is changed. If port is zero, it’s taken from the original request, and only the IP is changed. If both IP and port are zero — that’s a special case of local redirection, and it works only with the socks proxy. In the case of local redirection, the request is redirected to a different service:

  • ftp locally redirects to ftppr
  • pop3 locally redirects to pop3p
  • http locally redirects to proxy
  • admin locally redirects to the admin -s service

The main purpose of local redirections is to have the requested resource (URL or POP3 username) logged and protocol-specific filters applied. In the case of local redirection, ACLs are reviewed twice: first by the SOCKS proxy up to the parent command, and then with the gateway service the connection is redirected to (HTTP, FTP, or POP3) after the parent command. That means an additional allow command is required for redirected requests, like this:

allow * * * 80
parent 1000 http 0.0.0.0 0
allow * * * 80 HTTP_GET,HTTP_POST
socks

That redirects all SOCKS requests with target port 80 to the local HTTP proxy, and the local HTTP proxy parses requests and allows only GET and POST requests. Iconic.

parent 1000 http 1.2.3.4 0

changes the external address for the given connection to 1.2.3.4 (an equivalent to -e1.2.3.4).

Optional username and password are used to authenticate on the parent proxy. A username of * means the username must be supplied by the user. 🫶

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

allow * * 192.168.1.1
nolog

weight <n> — extends the 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 a service, configuration reload will require all current sessions of this service to be re-authenticated. If the ACL is changed or a user account is removed, old connections which do not match current are closed. noforce allows you to keep previously authenticated connections.

Here come the bandwidth-limiter besties:

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 every one 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 the bandlim rules. 💖

Now for connection limits:

connlim <rate> <period> <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>
noconnlim <userlist> <sourcelist> <targetlist> <targetportlist> <operationlist> <weekdayslist> <timeperiodslist>

connlim sets a connections rate limit per time period for the traffic pattern controlled by ACL. period is in seconds. If period is 0, connlim limits the 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. 🦋

Traffic counters, assemble:

counter <filename> <reporttype> <repotname>
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, and 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. number is the sequential number of the record in this file. If 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 the 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/repotname may be used to generate traffic reports. reporttype is one of D,W,M,H(hourly), and repotname specifies the filename template for reports. A report is a text file with counter values in this format:

<COUNTERNUMBER> <TRAF>

The rest of the parameters are identical to bandlim/nobandlim. 🎀

Users, bestie:

users username[:pwtype:password] ...

pwtype is one of:

  • none (empty) — use system authentication
  • CL — password is cleartext
  • CR — password is crypt-style password
  • NT — password is NT password (in hex)

Example:

users test1:CL:password1 "test2:CR:$1$lFDGlder$pLRb4cU2D7GAT58YQvY49."
users test3:NT:BD7DFBF29A93F93C63CB84790DA00E63
Note: double quotes are required because the password contains a $ sign.

flush — empties 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 a system command.

pidfile <filename> — write the pid of the current process to a file. It can be used to manipulate 3proxy with signals under Unix. Currently next signals are available: (and then the page just moves on — no list here, bestie 😭).

monitor <filename> — if the monitored file 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, a username. Unix only.

Warning: under some Linux kernels setuid() works for the current thread only. It makes it impossible to setuid for all threads. 💀

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

chroot <path> [<uid>] [<gid>] — calls chroot(path) and sets gid/uid. Unix only. uid/gid supported since 0.9, and can be numeric or username/groupname. 🌈

  • stacksize <value_to_add_to_default_stack_size> — okay so this changes the default size for the threads stack. It may be required in some situations, like with non-default plugins, or on some platforms: some FreeBSD versions may require adjusting stack size because of an invalid defined value in system header files, and 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 setting 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 experimenting with negative values. 🧵

🧩 PLUGINS 🧩

  • plugin <path_to_shared_library> <function_to_call> [<arg1> ...] — loads the specified library and calls the given export function with the given arguments, like this:
int functions_to_call(struct pluginlink * pl, int argc, char * argv[]);

function_to_call must return 0 in case of success, and a value > 0 to indicate an 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). 🛡️

🐛 BUGS 🐛

Report all bugs to 3proxy@3proxy.org. fr fr, they want to know. 💌

👀 SEE ALSO 👀

Go peek at these, bestie:

🎀 TRIVIA 🎀

3APA3A is pronounced as zaraza. iykyk 😌

👑 AUTHORS 👑

3proxy is designed by Vladimir 3APA3A Dubrovin (3proxy@3proxy.org). iconic behavior, honestly. 🫶

💖 That’s the whole page, bestie. Source/version: 3proxy 0.9; date: January 2019; page: 3proxy.cfg(8). Mwah. 🎀

📦 where this page comes from