3proxy.cfg(5)

📦
version 1.0.1 · 3 versions
, in epel 10, epel 9, fedora 43, fedora 44

✨ 3proxy.cfg(5) — Universal proxy server ✨

💖 NAME 💖

3proxy.cfg — 3proxy configuration file

🌸 DESCRIPTION 🌸

🦋 Common structure 🦋

okay bestie, so picture this: the config file is just a text file that 3proxy reads all its configuration from. Every single line? Executed immediately, exactly like you typed it straight into the console. So the order of commands is so important — it's giving script energy. The config file is literally a script for the 3proxy executable. Each line is treated as a blank (space or tab) separated command line. Extra space characters? Ignored, periodt. Think about 3proxy as an "application level router" with a console interface. main character energy fr fr 💅

💬 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. no cap 💖

📂 File inclusion 📂

You can include a file by using the $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 the last example because the path contains a space character. For an included file, <CR> (end of line characters) is treated as a 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 a dollar sign somewhere in an 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 🚀

htproxy [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 📝

  • htproxy — 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 ✨

okay bestie, here's the tea on all the flags you can give 3proxy. it's giving config file realness 💅 let's go!

  • -pNUMBER — change default server port to NUMBER. easy peasy.
  • -6 — Only resolve IPv6 addresses. IPv4 addresses are packed in IPv6 in IPV6_V6ONLY compatible way. slay.
  • -4 — Only resolve IPv4 addresses. This is the default: a service reaches an IPv6 address only when told to with -6, -46 or -64. the default, periodt.
  • -46 — Prefer IPv4. Resolve IPv6 addresses if IPv4 address is not resolvable. flexible much?
  • -64 — Prefer IPv6. Resolve IPv4 addresses if IPv6 address is not resolvable. ipv6 girlies rise.
  • -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. routing table said gay rights.
  • -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. unix domain sockets are iconic.
  • -DiINTERFACE, -DeINTERFACE — bind internal (-Di) / external (-De) interface to given INTERFACE (e.g. eth0) if SO_BINDTODEVICE is supported by the system.
careful bestie! 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).
warning! 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). nat said what?
  • -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). udp girlies know.
  • -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. connect back realness.
  • -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. the other side of the coin.
  • -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, 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 on the listening socket by default on Unix. 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. socket options are a whole vibe.
  • -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. haproxy stans rise.
  • -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. minimize that polling energy.
  • -s —
    • (for admin) secure, allow only secure operations, currently only traffic counters view without ability to reset. secure the bag.
    • (for TCP services, Linux) enable splice().
note! splice() is not built by default and is disabled even when built, because current Linux does not implement SPLICE_F_MOVE, so no real zero-copy takes place and the read/write path is faster for most traffic. Rebuild with -DWITHSPLICE to make -s available, -s0 disables it explicitly. 💀
  • -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).
warning! 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. udp association drama.
    • (for dnspr) simple, do not use resolver and 3proxy cache, always use external DNS server. dnspr said no cache.
    • (for udppm) singlepacket, expect only one packet from both client and server. single packet energy.
  • -u — Never ask for username/password. no auth, no problem.
  • -u2 (for socks) — require username/password in authentication methods. auth required, bestie.
  • -a (for proxy) — anonymous proxy (no information about client reported). anonymous icon.
  • -a1 (for proxy) — anonymous proxy (random client information reported). randomize that info.
  • -a2 (for proxy) — generate Via: and X-Forwarded-For: instead of Forwarded:. header drama.

Also, all options mentioned for htproxy(8) socks(8) pop3p(8) imapp(8) tcppm(8) udppm(8) ftppr(8) are also supported. the whole squad is here 💖

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. pop3 said log in.

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. dns realness.

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. ftp said don't do the most

and now for the config file commands, bestie:

  • include <path> — Include config file. include it, bestie.
  • config <path> — Path to configuration file to use on 3proxy restart. restart ready.
  • end — End of configuration. that's a wrap.
  • log [[@|&]logfile] [<LOGTYPE>] — sets logfile for all gateways.
    • @ (for Unix) use syslog, filename is used as ident name. syslog vibes.
    • & use ODBC, filename consists of comma-delimited datasource,username,password (username and password are optional). odbc said hi.
    • radius - use RADIUS for logging. radius 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. stdout said what's up
    • 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. time zones are a whole thing.
  • rotate <n> — how many archived log files to keep. keep it tidy.
  • 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 elements are in local time zone. You can use:

