3APA3A 3proxy Tiny Proxy Server HowTo
Under construction, very incomplete
- Compilation
  - How to compile 3proxy with Visual C++
    Extract source code files from 3proxy.tgz (with WinZip or another utility). For 64-bit Windows use:
```
nmake /f Makefile.msvc64
```
    For ARM64 Windows use:
```
nmake /f Makefile.msvcARM64
```
    Binaries will be placed in the bin/ directory.
  - How to compile 3proxy with CMake
    CMake provides a cross-platform build system. It works on Windows (MSVC, MinGW), Linux, macOS, and BSD.
    Basic build steps:
```
mkdir build
cd build
cmake ..
cmake --build .
```
    On Windows with Visual Studio, you can also generate a solution file:
```
cmake -G "Visual Studio 17 2022" -A x64 ..
cmake --build . --config Release
```
    Optional features can be controlled with cmake options:
```
cmake -D3PROXY_USE_OPENSSL=ON -D3PROXY_USE_PCRE2=ON ..
```
    Available options: 3PROXY_USE_OPENSSL, 3PROXY_USE_PCRE2, 3PROXY_USE_PAM, 3PROXY_USE_ODBC.
    Binaries will be placed in the build/bin/ directory.
  - How to compile 3proxy with GCC under Unix/Linux
- Proxy server installation and removal
  - How to install/remove 3proxy under Windows NT/2000/XP
    Unpack 3proxy.zip to any directory, for example c:\Program Files\3proxy. If needed, create a directory for storing log files, ODBC sources, etc. Create 3proxy.cfg in the 3proxy installation directory (see Server configuration). Now, start a command prompt (cmd.exe). Change to the 3proxy installation directory and run 3proxy.exe --install:
```
D:\>C:
C:\>cd C:\Program Files\3proxy
C:\Program Files\3proxy>3proxy.exe --install
```
    Now, you should have the 3proxy service installed and running. If the service is not started, run 3proxy.exe manually and correct all errors.
    To remove 3proxy, run 3proxy --remove:
```
D:\>C:
C:\>cd C:\Program Files\3proxy
C:\Program Files\3proxy>net stop 3proxy
C:\Program Files\3proxy>3proxy.exe --remove
```
    Now you can simply remove the 3proxy installation directory.
  - How to install/remove 3proxy under Unix/Linux
    Using Makefile:
    Compile 3proxy (see Compilation) then run:
```
sudo make install
```
    This installs binaries to /usr/local/3proxy/sbin/, configuration to /etc/3proxy/, and sets up chroot directories. Default configuration file is /etc/3proxy/3proxy.cfg.
    
    Using CMake:
```
mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .
```
    Using pre-built packages from GitHub:
    Download .deb or .rpm packages from GitHub Releases.
    For Debian/Ubuntu:
```
sudo dpkg -i 3proxy_*.deb
```
    For RHEL/CentOS/Fedora:
```
sudo rpm -i 3proxy-*.rpm
```
    Add 3proxy to the system startup scripts or use systemd:
```
sudo systemctl enable 3proxy
sudo systemctl start 3proxy
```
  - How to install/remove 3proxy under macOS
    Using CMake (recommended):
```
mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .
```
    This installs:
    - Binaries to /usr/local/bin/
    - Configuration to /etc/3proxy/
    - Plugins to /usr/local/lib/3proxy/
    - Launchd plist to /Library/LaunchDaemons/org.3proxy.3proxy.plist
    Using Makefile:
```
ln -sf Makefile.FreeBSD Makefile
make
sudo make install
```
    This installs binaries to /usr/local/3proxy/bin/ and configuration to /usr/local/etc/3proxy/.
    
    Service management with launchd:
    After installation via cmake, the service can be managed with launchctl:
```
# Load and start the service
sudo launchctl load /Library/LaunchDaemons/org.3proxy.3proxy.plist

# Stop the service
sudo launchctl stop org.3proxy.3proxy

# Start the service
sudo launchctl start org.3proxy.3proxy

# Unload and disable the service
sudo launchctl unload /Library/LaunchDaemons/org.3proxy.3proxy.plist
```
    The service runs as user proxy (created during installation). Configuration file: /etc/3proxy/3proxy.cfg
  - How to use 3proxy with Docker
    Using pre-built images from GitHub Container Registry:
