dwww Home | Manual pages | Find package

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

NAME
       3proxy.cfg 3proxy configuration file

DESCRIPTION
        Common structure:
        Configuration file is a text file 3proxy reads configuration from. Each
       line  of the file is a command executed immediately, as if it were given
       from the console. The sequence of commands is important. The  configura-
       tion  file is actually a script for the 3proxy executable.  Each line of
       the file is treated as a blank (space or tab)  separated  command  line.
       Additional  space characters are ignored.  Think about 3proxy as "appli-
       cation level router" with console interface.

        Comments:
        Any line beginning with a space character or ´#´ character  is  a  com-
       ment. 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 conven-
       tion). For example, to use HELLO "WORLD"  as  an  argument,  you  should
       write  it  as "HELLO ""WORLD""".  Good practice is to quote any argument
       you use.

        File inclusion:
        You can include file by using $FILENAME macro (replace FILENAME with  a
       path to file, for example $/usr/local/etc/3proxy/conf.incl or
        $"c:\\Program  Files\3proxy\include.cfg"  Quotation is required in last
       example because path contains space character.  For included  file  <CR>
       (end of line characters) is treated as space character (arguments delim-
       iter instead of end of command delimiter).  Thus, include files are only
       useful to store long single-line commands (like userlist, network lists,
       etc).   To  use  dollar  sign somewhere in argument it must be quoted or
       doubled: inside quotes a dollar is ordinary text, and $$  stands  for  a
       single dollar and is not read as an include.  Recursion is not allowed.

        Next commands start gateway services:

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

        Options:
       -pNUMBER change default server port to NUMBER
       -6  Only  resolve  IPv6  addresses. IPv4 addresses are packed in IPv6 in
       IPV6_V6ONLY compatible way.
       -4 Only resolve IPv4 addresses. This is the default: a  service  reaches
       an IPv6 address only when told to with -6, -46 or -64.
       -46  Prefer  IPv4. Resolve IPv6 addresses if IPv4 address is not resolv-
       able
       -64 Prefer IPv6. Resolve IPv4 addresses if IPv6 address is  not  resolv-
       able
       -e External address. IP address of the interface the proxy should initi-
       ate connections from. External IP must be specified if you need incoming
       connections.   By default the system will decide which address to use in
       accordance with the routing table.
       -i Internal address. IP address the proxy accepts  connections  to.   By
       default, connections to any interface are accepted.  Unix domain sockets
       can  be specified with -iunix:/path/to/socket syntax. On Linux, abstract
       sockets use -iunix:@socketname syntax.
       -DiINTERFACE, -DeINTERFACE bind internal (-Di) / external  (-De)  inter-
       face  to  given INTERFACE (e.g. eth0) if SO_BINDTODEVICE is supported by
       the system. You may need to run as root or have  CAP_NET_RAW  capability
       in  order  to bind to an interface, depending on the system, so this op-
       tion may require root privileges and can be incompatible with some  con-
       figuration  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 connec-
       tions (-ne).  With -ni the current namespace is saved before opening the
       listening  socket  and  restored  immediately after binding, so that the
       rest of the process (outgoing connections, child threads)  runs  in  the
       original  namespace  unless  -ne  is  also  given.  With -ne the process
       switches to the specified namespace after the listening socket is  bound
       (and  after  restoring  from -ni if applicable).  Requires CAP_SYS_ADMIN
       (or CAP_NET_ADMIN on recent kernels) and is incompatible with chroot/se-
       tuid/daemon if privileges are dropped before the switch takes effect.
       -Ne (for socks) External NAT address  (between  3proxy  and  destination
       server)  to  report  to client for CONNECT and BIND. By default external
       address is reported. It's only useful in the case of IP-IP NAT (will not
       work for PAT).
       -Ni (for socks) Internal NAT address (between client and 3proxy) to  re-
       port  to  client  for UDPASSOC. By default internal address is reported.
       It's only useful in the case of IP-IP NAT (will not work for PAT).
       -RHOST:port listen on given local HOST:port for incoming connections in-
       stead 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  ser-
       vice  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.   OP-
       TIONS is a comma separated list of NAME or NAME=VALUE; a name alone sets
       the option to 1 (TCP_MAXSEG to the value of maxseg), and NAME=0 turns it
       off.  Options  add  to the defaults and to the options given earlier for
       the same socket. An unknown name or a value which is not a number is  an
       error.   TCP_NODELAY  is set by default on proxy-to-client and proxy-to-
       server sockets, so a reply written in several parts is  not  delayed  by
       Nagle's  algorithm;  use -ocTCP_NODELAY=0 or -osTCP_NODELAY=0 to turn it
       off, e.g. to send fewer packets on slow links.  Options  like  TCP_CORK,
       TCP_NODELAY,     TCP_DEFER_ACCEPT,     TCP_QUICKACK,     TCP_TIMESTAMPS,
       TCP_FASTOPEN,    SO_REUSEADDR,    SO_REUSEPORT,     SO_EXCLUSIVEADDRUSE,
       SO_PORT_SCALABILITY,  SO_REUSE_UNICASTPORT,  SO_KEEPALIVE,  SO_DONTROUTE
       may be supported depending on OS.  SO_REUSEADDR and SO_REUSEPORT are set
       by default on the listening sockets (-ol,  -oR)  on  Unix;  -olSO_REUSE-
       PORT=0  turns one off. On Windows SO_REUSEADDR is not set: it is not re-
       quired to rebind a listening port and it only lets another local process
       bind the same address and port. Use SO_EXCLUSIVEADDRUSE (Windows) on the
       listening socket (-ol) to prevent that.
       -H (for all services) Expect HAProxy PROXY protocol v1 header on  incom-
       ing connection.  This allows the proxy to receive real client IP address
       from  HAProxy  or  other load balancer that supports the PROXY protocol.
       The header must be sent before any protocol-specific data.
       -g(GRACE_TRAFF,GRACE_NUM,GRACE_DELAY) delay GRACE_DELAY milliseconds be-
       fore 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
       -B (for TCP services) split the TLS ClientHello across two TCP  segments
       in  the middle of the server name (SNI) when it is passed through tlspr,
       as with parent ... tls 0.0.0.0 0: some DPI systems looking  for  blocked
       host  names  do not reassemble it. TCP_NODELAY, set by default, must not
       be turned off, or the kernel may join  the  segments  again.  In  builds
       without splice() -s does the same.
       -s
        (for  admin) secure, allow only secure operations, currently only traf-
       fic counters view without ability to reset.
        (for TCP services, Linux) use splice() to pass data between the  client
       and  the server without copying it through 3proxy. -s alone splices both
       directions where it pays: a body of known length if at least 16K  of  it
       is  left  to read, a stream once it carries large reads, back to copying
       when they turn small. -s1 always splices what the server  sends  to  the
       client  (downloads),  -s2  what  the  client  sends (uploads), -s3 both;
       adding 4 (-s5, -s6, -s7, the last the same as -s) splices  those  direc-
       tions only where it pays. -s0, the default, turns it off. splice() suits
       large  transfers:  they  go  faster  and use less CPU; small requests go
       slower with it. A spliced direction needs a pipe (two file descriptors),
       made when first needed and kept for the connection, and more kernel mem-
       ory; data filters are not applied to spliced data. Available  in  builds
       with WITHSPLICE, the default on Linux.
       -C
        (for  TCP  services) a connection closed by any of the sides terminates
       the session, buffered data is delivered before the sockets  are  closed.
       By  default  the  session  is kept until both sides close the connection
       (TCP half-close).  Half-close is required for the protocols where one of
       the sides closes its sending side and expects the answer, but  it  keeps
       the  socket  of  the  side  which  has  already closed the connection in
       CLOSE_WAIT state. Use -C to close both sockets as soon  as  any  of  the
       sides  closes  the  connection, -C1 to request the default behaviour ex-
       plicitly.
       -U[MODE]
        (for socks) what to do when the destination changes within an UDP asso-
       ciation: 1 - log it, 2 - authorize it, 3 - both, the default, 0 (same as
       bare -U) - neither. The destination of the first datagram is always  au-
       thorized  and logged. With -U0 and -U1 the destination is not authorized
       again, so ACLs limiting the destination only apply to the first destina-
       tion of the association, and the parent proxy and the  external  address
       selected  for it are kept for the whole association. Use -U2 to keep the
       authorization and to drop the per-destination log records only.
        (for dnspr) simple, do not use resolver and 3proxy  cache,  always  use
       external DNS server.
        (for  udppm)  singlepacket, expect only one packet from both client and
       server
       -u Never ask for username/password
       -u2 (for socks) require username/password in authentication methods
       -a (for proxy) anonymous proxy (no information about client reported)
       -a1 (for proxy) anonymous proxy (random client information reported)
       -a2 (for proxy) generate Via: and X-Forwarded-For: instead of Forwarded:
       -Xftp (for proxy) fetch ftp:// URLs, in a build with FTP support.  With-
       out  this  the  scheme is not one the service knows, whatever the build:
       fetching it opens a second connection and builds a listing, which a ser-
       vice serving http has no use for.
        Also, all options mentioned for  proxy(8)  socks(8)  pop3p(8)  imapp(8)
       tcppm(8) udppm(8) ftppr(8)
        are also supported.
        Portmapping  services  listen at SRCPORT and connect to DSTADDR:DSTPORT
       HTTP and SOCKS proxies are standard.
        POP3 proxy must be configured as POP3 server and requires  username  in
       the  form  of: pop3username@pop3server. If POP3 proxy access must be au-
       thenticated, you  can  specify  username  as  proxy_username:proxy_pass-
       word: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:proxy-
       password:FTPuser  as  FTP username, otherwise do not change original FTP
       user name

       include <path>
        Include config file

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

       end
        End of configuration

       log [[@|&]logfile] [<LOGTYPE>]
        sets logfile for all gateways
        @ (for Unix) use syslog, filename is used as ident name
        & use  ODBC,  filename  consists  of  comma-delimited  datasource,user-
       name,password (username and password are optional)
        radius - use RADIUS for logging
        LOGTYPE is one of:
         c Minutely
         H Hourly
         D Daily
         W Weekly (starting from Sunday)
         M Monthly
         Y Annually
        if logfile is not specified logging goes to stdout. You can specify in-
       dividual  logging options for gateway by using -l option in gateway con-
       figuration.
        log command supports same format specifications for  filename  template
       as  "logformat"  (if filename contains ´%´ sign it´s believed to be tem-
       plate).  As with "logformat" filename must begin  with  ´L´  or  ´G´  to
       specify  Local or Grinwitch time zone for all time-based format specifi-
       cators.

       rotate <n>
        how many archived log files to keep

       logformat <format>
        Format for log record. First symbol in format must be L (local time) or
       G (absolute Grinwitch time).  It can be preceeded with -XXX+Y where  XXX
       is  list  of  characters to be filtered in user input (any non-printable
       characters are filtered too in this case) and Y is  replacement  charac-
       ter. For example, "-,%+ L" in the beginning of logformat means comma and
       percent  are replaced with space and all time based elemnts are in local
       time zone.
        You can use:

         %y Year in 2 digit format
         %Y Year in 4 digit format
         %m Month number
         %o Month abbreviation
         %d Day
         %H Hour
         %M Minute
         %S Second
         %t Timestamp (in seconds since 01-Jan-1970)
         %. milliseconds
         %z time zone (from Greenwich)
         %D request duration (in milliseconds)
         %b average send rate per request (in bytes per second); this speed  is
       typically below the connection speed shown by the download manager.
         %B  average receive rate per request (in bytes per second); this speed
       is typically below the connection speed shown by the download manager.
         %U Username
         %N service Name
         %p service Port
         %E Error code
         %C Client IP
         %c Client port
         %R Remote IP
         %r Remote port
         %i Internal IP used to accept client connection
         %e External IP used to establish connection
         %Q Requested IP
         %q Requested port
         %n requested hostname
         %I bytes In
         %O bytes Out
         %h Hops (redirections) count
         %T service specific Text
         %N1-N2T (N1 and N2 are positive  numbers)  log  only  fields  from  N1
       through N2 of service-specific text
        In  the case of ODBC logging, logformat specifies an SQL statement, for
       example:
        logformat "-´+_Linsert  into  log  (l_date,  l_user,  l_service,  l_in,
       l_out, l_descr) values (´%d-%m-%Y %H:%M:%S´, ´%U´, ´%N´, %I, %O, ´%T´)"

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

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

       archiver <ext> <commandline>
        Archiver  to  use  for  log  files. <ext> is file extension produced by
       archiver. Filename will be last argument to archiver, optionally you can
       use %A as produced archive name and %F as filename.

       timeouts <BYTE_SHORT> <BYTE_LONG> <STRING_SHORT> <STRING_LONG>  <CONNEC-
       TION_SHORT>  <CONNECTION_LONG>  <DNS>  <CHAIN>  <CONNECT>  <CONNECTBACK>
       <LINGER>
        Sets timeout values, defaults 1, 5, 30, 60, 180, 1800, 15, 60,  15,  5,
       5.
        BYTE_SHORT short timeout for single byte, is usually used for receiving
       single byte from stream.
        BYTE_LONG  long  timeout for single byte, is usually used for receiving
       first byte in frame (for example first byte in socks request).
        STRING_SHORT short timeout, for character string within stream (for ex-
       ample to wait between 2 HTTP headers)
        STRING_LONG long timeout, for first string in stream  (for  example  to
       wait for HTTP request).
        CONNECTION_SHORT  inactivity timeout for short connections (HTTP, POP3,
       etc).
        CONNECTION_LONG inactivity timeout for long connection (SOCKS, portmap-
       pers, etc).
        DNS timeout for DNS request before requesting next server
        CHAIN timeout for reading data from chained connection
        LINGER timeout to deliver buffered data after  one  of  the  sides  has
       closed  its  sending side, also used as SO_LINGER value on outgoing con-
       nections. Too small value may cause the tail of the data to be  lost  on
       slow connections, too large one delays release of the sockets.
        default timeouts 1 5 30 60 180 1800 15 60 15 5 5

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

       radius   <NAS_SECRET>   <radius_server_1[:port][/local_address_1]   <ra-
       dius_server_2[:port][/local_address_2]
        Configures RADIUS servers to be used  for  logging  and  authentication
       (log  and  auth  types must be set to radius). port and local address to
       use with given server may be specified.
        Attributes within request: User-Name, Password: (username and  password
       if presented by client), Service Type: Authenticate-Only, NAS-Port-Type:
       NAS-Port-Virtual,  NAS-Port-ID:  (proxy  service  port, e.g. 1080), NAS-
       IPv6-Address / NAS-IP-Address: (proxy  interface  accessed  by  client),
       NAS-Identifier:  (text identifing proxy, e.g. PROXY or SOCKSv5), Framed-
       IPv6-Address / Framed-IP-Address: (IP address of  the  client),  Called-
       Station-ID:  (requested  Hostname, if presents), Login-Service: (type of
       request, e.g. 1001 - SOCKS CONNECT, 1010 - HTTP GET, 1013  -  HTTP  CON-
       NECT),  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 auth-
       cache to speedup authentication. RADIUS feature is currently  experimen-
       tal.

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

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

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

       nsrecord <hostname> <hostaddr>
        Adds static record to nscache. nscache must be enabled  and  must  come
       first, because the record is placed in the table it allocates - nscache6
       for  a  record naming an IPv6 address - and nserver must be set as well:
       without it the system resolver is used and static records are never con-
       sulted. 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 gate-
       ways. 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 (file-
       less) Unix sockets are supported with the syntax unix:@socketname (e.g.,
       internal unix:@3proxy). When using Unix sockets, the socket file is  au-
       tomatically 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 Ex-
       ternal or -e can be given twice: once with IPv4 and once with  IPv6  ad-
       dress.

       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  con-
       nection 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 ser-
       vice  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 recom-
       mended 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  authoriza-
       tion  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 in-
       stead of through the parent proxy of the matching ACL entry, with no er-
       ror reported. Do not use cacheacl  together  with  parent  proxies,  use
       cache  instead.  The  only redirection type which survives is extip, and
       only if ext is a part of the authcache key, because the external address
       is then restored from the cache entry.
        radius - authentication with RADIUS.
        Plugins may add additional authentication types.

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

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

       allow  <userlist>  <sourcelist>  <targetlist>  <targetportlist>  <opera-
       tionlist> <weekdayslist> <timeperiodslist>
       deny  <userlist>  <sourcelist>  <targetlist>  <targetportlist>   <opera-
       tionlist> <weekdayslist> <timeperiodslist>
       redirect  <ip>  <port>  <userlist>  <sourcelist>  <targetlist>  <target-
       portlist> <operationlist> <weekdayslist> <timeperiodslist>
        Access control entries. All lists are comma-separated,  no  spaces  are
       allowed.  Usernames  are  case  sensitive  (if used with authtype nbname
       username must be in uppercase). Source and target lists may  contain  IP
       addresses  (W.X.Y.Z),  ranges  A.B.C.D  -  W.X.Y.Z  (since 0.8) or CIDRs
       (W.X.Y.Z/L).  Since 0.6, the targetlist may also contain host names, in-
       stead of addresses. It´s possible to use a wildmask in the beginning and
       at the end of the hostname,  e.g.  *badsite.com  or  *badcontent*.   The
       hostname  is  only  checked  if a hostname is present in the request.  A
       name written with a pcre: prefix (regex: is the same thing) is a regular
       expression instead of a wildmask, in a build with PCRE support:
        deny * * "pcre:^(ads|track)[0-9]*\.example\.(com|net)$"
        The name is lowercased and any trailing dots are removed before  it  is
       matched,  so  patterns  are written in lower case. A pattern ending in $
       has to be quoted or written $$, since a lone dollar outside  quotes  be-
       gins the name of a file to include. The same patterns, and the same pre-
       fix, are used by the http command, see BUILT IN HTTP SERVER. Regular ex-
       pressions  are  matched per request and cost more than a wildmask, which
       is enough for most rules.  Targetportlist may contain ports (X) or  port
       ranges  lists  (X-Y).  For any field * sign means ANY. If access list is
       empty it´s assumed to be
        allow *
        If access list is not empty last item in access list is assumed to be
        deny *
        You may want explicitly add deny * to the end of access list to prevent
       HTTP proxy from requesting user´s password.  Access  lists  are  checked
       after  user  have  requested any resource.  If you want 3proxy to reject
       connections from specific addresses immediately without  any  conditions
       you  should either bind proxy to appropriate interface only or to use ip
       filters.

        Operation is one of:
        CONNECT establish outgoing TCP connection
        BIND bind TCP port for listening
        UDPASSOC make UDP association
        ICMPASSOC make ICMP association (for future use)
        HTTP_GET HTTP GET request
        HTTP_PUT HTTP PUT request
        HTTP_POST HTTP POST request
        HTTP_HEAD HTTP HEAD request
        HTTP_CONNECT HTTP CONNECT request
        HTTP_OTHER over HTTP request
        HTTP matches any HTTP request except HTTP_CONNECT
        HTTPS same as HTTP_CONNECT
        FTP_GET FTP get request
        FTP_PUT FTP put request
        FTP_LIST FTP list request
        FTP_DATA FTP data connection. Note: FTP_DATA requires access to dynamic
       non-privileged (1024-65535) ports on the remote side.
        FTP matches any FTP/FTP Data request
        ADMIN access to administration interface

        Weekdays are week day numbers or periods, 0 or 7  means  Sunday,  1  is
       Monday, 1-5 means Monday through Friday.
        Timeperiodlists  is a list of time periods in HH:MM:SS-HH:MM:SS format.
       For  example,  00:00:00-08:00:00,17:00:00-24:00:00   lists   non-working
       hours.
        A SOCKSv5 UDP ASSOCIATE request carries no destination, the destination
       of  every  datagram is taken from the datagram itself. 3proxy authorizes
       the destination of every datagram, so ACLs limiting the destination  ad-
       dress, 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 ac-
       cepted, 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 asso-
       ciation is not logged.
        A  client  may  use a single association to reach many destinations. An
       ACL entry which limits the destination silently drops the  datagrams  to
       every  other destination, so limiting the destination of UDP traffic can
       break such clients in a way which is hard to  diagnose.  Limit  it  only
       when it is really required.
        Bandwidth   limiters   (bandlimin,  bandlimout)  and  traffic  counters
       (countin, countout) which limit the destination are  selected  when  the
       destination  is  authorized,  so  within an UDP association they are se-
       lected for the destination of the first datagram and are not re-selected
       for every following destination. They can not be applied per destination
       to the incoming UDP traffic at all, because an incoming datagram is  not
       matched against any destination.
        Only  socks5 and socks5+ parents can be used for UDP. Because every new
       destination is authorized, use authcache, especially with ´strong´,  RA-
       DIUS  or  plugin  authentication:  cacheacl  with the destination in the
       cache key if no parent proxy is used, cache otherwise, see cacheacl.

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

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

        IP  and  port  are ip addres and port of parent proxy server.  If IP is
       zero, ip is taken from original request, only port is changed.  If  port
       is  zero, it´s taken from original request, only IP is changed.  If both
       IP and port are zero - it´s a special  case  of  local  redirection,  it
       works  only  with  socks  proxy. In case of local redirection request is
       redirected to different service, ftp locally redirects to ftppr pop3 lo-
       cally 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´  com-
       mand.  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 (equiva-
       lent 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 mem-
       ber  of  the group instead of the same parent again. Its share is spread
       over the parents of the group which are left,  in  proportion  to  their
       weights.
        Weight  0  marks a fallback parent. Such a parent takes no share of the
       random choice, and none of the share left over by a parent which failed,
       and is only used once every weighted parent of  its  group  has  failed,
       which is how a parent used only when another one is down is configured:
        allow *
        parent 1000 socks5 192.168.10.1 1080
        parent 0 socks5 192.168.20.1 1080
        Several  fallbacks  are tried in the order they are written. Reaching a
       fallback costs an attempt, so parentretries has to be at least as  large
       as the number of parents to try.
        When  every  parent  of  a  group has failed the request fails as well,
       rather than being sent without a parent.

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

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

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

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

       bandlimin  <rate>  <userlist> <sourcelist> <targetlist> <targetportlist>
       <operationlist> <weekdayslist> <timeperiodslist>
       nobandlimin <userlist> <sourcelist> <targetlist> <targetportlist> <oper-
       ationlist> <weekdayslist> <timeperiodslist>
       bandlimout <rate> <userlist> <sourcelist> <targetlist>  <targetportlist>
       <operationlist> <weekdayslist> <timeperiodslist>
       nobandlimout  <userlist> <sourcelist> <targetlist> <targetportlist> <op-
       erationlist> <weekdayslist> <timeperiodslist>
        bandlim sets a bandwidth limitation filter to <rate> bps (bits per sec-
       ond).  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  ad-
       dresses) to 57600 bps, you have to specify 4 rules like
        bandlimin 57600 * 192.168.10.16
        bandlimin 57600 * 192.168.10.17
        bandlimin 57600 * 192.168.10.18
        bandlimin 57600 * 192.168.10.19
        and each of your clients will have a 56K channel. If you specify
        bandlimin 57600 * 192.168.10.16/30
        you  will  have a 56K channel shared between all clients.  If you want,
       for example, to limit all speed except access to POP3, you can use
        nobandlimin * * * 110
        before the rest of bandlim rules.

       connlim <rate> <period> <userlist>  <sourcelist>  <targetlist>  <target-
       portlist> <operationlist> <weekdayslist> <timeperiodslist>
       noconnlim  <userlist> <sourcelist> <targetlist> <targetportlist> <opera-
       tionlist> <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, no-
       connlim adds an exception.

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

        counter, countin, nocountin, countout, nocountout, countall, nocountall
       commands are used to set a traffic limit in MB  for  a  period  of  time
       (day, week or month). Filename is a path to a special file where traffic
       information  is permanently stored.  The number is the sequential number
       of the record in this file. If the number is 0, this counter is not pre-
       served in the counter file (that is, if  the  proxy  is  restarted,  all
       counters  with  0 are flushed); otherwise, it should be a unique sequen-
       tial number which points to the position of the counter within the file.
       Type specifies a type of counter. Type is one of:
        H - counter is reset hourly
        D - counter is reset daily
        W - counter is reset weekly
        M - counter is reset monthly
        reporttype/reportname may be used to generate traffic reports.  Report-
       type is one of D, W, M, H (hourly) and reportname specifies the filename
       template for reports. The report is a text file with counter  values  in
       the format:
        <COUNTERNUMBER> <TRAF>
        The rest of parameters is identical to bandlim/nobandlim.

       users username[:pwtype:password] ...
        pwtype is one of:
        none (empty) - use system authentication
        CL - password is cleartext
        CR  -  password is crypt-style password. $1$ prefix uses MD5-crypt (re-
       quires OpenSSL), $3$ prefix uses BLAKE2b-crypt  (always  available,  see
       3proxy_crypt(8))
        NT - password is NT password (in hex)
        example:
        users test1:CL:password1 "test2:CR:$1$lFDGlder$pLRb4cU2D7GAT58YQvY49."
        users test3:NT:BD7DFBF29A93F93C63CB84790DA00E63
        users "test4:CR:$3$salt$G47yV9w...."
        Note:  double  quotes  are  required  because the password contains a $
       sign.

       transparent [auto|netfilter|pf|socket]
        Take the destination of a connection, both address and port,  from  the
       packet  filter  that  redirected it, instead of from the request. It ap-
       plies 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  destina-
       tion  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, netfil-
       ter asks the Linux kernel, pf looks the connection up in the packet fil-
       ter,  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 lis-
       tens 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, lim-
       its 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 ad-
       dress 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 de-
       clared after it.

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

       system <command>
        execute system command

       pidfile <filename>
        write pid of current process to file. It  can  be  used  to  manipulate
       3proxy with signals under Unix. Currently next signals are available:

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

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

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

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

       stacksize <value_to_add_to_default_stack_size>
        Change the default size for thread stacks. May be required in some sit-
       uations, e.g. with non-default  plugins,  or  on  some  platforms  (some
       FreeBSD  versions  may require adjusting the stack size due to an incor-
       rectly defined value in system header files; this value  is  also  often
       required  to be changed for ODBC and PAM support on Linux). If you expe-
       rience 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 vf-
       printf() called by syslog() use significantly more stack there. The  re-
       sult is never lowered below PTHREAD_STACK_MIN, so a large negative value
       can not disable the thread stack.