the logformat string is literally a whole little language, bestie, and these percent codes are its alphabet:

  • %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, aka 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

and when you're doing ODBC logging, logformat is not even a format string anymore, it's an SQL statement, like:

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> — instantly makes extra log records once the given amount of incoming/outgoing traffic is hit for a connection, without waiting for the connection to finish. It can be useful to keep info about long-lasting downloads from vanishing on server shutdown. 🔥
  • delimchar <char> — sets the delimiter character used to separate username from hostname in proxy authentication strings, like for FTP and POP3 proxies. Default is ´@´. For example, to use ´#´ instead: delimchar #. This lets usernames contain the ´@´ character. 💅
  • archiver <ext> <commandline> — archiver to use for log files. <ext> is the file extension produced by the archiver. The filename will be the last argument to the archiver, and optionally you can use %A as the produced archive name and %F as the 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 a single byte, usually used for receiving a single byte from a stream.
    • BYTE_LONG — long timeout for a single byte, usually used for receiving the first byte in a frame, like the first byte in a socks request.
    • STRING_SHORT — short timeout for a character string within a stream, like waiting between 2 HTTP headers.
    • STRING_LONG — long timeout for the first string in a stream, like waiting for an HTTP request.
    • 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 requesting the next server.
    • CHAIN — timeout for reading data from a 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 a value may cause the tail of the data to be lost on slow connections, and too large a value 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, aka 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. A port and local address to use with a 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 identifying 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 is specified, system routines for name resolution are used. An optional port number may be specified. If optional /tcp is added to the 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 a 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. ✨

okay so you can absolutely stack multiple auth types in the same command, and it's lowkey iconic:

auth iponly strong

Here's the tea: strong only gets used if the resource access can't be done with iponly auth — meaning a username is actually required in the ACL. It's giving ✨the best of both worlds✨: password-protect some resources while other stuff stays passwordless, or use IP-based auth for your dedicated laptops and make the shared ones cough up a username/password. chef's kiss 👑

🎀 authcache <cachtype> <cachtime> <cachesize> 🎀

Caches your auth info for a set amount of time (cachetime) in seconds. And cachesize caps how many cache entries you're allowed. Cachetype is one of these besties:

  • ip — after a successful authentication, every connection from that same IP during the caching time gets assigned to the same user, and the username isn't even requested.
  • ip,user — username is requested, and then all connections from the same IP get assigned to the same user without any actual authentication happening. 💀
  • user — same vibe as above, but the IP isn't checked.
  • user,password — both username and password get checked against the cached ones.
  • limit — limits the user to using only one ip, and ip and user are required.
  • acl — only use cached auth if the user accesses a service with the 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, like ip,user,dstaddr,dstport. 💅

careful bestie — with cacheacl, the ACL result is not re-evaluated on a cache hit, so every single field the ACL limits has to be part of the cache key. Otherwise the result cached for one request gets applied to a whole 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. This is especially important for SOCKSv5 UDP traffic, where the destination of every datagram gets authorized: without dstaddr and dstport in the key, the result cached for one destination gets applied to any other destination and the destination isn't checked at all. see allow. 😭

Use auth type cache (or cacheacl) for cached authentication.

🔥 allow / deny / redirect 🔥

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>