```
docker pull ghcr.io/3proxy/3proxy:latest
```
    Building Docker images:
    Two Dockerfiles are provided:
    - Dockerfile.minimal - minimal static build, no plugins, configuration from stdin:
```
docker build -f Dockerfile.minimal -t 3proxy.minimal .
docker run -i -p 3129:3129 --name 3proxy 3proxy.minimal
```
      Then enter configuration followed by "end" command.
    - Dockerfile.full - full build with plugins (SSL, PCRE, Transparent):
```
docker build -f Dockerfile.full -t 3proxy.full .
docker run -p 3129:3129 -v /path/to/config:/usr/local/3proxy/conf 3proxy.full
```
      The configuration file must be placed at /path/to/config/3proxy.cfg.
    By default, 3proxy runs in chroot environment with uid/gid 65535. Use nserver in config for DNS resolution in chroot. For non-chroot execution, mount config to /etc/3proxy.
- Server configuration
  - How to make 3proxy start
    A valid configuration file is required.
  - How to make limitations (access, bandwidth, traffic, connections) work
    The most probable reasons for non-working limitations: 'auth none' or no auth is used. For any ACL-based feature, one of 'iponly', 'nbname', or 'strong' auth is required. The sequence of commands may be invalid. Commands are executed one-by-one, and 'proxy', 'tcppm', 'socks', or another service commands must follow a valid configuration. An invalid sequence of ACLs. The first matching ACL is used (except for internal redirections, see below). If an ACL contains at least one record, the last record is assumed to be 'deny *'.
  - How to make 3proxy run as a service
    Possible reasons for 3proxy starting manually but failing to start as a service:
    - there are relative paths in the configuration file for included files, log files, etc. Always use absolute paths. For example, $"c:\3proxy\networks.local" instead of $networks.local. For debugging, remove 'service' and 'daemon', log to stdout, and try to execute 3proxy from the command line from a different directory (for example, from the disk root).
    - the SYSTEM account doesn't have access to the executable file, configuration files, log files, etc.
    - the configuration file is not located in the default path (3proxy.cfg in the same location as 3proxy.exe). For an alternative configuration file location, use
```
3proxy --install full_path_to_configuration_file
```
    - the user has no rights to install or start the service
    - the service is already installed and/or started
    How to understand internal and external
    Both internal and external IPs are IPs of the host running 3proxy itself. This configuration option is useful in situations where 3proxy is running on a border host with 2 (or more) connections: e.g., LAN and WAN with different IPs