PLUGINS
       plugin <path_to_shared_library> <function_to_call> [<arg1> ...]
        Loads  specified library and calls given export function with given ar-
       guments, as
        int functions_to_call(struct pluginlink * pl, int argc, char * argv[]);
        function_to_call must return 0 in case of success, value > 0  to  indi-
       cate 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 re-
       quired.

       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 cer-
       tificate  authentication  -  mTLS (mutual TLS) requiring client certifi-
       cates

   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 ser-
       vices 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  up-
       stream 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  ver-
       sion (e.g., TLSv1.2)
       ssl_server_min_proto_version  tls_version  - TLS server minimum TLS ver-
       sion
       ssl_client_max_proto_version tls_version - TLS client maximum  TLS  ver-
       sion
       ssl_server_max_proto_version  tls_version  - TLS server maximum TLS ver-
       sion
       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 se-
       cure parent types (ending with 's')
       ssl_certcache /path/to/cache/ - location for the generated MITM certifi-
       cates cache

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

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

   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 ad-
       ditional 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  equiva-
       lents for backward compatibility.
       PCRE2  options: PCRE2_CASELESS, PCRE2_MULTILINE, PCRE2_DOTALL, PCRE2_EX-
       TENDED,  PCRE2_DOLLAR_ENDONLY,  PCRE2_UNGREEDY,  PCRE2_UTF,   PCRE2_UCP,
       PCRE2_NO_AUTO_CAPTURE,  PCRE2_FIRSTLINE, PCRE2_DUPNAMES, PCRE2_MATCH_UN-
       SET_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_NOT-
       BOL,     PCRE_NOTEOL,     PCRE_UNGREEDY,    PCRE_NOTEMPTY,    PCRE_UTF8,
       PCRE_NO_AUTO_CAPTURE, PCRE_NO_UTF8_CHECK,  PCRE_AUTO_CALLOUT,  PCRE_PAR-
       TIAL,  PCRE_DFA_SHORTEST,  PCRE_DFA_RESTART,  PCRE_FIRSTLINE,  PCRE_DUP-
       NAMES, PCRE_NEWLINE_CR,  PCRE_NEWLINE_LF,  PCRE_NEWLINE_CRLF,  PCRE_NEW-
       LINE_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  be-
       fore 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 sub-
       strings $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 cho-
       sen, 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 re-
       place 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,  which  a
       proxy  service  then  still  has  to  ask for with -Xftp; with CMake the
       switches  are  -D3PROXY_USE_MAILPROXY=ON  and  -D3PROXY_USE_FTP=ON.  The
       standalone  binaries of those services are built with them and not with-
       out.
        A configuration naming a service which was not built is still read. The
       three mail proxies become tlspr negotiating STARTTLS in  that  protocol,
       which  is  what most of their use amounts to now that the mail protocols
       are used over TLS, and a parent chain naming pop3, imap or smtp does the
       same. ftppr is answered by nothing: a client reaching it is turned  away
       and the refusal logged, since there is no protocol to fall back on.

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

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

   Operations
        file PATH [TYPE [MAX-AGE [HEADERS [CODE]]]] - send the  file  at  PATH.
       The  file  is  handed  to  the socket by the system where it can do that
       (sendfile, TransmitFile) and read here where it cannot, as when the con-
       nection carries TLS.  The arguments after PATH are described below,  and
       each of them may be written as * to leave it out.
        cache  PATH  [TYPE [MAX-AGE [HEADERS [CODE]]]] - the same, but the file
       is read into memory on the first request and answered from there  after-
       wards.   A  file  that has changed on disk is read again, and one larger
       than a megabyte is sent as file would. With a MAX-AGE the  file  is  not
       looked  at  again  for  that long: the rule has 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  nothing  but  the  copy  out.
       Without  one  every  request stats the file, so a change is picked up at
       once.
        reply [CODE [HEADERS]] - answer with a status and nothing  else.   CODE
       is  the  status to send, 200 without one. A status which 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 for the host, which decides which of the
       rules after it match. $1 upwards  stand  for  what  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 is built 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.
        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 is 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-
       not carry a line ending. Each 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 is not 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 has not changed since
       the time it names. All three date formats  HTTP  allows  are  read;  one
       which cannot 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 is
       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 EXTENSION TYPE
        Answer  for a file with that extension with that content type, in addi-
       tion 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  car-
       ries 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  did  not
       name.
        ** crosses them, and is 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 ar-
       gument holding one - a path or location built with $1, a regular expres-
       sion anchored with $ - is written in quotes. $$ stands for a single dol-
       lar and is not 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  is  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 be-
       fore 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  Con-
       nection:  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 chun-
       ked body a 1.1 client can read, so the pages of  admin  are  always  the
       last  thing  on a connection. A request body which cannot 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 is refused rather than
       corrected when it is 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  new-
       line  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  inter-
       face, 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/lo-
       cal/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

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

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

3proxy 0.9                          May 2026                      3proxy.cfg(5)

Generated by dwww version 1.16 on Thu Nov 12 21:45:39 CET 2026.