These are your access control entries, the main character of the whole config ngl. All lists are comma-separated and no spaces are allowed, fr fr. Usernames are case sensitive (and if you're using them 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 the targetlist may also contain host names instead of addresses. You can use a wildmask at the beginning and at the end of the hostname, e.g. *badsite.com or *badcontent*. The hostname only gets checked if a hostname is actually 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, bestie:

deny * * "pcre:^(ads|track)[0-9]*\.example\.(com|net)$"

The name gets lowercased and any trailing dots are removed before it's matched, so write your patterns 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 honestly enough for most rules. Targetportlist may contain ports (X) or port ranges lists (X-Y). For any field, * 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. And if you want 3proxy to reject connections from specific addresses immediately, without any conditions, you should either bind the proxy to the appropriate interface only or use ip filters. no shortcuts here 🫶

✧ OPERATIONS ✧

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. (slay for off-hours rules)

🦋 UDP, the chaotic part 🦋

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, while 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 that is genuinely hard to diagnose. Limit it only when it is really required. bestie please 🙈

Bandwidth limiters (bandlimin, bandlimout) and traffic counters (countin, countout) which limit the destination are selected when the destination is authorized — so within a UDP association they're selected for the destination of the first datagram and are not re-selected for every following destination. They can't be applied per destination to the incoming UDP traffic at all, because an incoming datagram isn't matched against any destination. periodt.

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 an allow rule. It extends the last allow rule to build a proxy chain. Proxies may be grouped, and a proxy inside a group is selected randomly. If a few groups are specified, one proxy is randomly picked from each group and a chain of proxies is created (that is, the second proxy connected through the first one and so on). ⛓️

Weight is what groups the 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, no cap. 🫶

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. iconic behavior honestly ✨

That is:

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

makes 3proxy 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 a 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. And heads up — chains are only applied to new connections; pipelined (keep-alive) requests in the same connection use the same chain. 💅

okay so picking right back up with the parent type menu, because this list is long and every single one matters — the type is one of:

  • extip — bestie, this one does not actually redirect the request. Instead it sets the external address for this request to <ip>. You can chain it with another parent type. It's giving "set my external IP based on ACL" or "make it random" ✨
  • extport — also 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 — same thing but 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, and no cap, it does not support parent authentication.
  • http — redirect to HTTP proxy. HTTP is always the last chain. It should only be used with the http (proxy) service; if used with a 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. secure queen behaviour 🔐

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, nobandlimin, bandlimout, nobandlimout

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, and 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, noconnlim

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, countin, nocountin, countout, nocountout, countall, nocountall

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 — bestie, these set a traffic limit in MB for a period of time (day, week or month). 💖

Filename is a path to a special file where the traffic info gets stored permanently. The number is the sequential number of the record in that file. If number is 0, this counter is not preserved in the counter file — which literally means if the proxy restarts, all counters with 0 get flushed. Otherwise it should be a unique sequential number that points to the position of the counter inside the file. ✨

Type says what kind of counter it is, and it's one of:

  • H — counter resets hourly
  • D — counter resets daily
  • W — counter resets weekly
  • M — counter resets monthly

reporttype/reportname may be used to generate traffic reports. reporttype is one of D, W, M, H (hourly) and reportname sets the filename template for the reports. The report is a text file with counter values in this format:

<COUNTERNUMBER> <TRAF>

The rest of the parameters is identical to bandlim/nobandlim. 👑

  • users username[:pwtype:password] ... — the whole login situation 🫶

pwtype is one of:

  • none (empty) — use system authentication
  • CL — password is cleartext
  • CR — password is crypt-style password. The $1$ prefix uses MD5-crypt (requires OpenSSL), the $3$ prefix uses BLAKE2b-crypt (always available, see 3proxy_crypt(8))
  • NT — password is NT password (in hex)

examples, keep them exact king:

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. Do not come for me about it, that's just how it is. 💅
  • 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. Bestie, 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. See? Iconic behaviour. 🌸

  • system <command> — execute system command. 💅
  • pidfile <filename> — write the pid of the current process to file. It can be used to manipulate 3proxy with signals under Unix. Currently next signals are available: ⭐
  • monitor <filename> — if the 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 a username. Unix only.
Warning: under some Linux kernels setuid() works for the current thread only. It makes it impossible to suid for all threads. Not me finding that out the hard way. 😭
  • 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, can be numeric or username/groupname. 🔥
  • 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. Periodt. 💅

🔌 PLUGINS ✨

  • plugin <path_to_shared_library> <function_to_call> [<arg1> ...] — loads the specified library and calls the given export function with the given arguments, as
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 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. Slay.

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

🕵️ MITM Commands 💅

  • ssl_mitm — spoof certificates for services started below. Usage without ssl_client_verify is insecure. 🚨
  • ssl_nomitm — do not spoof certificates for services started below.

🖥️ Server TLS Commands ✨

  • ssl_serv (or ssl_server) — require TLS connection from clients for services below.
  • ssl_noserv (or ssl_noserver) — do not require TLS connection from clients for services below.

🌐 Client TLS Commands 🦋

  • ssl_cli (or ssl_client) — establish TLS connection to upstream server for services below.
  • ssl_nocli (or ssl_noclient) — do not establish TLS connection to upstream server for services below.

🎀 SSL Parameters 💖

  • ssl_server_cert /path/to/cert — server certificate (should not be self-signed, must contain SAN) for ssl_serv
  • ssl_server_key /path/to/key — server certificate key for ssl_server_cert or generated MITM certificate
  • ssl_client_cert /path/to/cert — client certificate for authentication on upstream server (used with ssl_cli)
  • ssl_client_key /path/to/key — client certificate key for ssl_client_cert
  • ssl_client_ciphersuites ciphersuites_list — TLS client ciphers for TLS 1.3
  • ssl_server_ciphersuites ciphersuites_list — TLS server ciphers for TLS 1.3
  • ssl_client_cipher_list ciphers_list — TLS client ciphers for TLS 1.2 and below
  • ssl_server_cipher_list ciphers_list — TLS server ciphers for TLS 1.2 and below
  • ssl_client_min_proto_version tls_version — TLS client minimum TLS version (e.g., TLSv1.2)
  • ssl_server_min_proto_version tls_version — TLS server minimum TLS version
  • ssl_client_max_proto_version tls_version — TLS client maximum TLS version
  • ssl_server_max_proto_version tls_version — TLS server maximum TLS version
  • ssl_client_verify — verify the certificate for the upstream server (used with ssl_mitm or ssl_cli)
  • ssl_client_no_verify — do not verify the certificate for the upstream server (default)
  • ssl_server_verify — require client certificate authentication (mTLS) for ssl_serv
  • ssl_server_no_verify — do not require client certificate (default)
  • ssl_server_ca_file /path/to/cafile — CA certificate file for MITM
  • ssl_server_ca_key /path/to/cakey — key for ssl_server_ca_file MITM CA
  • ssl_server_ca_dir /path/to/cadir — CA directory for ssl_server_verify
  • ssl_server_ca_store /path/to/castore — CA store for ssl_server_verify (OpenSSL 3.0+)
  • ssl_client_ca_file /path/to/cafile — CA file for ssl_client_verify
  • ssl_client_ca_dir /path/to/cadir — CA directory for ssl_client_verify
  • ssl_client_ca_store /path/to/castore — CA store for ssl_client_verify (OpenSSL 3.0+)
  • ssl_client_sni hostname — SNI hostname to send to upstream server
  • ssl_client_alpn protocol1 protocol2 ... — ALPN protocols to negotiate with upstream server
  • ssl_client_mode mode — when to establish TLS connection: 0 — on connect (default), 1 — after authentication, 2 — before data, 3 — only for secure parent types (ending with s)
  • ssl_certcache /path/to/cache/ — location for the generated MITM certificates cache 🧚

💅 PCRE FILTERING 💅

okay bestie so PCRE — that's Perl Compatible Regular Expressions 🧚 — filtering is built right into 3proxy (since 0.9.7) when it's compiled with PCRE2 support (WITH_PCRE). It used to be a thing called PCREPlugin, but now the functionality is integrated into the main binary. The plugin line? Not needed anymore, periodt. 💅

PCRE filtering lets you make matching and replacement rules with regular expressions for client requests, headers, and data. It's giving regex glow-up ✨.

✨ PCRE Commands ✨

  • pcre TYPE FILTER_ACTION REGEXP [ACE] — Apply a rule for matching regular expression.
  • pcre_rewrite TYPE FILTER_ACTION REGEXP REWRITE_EXPRESSION [ACE] — Match and replace with rewrite expression.
  • pcre_extend ACE — Extend the ACL of the last pcre or pcre_rewrite command by adding an additional ACE.
  • pcre_options OPTION1 [OPTION2 ...] — Set matching options. Both PCRE2 native options and PCRE compatibility options are supported. PCRE options are mapped to their PCRE2 equivalents for backward compatibility.

PCRE2 options: PCRE2_CASELESS, PCRE2_MULTILINE, PCRE2_DOTALL, PCRE2_EXTENDED, PCRE2_DOLLAR_ENDONLY, PCRE2_UNGREEDY, PCRE2_UTF, PCRE2_UCP, PCRE2_NO_AUTO_CAPTURE, PCRE2_FIRSTLINE, PCRE2_DUPNAMES, PCRE2_MATCH_UNSET_BACKREF, PCRE2_ALT_BSUX, PCRE2_ALT_CIRCUMFLEX, PCRE2_ALT_VERBNAMES, PCRE2_USE_OFFSET_LIMIT, PCRE2_EXTENDED_MORE, PCRE2_LITERAL, PCRE2_MATCH_INVALID_UTF.

PCRE compatibility options: PCRE_CASELESS, PCRE_MULTILINE, PCRE_DOTALL, PCRE_EXTENDED, PCRE_ANCHORED, PCRE_DOLLAR_ENDONLY, PCRE_EXTRA, PCRE_NOTBOL, PCRE_NOTEOL, PCRE_UNGREEDY, PCRE_NOTEMPTY, PCRE_UTF8, PCRE_NO_AUTO_CAPTURE, PCRE_NO_UTF8_CHECK, PCRE_AUTO_CALLOUT, PCRE_PARTIAL, PCRE_DFA_SHORTEST, PCRE_DFA_RESTART, PCRE_FIRSTLINE, PCRE_DUPNAMES, PCRE_NEWLINE_CR, PCRE_NEWLINE_LF, PCRE_NEWLINE_CRLF, PCRE_NEWLINE_ANY, PCRE_NEWLINE_ANYCRLF, PCRE_BSR_ANYCRLF, PCRE_BSR_UNICODE.

These options apply to every pattern the configuration compiles — the host patterns of access rules and http rules included — so set them before the rules which are to use them. ✋

Regular expressions are not only for these commands: a host name in the target list of an access rule, and the host and URL of an http rule, take one when it is written with a pcre: prefix. See allow and BUILT IN HTTP SERVER. 👑

🎀 PCRE Parameters 🎀

  • TYPE — type of filtered data (comma-delimited list):
    • request — content of the client's request (e.g., HTTP GET request string)
    • cliheader — content of the client request headers
    • srvheader — content of the server's reply headers
    • clidata — data received from the client (e.g., HTTP POST data)
    • srvdata — data received from the server (e.g., HTML page)
  • FILTER_ACTION — action on match:
    • allow — allow this request without checking the rest of the rules
    • deny — deny this request without checking the rest of the rules
    • dunno — continue with the rest of the rules (useful with pcre_rewrite)
  • REGEXP — PCRE (Perl) regular expression. Use * if no regexp matching is required.
  • REWRITE_EXPRESSION — substitution string. May contain Perl-style substrings $1, $2, etc. $0 means the whole matched string. \r and \n may be used to insert new lines; the string may be empty ("").

A rewritten request is what the server receives. The destination is chosen, and the access rules are applied to it, before the filters run, so a rewrite that names another host or changes the method is logged but not acted on: the request is still sent where the access rules allowed. Rewriting the path or the query works on a direct connection and through a parent alike. 🔄

  • ACE — access control entry (user names, source IPs, destination IPs, ports, etc.), identical to allow/deny/bandlimin commands. The regular expression is only matched if the ACL matches the connection data.
⚠️ Warning: Regular expressions don't require authentication and cannot replace authentication and/or allow/deny ACLs. 🚨

🌈 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; 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 👑

So like, the httpsrv service is that girl who answers requests herself instead of forwarding them 💅. What she actually does with a request? Decided by http rules, and they're taken in the order they're written — the first one whose host AND URL both match is the one that handles the request. Rules belong to the service that follows them, exactly the way access rules do, and the admin is httpsrv with a set of rules already in place. Periodt. ✨

http OPERATION HOST URL [PARAMETERS]

Handle a request for URL on HOST with OPERATION. HOST gets matched against the Host header, and URL against the path — with the query string removed, bestie. 🎀

🌸 Operations 🌸

  • file PATH [TYPE [MAX-AGE [HEADERS [CODE]]]] — send the file at PATH. The file gets handed to the socket by the system where it can do that (sendfile, TransmitFile), and read here where it can't — like when the connection carries TLS. The arguments after PATH are described below, and each of them can be written as * to leave it out. 🦋
  • cache PATH [TYPE [MAX-AGE [HEADERS [CODE]]]] — same thing, but the file is read into memory on the first request and answered from there afterwards. A file that has changed on disk gets read again, and one larger than a megabyte is sent the way file would. With a MAX-AGE the file isn't looked at again for that long — the rule already told clients the file may be treated as unchanged for that time, so the server treats its own copy the same way and a request costs basically nothing but the copy out. Without one, every request stats the file, so a change gets picked up at once 👀.
  • reply [CODE [HEADERS]] — answer with a status and literally nothing else. CODE is the status to send, and it's 200 if you don't give one. A status that carries no body of its own (1xx, 204, 304) is sent without a length; anything else is sent with a length of zero.
  • redir [CODE] LOCATION — answer with a redirect. CODE is 301 or 302, or any status from 300 to 399; without one, 302 is used.
  • rewrite PATH — change the path of the request and hand it to the rules that follow this one.
  • rewrite_host HOST — the same but for the host, which decides which of the rules after it match. $1 upwards stand for whatever the stars, or the groups, of this rule's host pattern matched, the way they stand for those of the URL in a rewrite. What you build has to be a host name; the name the client sent is what access rules matched and what the log records.
  • echo — answer with a description of the request: the method, path, query, host, and the address and port it came from. For testing 🧪.
  • data [size=N] [block=N] [status=N] [chunked=1] [delay=N] — answer with generated content of the size asked for. For testing 🧪.
  • proxypass — hand the request to the proxy code, which fetches it the way proxy would, see BOTH A SITE AND A PROXY below.
  • admin, admin_counters, admin_reload, admin_services — the pages of the administration interface 👑.

💖 What a rule adds to the answer 💖

TYPE is the content type to answer with. Without it, or with *, the type is worked out from the name of the file, see http_content_type.

MAX-AGE is a number of seconds, and gets sent as Cache-Control: max-age. Without it, or with *, nothing is said about caching.

HEADERS is one argument holding whole header lines, separated by a backslash and an n — the two characters, since a configuration line can't carry a line ending. Each one becomes a real line ending in the answer. Quote the argument if any header holds a space, which they usually do 🙈.

CODE is the status to answer with instead of 200, which is how a file serves as the body of an error page.

A rule's headers and MAX-AGE go with whatever status that rule asked for. They are not sent with a refusal the server itself decided on: a request for a file which isn't there is answered 404 by the server, not by the rule. 💀

file and cache send Last-Modified, and answer a request carrying If-Modified-Since with 304 and no body when the file hasn't changed since the time it names. All three date formats HTTP allows are read; one which can't be read is treated as no date at all. A rule answering with a CODE of its own is answering something other than the file, so it's never turned into a 304.

http file * /err/** "/usr/local/web/404.html" text/html * "X-Served:
static" 404
http reply * /health** 200 "X-Health: ok"
http reply * /down** 503 "Retry-After: 30"

✨ http_content_type ✨

http_content_type EXTENSION TYPE

Answer for a file with that extension with that content type, in addition to the types already known. The extension may be written with or without its dot. A type named by a rule is used whatever this says, and a name the server knows nothing about is answered as application/octet-stream.

http_content_type .webp image/webp

🦋 Patterns 🦋

A URL is matched with stars, or with a regular expression when it carries a pcre: prefix (regex: is taken as well). A host is matched the way an access list matches one, and takes the same prefix.

  • * stands for any run of characters within one element of the path: it does not cross a /, so a rule cannot reach into a directory it didn't name. 🙅‍♀️
  • ** crosses them, and it's what a rule which should match everything below a point, or everything at all, is written with.
  • Each star, and each group of a regular expression, is remembered in the order it appears. $1 upwards stand for them in the path or location a rule builds, and $0 for the whole request path.

Outside quotes a dollar begins the name of a file to include, so an argument holding one — a path or location built with $1, a regular expression anchored with $ — is written in quotes. $$ stands for a single dollar and isn't read as an include either, which is how a dollar reaches a rule as text. 💅

🌈 Both a site and a proxy 🌈

A request may arrive the way it arrives at a site, naming a path and a host in the Host header, or the way it arrives at a proxy, naming the whole URL, or, for a tunnel, the host alone with CONNECT. Both are read. A request in the proxy form authenticates with Proxy-Authorization and is refused with 407, as a proxy refuses one; a request in the site form uses Authorization and 401.

What answers a request is still decided by the rules. proxypass is the rule which answers by fetching, so a service can serve what it has and proxy the rest:

http file * /local/** "/usr/local/web/$1"
http proxypass * /**
httpsrv -p8080

The same happens without a rule for it where an access rule redirects to the local proxy, which is written as a chain of no address: the rules are asked first, and a request none of them answers is fetched.

allow *
parent 1000 http 0.0.0.0 0
allow *

The second allow is what the proxy matches on the pass it makes itself: a rule carrying the chain is not taken twice. Authentication happens twice for the same reason — once for the service and once for the proxy — so a configuration asking for credentials asks for them as a proxy does.

The access rules are read from the top on both passes, and it's the second pass which describes where the request is going. On the first one the service is answering for itself, so the destination an address or a port is matched against is the address the client connected to; the name from the request is matched on both. On the second, the destination is the one the request names, so rules written with an address, a port or a name decide what the proxy is allowed to fetch — and they decide it before the connection is made:

allow *
parent 1000 http 0.0.0.0 0
allow * * * 80,443
deny *

Everything reaches the rules, and only ports 80 and 443 are fetched. A rule before the one carrying the chain applies on both passes just the same, so a deny written there stops the request as well. 🔥

The connection to the server is kept for the request after it, and closed when the request after it goes somewhere else, or when the server has closed it in the meantime. A tunnel is fetched by the proxy code as well, which means the connection carrying it belongs to that request alone.

💜 Connections 💜

An answer is sent as HTTP/1.1 to a client which asked in HTTP/1.1, and the connection is kept for the next request unless the client sent Connection: close. A 1.0 client gets a 1.0 answer, and the connection is kept only when it asked with Connection: keep-alive.

The connection is kept only when what was sent is framed exactly: every operation but the administration pages states a length, or sends a chunked body a 1.1 client can read — so the pages of admin are always the last thing on a connection. A request body which can't be read to its end ends the connection as well: one sent with Transfer-Encoding, which this server does not read, and one longer than a megabyte, which it will not. 😭

🎀 Paths a rule builds 🎀

The path a rule builds is used as it is, so it's refused rather than corrected when it's not a plain full path. A relative path is refused: it would be read against whatever directory the service happens to be in. So is one holding . or .. as an element, a carriage return, a newline or a star. On Windows a path must name a drive or a share, and is converted to the extended \\?\ form and opened through the wide interface, so a long path works.

A request is checked before any of this: a path which decodes to one leaving the tree is refused outright. 🚫

⭐ Examples ⭐

http file example.com /my/webpath/*.html "/usr/local/web/$1.html"
http cache example.com "pcre:^/(.*)/pic/(.*).(gif|jpeg)$"
"/usr/local/web/picts/$1/$2.$3"
http redir * /old/** 301 "https://example.org/$1"
http rewrite * /alias/** "/w/$1"
http rewrite_host *.old.example ** "$1.new.example"
http file * /static/** "/usr/local/web/static/$1"
httpsrv -p8080

💀 BUGS 💀

Report all bugs to 3proxy@3proxy.org — yes bestie, they really want your bug reports, send them fr fr 📬.

🫶 SEE ALSO 🫶

3proxy(8), 3proxy_crypt(8), ftppr(8), htproxy(8), socks(8), pop3p(8), imapp(8), smtpp(8), tlspr(8), tcppm(8), udppm(8), syslogd(8), https://3proxy.org/ — go read the whole squad, iykyk 🌸

👑 AUTHORS 👑

3proxy is designed by Vladimir Dubrovin <vlad@3proxy.org> — legend behaviour, no cap 💖

okay so that's literally the whole page, you made it to the end and I'm so proud of you 🥹 this was 3proxy version 0.9, dated May 2026, from 3proxy.cfg(5). Go forth and configure, main character 💅✨🦋

📦 where this page comes from