```
     LAN connection +-------------+ Internet connection
LAN <-------------->| 3proxy host |<-------------------> INTERNET
                   ^+-------------+^
	           |               |
              Internal IP       External IP
```
    If 3proxy is used on a host with a single connection, both internal and external are usually the same IP.
    The internal interface should exist and be UP at the moment 3proxy is started and should never be disconnected/DOWN. If this interface is periodically disconnected (e.g., a direct link between 2 hosts), do not specify an internal address or use 0.0.0.0 instead. In this case, if you have 2 or more interfaces, you must use a firewall (preferably) or 3proxy ACLs to avoid an open proxy situation.
    The external IP (if specified) must exist at the moment 3proxy serves a client request. If the external interface is not specified (or 0.0.0.0), the system selects the external IP. It may be possible to access resources of the internal network; to prevent this, use ACLs. In addition, SOCKSv5 will not support the BIND operation, which is required for incoming connections (this operation is quite rarely implemented in SOCKSv5 clients and is usually not required). In case of a dynamic address, do not specify external or use external 0.0.0.0, or, if an external address is required, create a script to determine the current external IP and save it to a file, and use external "$path_to_file" with the "monitor" command to automatically reload the configuration on address change.
  - How to make ODBC logging work?
    Check that you are using a system DSN. Check that the SQL request is valid. The best way to check is to use file or stdout logging, get the SQL request from the log file or console, and execute this request manually. Under Unix, you may also want to adjust the 'stacksize' parameter.
  - How to make IPv6 work
    The proxy cannot access a destination directly over IPv6 if the client requests an IPv4 address. To access an IPv6 destination, either an IPv6 address or a hostname must be used in the request. The best solution is to enable the option to resolve hostnames via the proxy on the client side.
  - How to fix 3proxy crashes
    The default stacksize may be insufficient if some non-default plugins are used (e.g., PAM and ODBC on Linux) or if compiled on some platforms with invalid system-defined values (a few versions of FreeBSD on amd64). The problem can be resolved with the 'stacksize' command or '-S' option starting with 3proxy 0.8.4.
  - Where to find a configuration example
    A server configuration example, 3proxy.cfg.sample, is included in every 3proxy distribution.
  - How to set up logging
    3proxy can log to stdout, a file, an ODBC datasource, or syslog (Unix/Linux/Cygwin only). To use ODBC under Unix/Linux, you must compile 3proxy with Unix ODBC libraries; see Compilation. You can control logging from 3proxy.cfg for all services, or you can control logging for an individual service. For example, /usr/local/sbin/socks -l/var/log/socks.log starts a SOCKS proxy with logging to a file. For the universal proxy (3proxy), log file rotation and archiving are supported. The log type is defined with the "log" configuration file command or with the -l switch on individual service invocation. log or -l with no argument is stdout logging.
```
	log filename
```
    and
```
	-lfilename
```
    specify a filename for logging.
```
	log @ident
```
    and
```
	-l@ident
```
    specify an ident for syslog logging. If the filename within the "log" command contains '%' characters, it is processed as a format specifier (see "logformat"). E.g., log c:\3proxy\logs\%y%m%d.log D creates a file like c:\3proxy\logs\060729.log; the date is generated based on local time.
```
	log &connstring
```
    specifies an ODBC connection string; connstring is in the format datasource,username,password (the last two are optional if the datasource does not require or already has authentication information). Also, you must specify logformat to build the SQL query to insert a record into the log; see How to set up logging format
    
    Rotation and archiving may be set up with log, rotate, and archiver commands.
```
	log filename LOGTYPE
```
    sets the rotation type. LOGTYPE may be:
    - M, monthly
    - W, weekly
    - D, daily
    - H, hourly
    - C, minutely
```
	rotate NUMBER
```
    specifies the number of files in rotation (i.e., how many files to keep).
```
	archiver EXT COMMAND PARAMETERS
```
    Sets an external archiver. EXT is the extension of archived files (for example, zip, gz, Z, rar, etc.). COMMAND and PARAMETERS are the command to execute and its command-line parameters. The original file is not deleted by 3proxy; this work is left for the archiver. You can pass the original filename to the archiver with the %F macro and the archive filename with %A. Examples are located in 3proxy.cfg.sample
  - How to set up logging format
    Since version 0.3, the log format may be set with the "logformat" command. The first symbol of the log format specifies the format of the date and time and should be L (LOCAL) or G (GMT - Greenwich Meridian Time). The format string may contain some macro substitutions:
    - %y - Year (2 digits)
    - %Y - Year (4 digits)
    - %m - Month (2 digits)
    - %o - Month (3-letter abbreviation)
    - %d - Day (2 digits)
    - %H - Hour (2 digits)
    - %M - Minute (2 digits)
    - %S - Second (2 digits)
    - %t - Timestamp (seconds since January 1, 1970 00:00:00 GMT)
    - %. - Milliseconds
    - %z - Timezone in mail format (from GMT, '+' east, '-' west HHMM). For example, Moscow winter time is +0300.
    - %U - Username ('-' if unknown).
    - %N - Service name (PROXY, SOCKS, POP3P, etc.)
    - %p - Service port
    - %E - Error code (see Log error codes reference)
    - %C - client IP
    - %c - client port
    - %R - target IP
    - %r - target port
    - %e - external IP address used to establish the connection
    - %Q - requested IP
    - %q - requested port
    - %I - bytes received from the target
    - %O - bytes sent to the target
    - %n - hostname from the request
    - %h - hops before the target (if redirection or chaining is used); see How to use chains and parent proxies)
    - %T - service-specific text (for example, the requested URL). %X-YT, where X and Y are positive numbers, only displays fields (space-delimited) X to Y of the text. An example is %1-2T.
    Example:
