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). Use nmake /f Makefile.msvc command
  - How to compile 3proxy with Intel C Compiler under Windows
    See How to compile 3proxy with Visual C++ Use Makefile.intl instead of Makefile.msvc
  - How to compile 3proxy with GCC under Windows
  - How to compile 3proxy with GCC under Unix/Linux
- How to compile 3proxy with Compaq C Compiler 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 directory for storing log files, ODBC sources, etc. Create 3proxy.cfg in the 3proxy installation directory (See Server configuration). Add
```
service
```
  string into 3proxy.cfg. Now, start command prompt (cmd.exe). Change directory to 3proxy installation and run 3proxy.exe --install:
```
D:\>C:
C:\>cd C:\Program Files\3proxy
C:\Program Files\3proxy>3proxy.exe --install
```
  Now, you should have 3proxy service installed and running. If service is not started, remove "service" string from 3proxy.cfg, 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 3proxy installation directory.
- How to install/remove 3proxy under Windows 95/98/ME
  Unpack 3proxy.zip to any directory, for example c:\Program Files\3proxy. If needed, create directory for storing log files, ODBC sources, etc. Create 3proxy.cfg in the 3proxy installation directory (See Server configuration). Remove string
```
service
```
  from 3proxy.cfg and add
```
daemon
```
  if you want 3proxy to run in background. Create shortcut for 3proxy.exe and place it in autostart or add to registry with regedit.exe:
  HKLM\Software\Microsoft\Windows\CurrentVersion\Run
  Type: String
  3proxy = "c:\Program Files\3proxy.exe" "C:\Program Files\3proxy.cfg"
  You must use quotes if path contains space. If neccessary, restart Windows. If service is not started, check log. Remove "daemon" command from 3proxy.cfg, start 3proxy.exe manually and correct all errors.
- How to install/remove 3proxy under Unix/Linux
  Complie 3proxy (see Compilation). Copy executables to any appropriate location (for example /usr/local/3proxy/sbin for servers and /usr/local/3proxy/bin for utilities). Create /usr/local/etc/3proxy.cfg. (see Server configuration). You can change default configuration file location by specifing configuration file in 3proxy command line. Add 3proxy to system startup scripts.
Server configuration
- Where to find configuration example
  Server configuration example 3proxy.cfg.sample is in any 3proxy distribution.
- How to set up logging
  3proxy can log to stdout, file, ODBC datasource and syslog (Unix/Linux/Cygwin only). For using 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 of individual service, for example /usr/local/sbin/socks -l/var/log/socks.log starts SOCKS proxy with logging to file. For universal proxy (3proxy) log file rotation and archiving is supported. Log type is defined with "log" configuration file command or with -l switch on individual service invokation. log or -l is stdout logging.
```
	log filename
```
  and
```
	-lfilename
```
  specify filename for logging
```
	log @ident
```
  and
```
	-l@ident
```
  specify ident for syslog logging
```
	log &connstring
```
  specifies ODBC connection string, connstring is in format datasource,username,password (2 last are optional of datasource does not require or already has authentication information). Also, you must specify logformat to build SQL query, to insert recod into log, see How to setup logging format
  
  Rotation and archiving may be set up with log, rotate и archiver commands
```
	log filename LOGTYPE
```
  sets rotation type. LOGTYPE may be:
  - M, monthely
  - W, weekly
  - D, daily
  - H, hourly
  - С, minutely
```
	rotate NUMBER
```
  specifies number of files in rotation (that is how many files to keep).
```
	archiver EXT COMMAND PARAMETERS
```
  Sets external archiver. EXT is extention of archived files (for example zip, gz, Z, rar etc) COMMAND and PARAMETERS are command to execute and command line PARAMETERS. Originale file is not deleted by 3proxy, this work is left for archiver. You can pass original filename to archiver with %F macro and archive filename with %A. Examples are located in 3proxy.cfg.sample
- How to setup logging format
  Since 0.3 version log format may be set with "logformat" command. First symbol of log format specifies format of date and time and should be L (LOCAL) or G (GMT - Grinwitch Meridian Time). Format string may contains some macro substitutions:
  - %y - Year (2 digits)
  - %Y - Year (4 digits)
  - %m - Month (2 digits)
  - %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
  - %I - bytes received from target
  - %O - bytes sent to target
  - %h - hops before target (if redirection or chaning is used). see How to use chains and parent proxies)
  - %T - service specific text (for example URL requested).
  Пример:
```
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://www.security.nnov.ru/ HTTP/1.1
  (no line breaks)
  
  If ODBC used, logformat should specify SQL command, to insert record into log, for example
  logformat "GINSERT INTO proxystat VALUES (%t, '%c', '%U', %I)"
  (no line breaks)
- How to start any of proxy services (HTTP, SOCKS etc)
  3proxy is distributed in 2 variants: as a set of standalone modules (proxy, socks, pop3p, tcppm, udppm) and as universal proxy server. These services are absolutely independant, and if you use 3proxy you needn't any of standalone modules.
  Standalone modules are only configurable via command line interface while 3proxy uses configuration file. Many functions, such as ODBC logging, log rotation, access control, etc are only available in 3proxy, not in standalone proxies. Standalone module may be started from command line, for example:
```
$/sbin/socks -l/var/log/socks.log -i127.0.0.1
```
  Starts SOCKS server binded to localhost ip, port 1080 with logging to /var/log/socks.log. You can get help for any standalone service with -? command line option.
  If 3proxy is used you should start all services in 3proxy.cfg file. 3proxy.cfg is executed by 3proxy as a batch file. Example of 3proxy.cfg and command syntaxys 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 localhost interface with default port (3128 for HTTP, 1080 for SOCKS and 110 for POP3P) except socks started with port 3129. All logs are in file /var/log/3proxy.log (with daily date modification and rotation). 30 last files are stored.
- How to limit service access
Client configuration
Administering and information analisys
- How to obtain latest 3proxy version
  Latest version of 3proxy may be obtained here. New version may have changes and incompatibilities with previous one in files format or commands. Please, read CHANGELOG file and another documentation before installing new version.
- How to control 3proxy service under Windows NT/2000/XP
  If installed as system service, 3proxy understands Windows service commands for START, STOP, PAUSE and RESUME. If service is PAUSEd, no new connections are accepted while older connections are processed. Currently there is no support for dynamic configuration change, so, you have to restart service completely if you have changed any configuration. You can control 3proxy service via "Services" administration ot via "net" command:
```
	net start 3proxy
	net stop 3proxy
	net pause 3proxy
	net continue 3proxy
```
- Log error codes reference
  - 0 - Operation successfully complited (connection was closed by one of 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 - CONNECTION BROKEN ERRORS
  - 91 - connection was broken due to traffic limit
  - 91 - connection was broken by server
  - 92 - failed to send data
  - 93 - connection was broken by client
  - 94 - socket error
  - 97 - timeout
  - 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 quiestion not in How To?
Ask it in 3proxy phorum. Don't try to ask something you just misunderstood this How To, because you do not get better answer.

$Id: howtoe.html,v 1.7 2005/04/25 13:58:19 vlad Exp $