```
logformat "L%t.%. %N.%p %E %U %C:%c %R:%r %O %I %h %T"
```
    generates something like
    1042454727.0296 SOCK4.1080 000 3APA3A 127.0.0.1:4739 195.122.226.28:4739 505 18735 1 GET http://3proxy.org/ HTTP/1.1
    (no line breaks)
    
    If ODBC is used, logformat should specify the SQL command to insert a record into the log, for example:
```
logformat "-\'+_GINSERT INTO proxystat  VALUES (%t, '%c', '%U', %I)"
```
    (no line breaks)
    -\'+_ instructs to replace characters \ and ' with _
  - How to use log analyzers with 3proxy
    Just make the format of 3proxy logs compatible with a format supported by your favorite log analyzer. Examples of compatible logformats are:
    For Squid access.log:
    "- +_G%t.%. %D %C TCP_MISS/200 %I %1-1T %2-2T %U DIRECT/%R application/unknown"
    or, a more compatible format without %D:
```
"- +_G%t.%.      1 %C TCP_MISS/200 %I %1-1T %2-2T %U
 DIRECT/%R application/unknown"
```
    ISA 2000 proxy WEBEXTD.LOG (fields are TAB-delimited):
```
"-	+ L%C	%U	Unknown	Y	%Y-%m-%d	%H:%M:%S
	w3proxy	3PROXY	-	%n	%R	%r	%D
	%O	%I	http	TCP	%1-1T	%2-2T	-	-
	%E	-	-	-"
```
    ISA 2004 proxy WEB.w3c (fields are TAB-delimited):
```
"-	+ L%C	%U	Unknown	%Y-%m-%d	%H:%M:%S
	3PROXY	-	%n	%R	%r	%D	%O
	%I	http	%1-1T	%2-2T	-	%E	-
	-	Internal	External	0x0	Allowed"
```
    ISA 2000/2004 firewall FWSEXTD.log (fields are TAB-delimited):
```
"-	+ L%C	%U	unnknown:0:0.0	N	%Y-%m-%d
	%H:%M:%S	fwsrv	3PROXY	-	%n	%R	%r
	%D	%O	%I	%r	TCP	Connect	-	-
	-	%E	-	-	-	-	-"
```
    HTTPD standard log (Apache and others):
    "-""+_L%C - %U [%d/%o/%Y:%H:%M:%S %z] ""%T"" %E %I"
    or a more compatible format without the error code:
    "-""+_L%C - %U [%d/%o/%Y:%H:%M:%S %z] ""%T"" 200 %I"
  - How to start any of the proxy services (HTTP, SOCKS, etc.)
    3proxy is distributed in 2 variants: as a set of standalone modules (proxy, socks, pop3p, tcppm, udppm) and as a universal proxy server. These services are absolutely independent, and if you use 3proxy, you don't need any of the standalone modules.
    Standalone modules are only configurable via the command line interface, while 3proxy uses a configuration file. Many functions, such as ODBC logging, log rotation, access control, etc., are only available in 3proxy, not in standalone proxies. A standalone module may be started from the command line, for example:
    $/sbin/socks -l/var/log/socks.log -i127.0.0.1
    Starts a SOCKS server bound to localhost IP, port 1080, with logging to /var/log/socks.log. You can get help for any standalone service with the -? command line option.
    If 3proxy is used, you should start all services in the 3proxy.cfg file. 3proxy.cfg is executed by 3proxy as a batch file. An example of 3proxy.cfg and command syntax can be found in 3proxy.cfg.sample.
    log /var/log/3proxy.log D rotate 30 internal 127.0.0.1 external 192.168.1.1 proxy socks -p3129 pop3p
    Starts 3 services: HTTP PROXY, SOCKS, and POP3 PROXY. Each listens on the localhost interface with the default port (3128 for HTTP, 1080 for SOCKS, and 110 for POP3P) except socks, which is started with port 3129. All logs are in the file /var/log/3proxy.log (with daily date modification and rotation). The 30 most recent files are stored.
  - How to bind a service to a specific interface and port?
    The -i option specifies the internal interface; -p specifies the listening port. No spaces are allowed. To bind the 'proxy' service to port 8080 on interfaces 192.168.1.1 and 192.168.2.1, use:
    proxy -p8080 -i192.168.1.1 proxy -p8080 -i192.168.2.1
  - How to resolve names through a parent proxy
- Client configuration
- Administering and information analysis
  - How to obtain latest 3proxy version
    The latest version of 3proxy may be obtained here. A new version may have changes and incompatibilities with the previous one in file formats or commands. Please read the CHANGELOG file and other documentation before installing a new version.
  - How to control 3proxy service under Windows NT/2000/XP
    If installed as a system service, 3proxy understands Windows service commands for START, STOP, PAUSE, and RESUME. If the service is PAUSEd, no new connections are accepted while older connections are processed. Currently, there is no support for dynamic configuration changes, so you have to restart the service completely if you have changed any configuration. You can control the 3proxy service via "Services" administration or via the "net" command:
    net start 3proxy net stop 3proxy net pause 3proxy net continue 3proxy
  - Log error codes reference
    
    0 - Operation successfully completed (connection was closed by one of the peers)
    1-9 - AUTHENTICATION ERRORS
    1 - Access denied by ACL (deny)
    2 - Redirection (should not appear)
    3 - No ACL found, denied by default
    4 - auth=strong and no username in request
    5 - auth=strong and no matching username in configuration
    6 - User found, wrong password (cleartext)
    7 - User found, wrong password (crypt)
    8 - User found, wrong password (NT)
    9 - Redirection data not found (should not appear)
    10 - Traffic limit exceeded
    11-19 - CONNECTION ERRORS
    11 - failed to create socket()
    12 - failed to bind()
    13 - failed to connect()
    14 - failed to getpeername()
    20-29 - COMMON ERRORS
    21 - memory allocation failed
    30-39 - CONNECT PROXY REDIRECTION ERRORS
    31 - failed to request HTTP CONNECT proxy
    32 - CONNECT proxy connection timed out or wrong reply
    33 - CONNECT proxy fails to establish connection
    34 - CONNECT proxy timed out or closed connection
    40-49 - SOCKS4 PROXY REDIRECTION ERRORS
    50-69 - SOCKS5 PROXY REDIRECTION ERRORS
    70-79 PARENT PROXY CONNECTION ERRORS (identical to 1x)
    90-99 - established connection errors
    since 0.9
    90 - unexpected system error (should not happen)
    91 - unexpected poll error (should not happen)
    92 - connection terminated by timeout (see timeouts)
    93 - connection terminated by ratelimit-related timeout or due to errors limit
    94 - connection termination by server or client with unsent data
    95 - dirty connection termination by client (or networking issue)
    96 - dirty connection termination by server (or networking issue)
    97 - dirty connection termination by both client and server (probably networking issue)
    prior to 0.9:
    90 - socket error or connection broken
    91 - TCP/IP common failure
    92 - connection timed out
    93 - error on reading data from server
    94 - error on reading data from client
    95 - timeout from bandlimin/bandlimout limitations
    96 - error on sending data to client
    97 - error on sending data to server
    98 - server data limit (should not appear)
    99 - client data limit (should not appear)
    100 - HOST NOT FOUND
    200-299 - UDP portmapper specific bugs
    300-399 - TCP portmapper specific bugs
    400-499 - SOCKS proxy specific bugs
    500-599 - HTTP proxy specific bugs
    600-699 - POP3 proxy specific bugs
    999 - NOT IMPLEMENTED
- How to ask a question not in How To?
  Ask it in Github. Please read this document before asking a question.