-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathhowtoe.html
More file actions
2302 lines (2189 loc) · 92.4 KB
/
Copy pathhowtoe.html
File metadata and controls
2302 lines (2189 loc) · 92.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html lang="en">
<head>
<meta name="theme-color" content="#ffffff">
<meta name=viewport content="width=device-width, initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="shortcut icon" href="/favicon.ico" type="type=image/x-icon">
<link rel="stylesheet" href="/style/bootstrap.min.css">
<script src="/js/jquery.min.js"></script>
<script src="/js/bootstrap.bundle.min.js"></script>
<link rel="stylesheet" href="/style/main.css">
<title>
Soft:3proxy:HowTo </title>
<meta name="Description" content="3proxy freeware proxy server for Windows and Unix. HTTP, SOCKS, FTP, POP3">
<meta name="keywords" content="3proxy, proxy, proxy server, free, freeware, socks, socks v5">
<meta NAME="Author" content="3APA3A">
</head>
<body>
<nav class="navbar sticky-top navbar-expand-lg navbar-dark bg-dark">
<a class="navbar-brand" href="/"><span class="nav-logotext"><span class="nav-logotext1">3</span> PROXY</span></a>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNavDropdown" aria-controls="navbarNavDropdown" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarNavDropdown">
<ul class="navbar-nav">
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdownMenuLink" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Downloads
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
<a class="dropdown-item" href="/download/">Downloads</a>
<a class="dropdown-item" href="/download/stable/">Stable version</a>
<a class="dropdown-item" href="/download/devel/">Development version</a>
<a class="dropdown-item" href="https://github.com/z3APA3A/3proxy">GIT</a>
<a class="dropdown-item" href="https://hub.docker.com/repository/docker/3proxy/3proxy">Docker</a>
</div>
</li>
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdownMenuLink" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
Documentation
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
<a class="dropdown-item" href="/documents/">Documentation</a>
<a class="dropdown-item" href="/doc/">Manual</a>
<a class="dropdown-item" href="/howtoe.html">HowTo</a>
<a class="dropdown-item" href="/plugins/">Plugins</a>
</div>
</li>
<li class="nav-item dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdownMenuLink" data-bs-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
About
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdownMenuLink">
<a class="dropdown-item" href="/">About</a>
<a class="dropdown-item" href="https://github.com/z3APA3A/3proxy/issues">Questions and issues</a>
<a class="dropdown-item" href="/donations/">Help the project</a>
</div>
</li>
</ul>
</div>
<div class="lang-toogle nav navbar navbar-right navbar-dark bg-dark">
<a href="" lang="ru" id="lang-switch">RU</a><span>|</span><span lang="en">EN</span>
</div>
<script>document.getElementById('lang-switch').href='https://3proxy.ru'+location.pathname;</script>
</nav>
<div class="container container-content">
<div class="info-block">
<div class="alert alert-warning">
<a href="#" class="close close-info-block" data-bs-dismiss="alert" aria-label="close">×</a>
<strong>
Few antiviral products inadequately detect 3proxy as Trojan.Daemonize,
Backdoor.Daemonize, etc and many detect 3proxy as a PUA (potentially unwanted program).
It may cause browser warning on download page.
3proxy is not trojan or backdoor and contains
no functionality except described in documentation. Clear explanation of this
fact is given, for example, in
<A class="tiny" HREF="https://www.microsoft.com/en-us/wdsi/threats/malware-encyclopedia-description?Name=Program:Win32/TinyProxy" target="_blank">Microsoft</A>'s
article.
</strong>
</div>
</div>
<script type="text/javascript">
$(document).ready(function() {
// info-block
if (localStorage.getItem('show-info-block') == null) {
$('.info-block').show('slow');
} else {
$('.info-block').hide('slow');
}
$('.close-info-block').on('click', function(){
localStorage.setItem('show-info-block', '0');
})
// code highlighting
$('pre code').each(function(i, block) {
hljs.highlightBlock(block);
});
});
</script><ul>
<li>3APA3A 3proxy Tiny Proxy Server HowTo
<br>Under construction, very incomplete
<ul>
<li><A HREF="#COMPILE">Compilation</a>
<ul>
<li><A HREF="#MSVC">How to compile 3proxy with Visual C++</a>
<li><A HREF="#CMAKE">How to compile 3proxy with CMake</a>
<li><A HREF="#GCCUNIX">How to compile 3proxy with GCC under Unix/Linux</a>
</ul>
<li><A HREF="#INSTALL">Proxy server installation and removal</a>
<ul>
<li><A HREF="#INSTNT">How to install/remove 3proxy under Windows NT/2000/XP</a>
<li><A HREF="#INSTUNIX">How to install/remove 3proxy under Unix/Linux</a>
<li><A HREF="#INSTMACOS">How to install/remove 3proxy under macOS</a>
<li><A HREF="#INSTDOCKER">How to use 3proxy with Docker</a>
</ul>
<li><A HREF="#SERVER">Server configuration</a>
<ul>
<li><a href="#NOTHING">How to make 3proxy start</a></li>
<li><a href="#LIMITS">How to make limitations (access, bandwidth, traffic, connections) work</a></li>
<li><a href="#SERVICE">How to make 3proxy run as a service</a></li>
<li><a href="#INTEXT">How to understand internal and external</a></li>
<li><a href="#ODBC">How to make ODBC logging work?</a></li>
<li><a href="#IPV6">How to make IPv6 work</a></li>
<li><a href="#CRASH">How to fix 3proxy crashes</a></li>
<li><A HREF="#SAMPLE">Where to find a configuration example</a>
<li><A HREF="#LOGGING">How to set up logging</a>
<li><A HREF="#LOGFORMAT">How to set up logging format</a>
<li><A HREF="#LOGANALIZERS">How to use log analyzers with 3proxy</a>
<li><A HREF="#LAUNCH">How to start any of the proxy services (HTTP, SOCKS, etc.)</a>
<li><a href="#BIND">How to bind a service to a specific interface or port</a>
<li><a href="#NAMES">How to resolve names through a parent proxy</a></li>
<li><a href="#ISFTP">How to set up an FTP proxy</a></li>
<li><a href="#TLSPR">How to set up an SNI proxy (tlspr)</a></li>
<li><a href="#DNSPR">How to set up a DNS proxy (dnspr)</a></li>
<li><a href="#HTTPSRV">How to serve pages with the built-in HTTP server (httpsrv)</a></li>
<li><a href="#SSLPLUGIN">How to set up TLS/SSL (https proxy, mTLS)</a></li>
<li><a href="#CERTIFICATES">How to create CA and certificates for SSL</a></li>
<li><a href="#PCRE">How to use PCRE filtering (regular expressions)</a></li>
<li><a href="#TRANSPARENT">How to proxy transparently</a></li>
<li><A HREF="#AUTH">How to limit service access</a>
<li><A HREF="#USERS">How to create a user list</a>
<li><A HREF="#ACL">How to limit user access to resources</a>
<li><A HREF="#REDIR">How to manage redirections</a>
<li><a href="#SOCKSREDIR">How to manage local redirections</a>
<li><A HREF="#ROUNDROBIN">How to balance traffic between multiple external channels?</a>
<li><A HREF="#CHAIN">How to manage proxy chains</a>
<li><A HREF="#BANDLIM">How to limit bandwidth</a>
<li><A HREF="#TRAFLIM">How to limit traffic amount</a>
<li><a href="#TRAF">How to fix incorrect traffic accounting</a>
<li><A HREF="#NETLIST">How to build network lists</a>
<li><a href="#NSCACHING">How to configure name resolution and DNS caching</a>
<li><a href="#IPV6">How to use IPv6</a>
<li><a href="#CONNBACK">How to use connect back</a>
<li><a href="#HAPROXY">How to use HAProxy PROXY protocol</a>
<li><a href="#MAXSEG">How to set TCP maximum segment size (MSS)</a>
</ul>
<li><A HREF="#CLIENT">Client configuration</a>
<li><A HREF="#ADMIN">Administering and information analysis</a>
<ul>
<li><A HREF="#NEWVERSION">How to obtain the latest 3proxy version</a>
<li><A HREF="#NTSERVICE">How to control the 3proxy service under Windows NT/2000/XP</a>
<li><A HREF="#ERRORS">Log error codes reference</a>
</ul>
<li><A HREF="#QUEST">How to ask a question not in How To?</a>
</ul>
<br>
<ul>
<hr>
<li><A NAME="COMPILE">Compilation</a>
<p>
<ul>
<li><A NAME="MSVC">How to compile 3proxy with Visual C++</a>
<p>
Extract source code files from 3proxy.tgz (with WinZip or another utility) or use git.
<pre>
nmake /f Makefile.msvc
</pre>
Binaries will be placed in the <code>bin/</code> directory.
</p>
<li><A NAME="CMAKE">How to compile 3proxy with CMake</a>
<p>
CMake provides a cross-platform build system. It works on Windows (MSVC, MinGW), Linux, macOS, and BSD.
<br>Basic build steps:
<pre>
mkdir build
cd build
cmake ..
cmake --build .
</pre>
On Windows with Visual Studio, you can also generate a solution file:
<pre>
cmake -G "Visual Studio 17 2022" -A x64 ..
cmake --build . --config Release
</pre>
Optional features can be controlled with cmake options:
<pre>
cmake -D3PROXY_USE_OPENSSL=ON -D3PROXY_USE_PCRE2=ON ..
</pre>
Available options: 3PROXY_USE_OPENSSL, 3PROXY_USE_PCRE2, 3PROXY_USE_PAM, 3PROXY_USE_ODBC.
<br>Binaries will be placed in the <code>build/bin/</code> directory.
</p>
<li><A NAME="GCCUNIX">How to compile 3proxy with GCC under Unix/Linux</a></li>
<p>
For Linux, use:
<pre>
ln -sf Makefile.Linux Makefile
make
</pre>
For FreeBSD, use:
<pre>
ln -sf Makefile.FreeBSD Makefile
make
</pre>
For other Unix-like systems, use Makefile.unix. On BSD-derived systems, make
sure to use GNU make; sometimes it's called gmake instead of make.
<br>Compilation is tested under FreeBSD, NetBSD, OpenBSD, Linux, Solaris, and macOS.
<br>For ODBC support, install Unix ODBC libraries, remove -DNOODBC from the makefile,
and add the ODBC library to the linker variable.
<br>Binaries will be placed in the <code>bin/</code> directory.
</p>
</ul>
<hr>
<li><A NAME="INSTALL">Proxy server installation and removal</a>
<p>
<ul>
<li><A NAME="INSTNT">How to install/remove 3proxy under Windows NT/2000/XP</a>
<p>
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 <A HREF="#SERVER">Server configuration</a>).
Now, start a command prompt (cmd.exe).
Change to the 3proxy installation directory and run 3proxy.exe --install:
<pre>
D:\>C:
C:\>cd C:\Program Files\3proxy
C:\Program Files\3proxy>3proxy.exe --install
</pre>
Now, you should have the 3proxy service installed and running. If the service is not
started, run 3proxy.exe manually and correct all errors.
</p><p>
To remove 3proxy, run 3proxy --remove:
<pre>
D:\>C:
C:\>cd C:\Program Files\3proxy
C:\Program Files\3proxy>net stop 3proxy
C:\Program Files\3proxy>3proxy.exe --remove
</pre>
Now you can simply remove the 3proxy installation directory.
</p>
<li><A NAME="INSTUNIX">How to install/remove 3proxy under Unix/Linux</a>
<p>
<b>Using Makefile:</b>
<br>Compile 3proxy (see <A HREF="#COMPILE">Compilation</a>) then run:
<pre>
sudo make install
</pre>
This installs binaries to <code>/usr/local/3proxy/sbin/</code>, configuration to <code>/etc/3proxy/</code>,
and sets up chroot directories. Default configuration file is <code>/etc/3proxy/3proxy.cfg</code>.
</p>
<p>
<b>Using CMake:</b>
<pre>
mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .
</pre>
</p>
<p>
<b>Using pre-built packages from GitHub:</b>
<br>Download .deb or .rpm packages from <a href="https://github.com/3proxy/3proxy/releases">GitHub Releases</a>.
<br>For Debian/Ubuntu:
<pre>
sudo dpkg -i 3proxy_*.deb
</pre>
For RHEL/CentOS/Fedora:
<pre>
sudo rpm -i 3proxy-*.rpm
</pre>
</p>
<p>
Add 3proxy to the system startup scripts or use systemd:
<pre>
sudo systemctl enable 3proxy
sudo systemctl start 3proxy
</pre>
</p>
<li><A NAME="INSTMACOS">How to install/remove 3proxy under macOS</a>
<p>
<b>Using CMake (recommended):</b>
<pre>
mkdir build && cd build
cmake ..
cmake --build .
sudo cmake --install .
</pre>
This installs:
<ul>
<li>Binaries to <code>/usr/local/bin/</code></li>
<li>Configuration to <code>/etc/3proxy/</code></li>
<li>Plugins to <code>/usr/local/lib/3proxy/</code></li>
<li>Launchd plist to <code>/Library/LaunchDaemons/org.3proxy.3proxy.plist</code></li>
</ul>
</p>
<p>
<b>Using Makefile:</b>
<pre>
ln -sf Makefile.FreeBSD Makefile
make
sudo make install
</pre>
This installs binaries to <code>/usr/local/3proxy/bin/</code> and configuration to <code>/usr/local/etc/3proxy/</code>.
</p>
<p>
<b>Service management with launchd:</b>
<br>After installation via cmake, the service can be managed with launchctl:
<pre>
# 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
</pre>
The service runs as user <code>proxy</code> (created during installation).
Configuration file: <code>/etc/3proxy/3proxy.cfg</code>
</p>
<li><A NAME="INSTDOCKER">How to use 3proxy with Docker</a>
<p>
<b>Using pre-built images from GitHub Container Registry:</b>
<pre>
docker pull ghcr.io/3proxy/3proxy:latest
</pre>
</p>
<p>
<b>Building Docker images:</b>
<br>Two Dockerfiles are provided:
<ul>
<li><code>Dockerfile.minimal</code> - minimal static build, no plugins, configuration from stdin:
<pre>
docker build -f Dockerfile.minimal -t 3proxy.minimal .
docker run -i -p 3129:3129 --name 3proxy 3proxy.minimal
</pre>
Then enter configuration followed by "end" command.
</li>
<li><code>Dockerfile.full</code> - full build with plugins (SSL, PCRE, Transparent):
<pre>
docker build -f Dockerfile.full -t 3proxy.full .
docker run -p 3129:3129 -v /path/to/config:/usr/local/3proxy/conf 3proxy.full
</pre>
The configuration file must be placed at <code>/path/to/config/3proxy.cfg</code>.
</li>
</ul>
</p>
<p>
By default, 3proxy runs in chroot environment with uid/gid 65535. Use <code>nserver</code> in config for DNS resolution in chroot.
For non-chroot execution, mount config to <code>/etc/3proxy</code>.
</p>
</ul>
<hr>
<li><A NAME="SERVER">Server configuration</a>
<p>
<ul>
<li><a name="NOTHING">How to make 3proxy start</a>
<p>A valid configuration file is required.
<li><a name="LIMITS">How to make limitations (access, bandwidth, traffic, connections) work</a>
<p> 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 *'.
<li><a name="SERVICE">How to make 3proxy run as a service</a>
<p>Possible reasons for 3proxy starting manually but failing to start as a service:
<ul>
<li>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).
<li>the SYSTEM account doesn't have access to the executable file, configuration files,
log files, etc.
<li>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
<pre>
3proxy --install full_path_to_configuration_file
</pre>
<li>the user has no rights to install or start the service
<li>the service is already installed and/or started
</ul>
<p><A NAME="INTEXT">How to understand internal and external</a>
<p>
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
<pre>
LAN connection +-------------+ Internet connection
LAN <-------------->| 3proxy host |<-------------------> INTERNET
^+-------------+^
| |
Internal IP External IP
</pre>
If 3proxy is used on a host with a single connection, both internal and
external are usually the same IP.
<br>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.
<br>
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.
<li><a name="ODBC">How to make ODBC logging work?</a>
<p>
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.
<li><a name="IPV6">How to make IPv6 work</a>
<p> 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.
<li><a name="CRASH">How to fix 3proxy crashes</a>
<p> 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.
<li><A NAME="SAMPLE">Where to find a configuration example</a>
<p>
A server configuration example, 3proxy.cfg.sample, is included in every 3proxy distribution.
</p>
<li><A NAME="LOGGING">How to set up logging</a>
<p>
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 <A HREF="#COMPILE">Compilation</a>.
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.
<pre>
log filename
</pre>
and
<pre>
-lfilename
</pre>
specify a filename for logging.
<pre>
log @ident
</pre>
and
<pre>
-l@ident
</pre>
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.
<pre>
log &connstring;
</pre>
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 <A HREF="#LOGFORMAT">How to set up logging format</a>
</p>
<p>
Rotation and archiving may be set up with log, rotate, and archiver commands.
<pre>
log filename LOGTYPE
</pre>
sets the rotation type. LOGTYPE may be:
<ul>
<li>M, monthly
<li>W, weekly
<li>D, daily
<li>H, hourly
<li>C, minutely
</ul>
<pre>
rotate NUMBER
</pre>
specifies the number of files in rotation (i.e., how many files to keep).
<pre>
archiver EXT COMMAND PARAMETERS
</pre>
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
</p>
<li><A NAME="LOGFORMAT">How to set up logging format</a>
<p>
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:
<ul>
<li> %y - Year (2 digits)
<li> %Y - Year (4 digits)
<li> %m - Month (2 digits)
<li> %o - Month (3-letter abbreviation)
<li> %d - Day (2 digits)
<li> %H - Hour (2 digits)
<li> %M - Minute (2 digits)
<li> %S - Second (2 digits)
<li> %t - Timestamp (seconds since January 1, 1970 00:00:00 GMT)
<li> %. - Milliseconds
<li> %z - Timezone in mail format (from GMT, '+' east, '-' west HHMM). For example, Moscow winter time is +0300.
<li> %U - Username ('-' if unknown).
<li> %N - Service name (PROXY, SOCKS, POP3P, etc.)
<li> %p - Service port
<li> %E - Error code (see <A HREF="#ERRORS">Log error codes reference</a>)
<li> %C - client IP
<li> %c - client port
<li> %R - target IP
<li> %r - target port
<li> %e - external IP address used to establish the connection
<li> %Q - requested IP
<li> %q - requested port
<li> %I - bytes received from the target
<li> %O - bytes sent to the target
<li> %n - hostname from the request
<li> %h - hops before the target (if redirection or chaining is used);
see <A HREF="#CHAIN">How to use chains and parent proxies</a>)
<li> %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.
</ul>
Example:
<pre>
logformat "L%t.%. %N.%p %E %U %C:%c %R:%r %O %I %h %T"
</pre>
generates something like
<p><font face="courier">
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
</font>
<br>(no line breaks)
</p>
<p>
If ODBC is used, logformat should specify the SQL command
to insert a record into the log, for example:
<p><pre>
logformat "-\'+_GINSERT INTO proxystat VALUES (%t, '%c', '%U', %I)"</pre>
<br>(no line breaks)
<br>-\'+_ instructs to replace characters \ and ' with _
</p>
<li><A NAME="LOGANALIZERS">How to use log analyzers with 3proxy</a>
<p>
Just make the format of 3proxy logs compatible with a format supported by your
favorite log analyzer. Examples of compatible logformats are:
<br>
For Squid access.log:
<p><font face="courier">
"- +_G%t.%. %D %C TCP_MISS/200 %I %1-1T %2-2T %U DIRECT/%R application/unknown"
</p>
or, a more compatible format without %D:
<pre>
"- +_G%t.%. 1 %C TCP_MISS/200 %I %1-1T %2-2T %U
DIRECT/%R application/unknown"
</pre>
ISA 2000 proxy WEBEXTD.LOG (fields are TAB-delimited):
<pre>
"- + 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 - - -"
</pre>
ISA 2004 proxy WEB.w3c (fields are TAB-delimited):
<pre>
"- + 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"
</pre>
ISA 2000/2004 firewall FWSEXTD.log (fields are TAB-delimited):
<pre>
"- + L%C %U unknown:0:0.0 N %Y-%m-%d
%H:%M:%S fwsrv 3PROXY - %n %R %r
%D %O %I %r TCP Connect - -
- %E - - - - -"
</pre>
HTTPD standard log (Apache and others):
<p><font face="courier">
"-""+_L%C - %U [%d/%o/%Y:%H:%M:%S %z] ""%T"" %E %I"
</p>
or a more compatible format without the error code:
<p><font face="courier">
"-""+_L%C - %U [%d/%o/%Y:%H:%M:%S %z] ""%T"" 200 %I"
</p>
<li><A NAME="LAUNCH">How to start any of the proxy services (HTTP, SOCKS, etc.)</a>
<p>
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.
<br>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:
<pre>
$/sbin/socks -l/var/log/socks.log -i127.0.0.1
</pre>
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.
</p><p>
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.
<pre>
log /var/log/3proxy.log D
rotate 30
internal 127.0.0.1
external 192.168.1.1
proxy
socks -p3129
pop3p
</pre>
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.
</p>
<li><A NAME="BIND">How to bind a service to a specific interface and port?</a>
<p>
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:
<pre>
proxy -p8080 -i192.168.1.1
proxy -p8080 -i192.168.2.1
</pre>
</p>
<li><a name="NAMES">How to resolve names through a parent proxy</a></li>
<p>
<i>A:</i> Use one of proxy, connect+, socks4+, or socks5+ as the parent type. 3proxy
itself still performs name resolution; it's required, e.g., for ACL matching.
So, if no name resolution must be performed by 3proxy itself, add the command
<pre>
fakeresolve</pre>
This command resolves any name to the 127.0.0.2 address.
</p>
<li><a name="ISFTP"><i>How to set up an FTP proxy</i></a></li>
<p>
There is FTP over HTTP (what is called FTP proxy in browsers) and FTP over FTP
(what is called FTP proxy in file managers and FTP clients). For browsers, there is no need to start an additional
proxy service; 'proxy' supports FTP over HTTP. Configure the 'proxy' port as an FTP proxy. For FTP clients and file
managers, use ftppr. The FTP proxy supports both active and passive mode with the client but always uses passive mode with FTP servers.
</p>
<li><a name="TLSPR"><i>How to set up an SNI proxy (tlspr)</i></a></li>
<p>
An SNI proxy can be used to transparently redirect any TLS traffic with an external router or via local redirection rules. It can also be used
to extract hostnames from TLS to use in ACLs in combination with SOCKS or HTTP(s) proxy and/or the Transparent plugin. It can also be used to require TLS or mTLS between services. The TLS handshake contains no
port information; if tlspr is used as a standalone service, the destination port may be either detected with the Transparent plugin or configured with the -P option (default 443).
Note: tlspr does not support user authentication (there are no credentials in the TLS handshake to authenticate against); use ACLs by IP or a parent proxy with authentication if access control is required.
</p><p>
<b>Options:</b>
</p><pre>
-P <port> - destination port (default: 443)
-c <level> - TLS check level:
0 (default) - allow non-TLS traffic
1 - require TLS, only check client HELLO packet
2 - require TLS, check both client and server HELLO
3 - require TLS, check that the server sends a certificate (not compatible with TLS 1.3)
4 - require mutual TLS, check that the server sends a certificate request and the client sends a certificate (not compatible with TLS 1.3)
-Ximap | -Xpop3 | -Xsmtp - explicit TLS (STARTTLS) mode: tlspr speaks the plaintext
protocol with the client (greeting, STARTTLS command), then upgrades both sides to TLS
</pre>
<p>
<b>Implicit vs explicit TLS:</b>
</p><p>
Implicit TLS means TLS from the first byte of the connection: https (443), imaps (993), SMTP submission secure (submissions) (465).
Explicit TLS means the connection starts in plaintext and is upgraded with a STARTTLS/STLS command: imap (143), SMTP submission (587), pop3 (110).
tlspr supports both: for implicit TLS the destination host is taken from SNI and the port from -P; for explicit TLS
the -X option makes tlspr speak the plaintext protocol phase with the client (greeting, STARTTLS command) before
upgrading both sides to TLS. Example:
</p><pre>
# https (implicit)
tlspr -p443 -P443 -c1
# imaps (implicit)
tlspr -p993 -P993 -c1
# submissions (implicit)
tlspr -p465 -P465 -c1
# imap STARTTLS (explicit)
tlspr -p143 -P143 -Ximap
# submission STARTTLS (explicit)
tlspr -p587 -P587 -Xsmtp
# pop3 STLS (explicit)
tlspr -p110 -P110 -Xpop3
</pre>
<p>
Note: for explicit TLS the protocol services smtpp, imapp and pop3p can be used instead of tlspr -X; they also
support STARTTLS.
</p><p>
<b>Recommended setup - traffic redirection:</b> the most universal configuration is to redirect TLS traffic
(ports 443, 993, 465, 143, 587, 110) to tlspr with external router rules or local redirection (Transparent plugin).
The original destination address and port are preserved, no -P or per-port services are required, and both implicit
and explicit TLS work with the same installation.
</p><pre>
auth iponly
allow *
tlspr -p1443 -c1
</pre>
<p>
with, for example, iptables:
</p><pre>
iptables -t nat -A PREROUTING -p tcp -m multiport --dports 443,993,465 -j REDIRECT --to-port 1443
</pre>
<p>
Alternatively, if clients use dnspr as their DNS resolver, traffic can be redirected via DNS —
see <a href="#DNSPR">How to set up a DNS proxy (dnspr)</a>.
</p>
<p>
<b>SNI Break (DPI Bypass):</b>
<br>tlspr can be used as a parent with the "tls" type to implement SNI splitting for DPI bypass (similar to NoDPI/GoodByeDPI).
The client sends the first part of the TLS ClientHello, tlspr splits it at the SNI extension and sends it in two TCP packets,
which can bypass some DPI systems that look for blocked hostnames in TLS handshakes.
<br>To enable SNI break, use <code>parent ... tls 0.0.0.0 0</code> and the <code>-s</code> option on the listening service with TCP_NODELAY:
</p><pre>
auth iponly
allow *
parent 1000 tls 0.0.0.0 0
allow *
proxy -s -i127.0.0.1 -ocTCP_NODELAY -osTCP_NODELAY -p1443
</pre>
<p>
TCP_NODELAY is required to prevent the kernel from merging the split packets.
</p>
<p>
<b>Configuration examples:</b>
</p>
<p>
1. Standalone SNI proxy on port 1443 redirecting to destination port 443:
</p><pre>
tlspr -p1443 -P443 -c1
</pre>
<p>
2. Using tlspr as parent in SOCKS to detect destination hostname from TLS (even when client connects by IP):
</p><pre>
allow * * * 80
parent 1000 http 0.0.0.0 0
allow * * * * CONNECT
parent 1000 tls 0.0.0.0 0
deny * * some.not.allowed.host
allow *
socks
</pre>
<p>
3. Using tlspr with HTTP proxy for TLS hostname-based ACL:
</p><pre>
allow * * * * HTTP_CONNECT
parent 1000 tls 0.0.0.0 0
deny * * blocked.example.com
allow *
proxy
</pre>
</p>
<li><a name="DNSPR"><i>How to set up a DNS proxy (dnspr)</i></a></li>
<p>
dnspr is a DNS forwarding service. It answers queries from the 3proxy name cache (including static nsrecord
entries), forwards other queries to the resolvers configured with nserver, and caches the results if
nscache/nscache6 are configured. Options:
</p><pre>
-s - simple DNS forwarding: do not use 3proxy resolver / name cache
-F<ip> - fake: answer all A (or AAAA) queries with the given IP address.
May be given twice - once with an IPv4 and once with an IPv6 address.
</pre>
<p>
dnspr can be used to redirect traffic by hostname, e.g. to point mail clients to a
<a href="#TLSPR">tlspr</a> installation, by adding nsrecord entries for the service hostnames
(nscache/nscache6 keep the answers for all other names intact):
</p><pre>
nscache 65536
nscache6 65536
dnspr -p53
# google
nsrecord smtp.gmail.com 10.0.0.1
nsrecord imap.gmail.com 10.0.0.1
nsrecord pop.gmail.com 10.0.0.1
# mail.ru
nsrecord smtp.mail.ru 10.0.0.1
nsrecord imap.mail.ru 10.0.0.1
nsrecord pop.mail.ru 10.0.0.1
# yandex.ru
nsrecord smtp.yandex.ru 10.0.0.1
nsrecord imap.yandex.ru 10.0.0.1
nsrecord pop.yandex.ru 10.0.0.1
</pre>
<p>
where 10.0.0.1 is the address tlspr listens on. If every hostname must be redirected, a single fake
address can be used instead of individual nsrecords:
</p><pre>
nscache 65536
nscache6 65536
dnspr -p53 -F10.0.0.1
</pre>
</p>
<li><a name="HTTPSRV"><i>How to serve pages with the built-in HTTP server (httpsrv)</i></a>
<p>
httpsrv answers requests itself instead of forwarding them. What it does with a
request is decided by <code>http</code> rules written before the service, the way
access rules are: the first rule whose host and URL both match handles the
request. It is useful for a status page, a small static site, a block page for
requests an ACL rejects, or a health check an upstream balancer can poll.
</p><pre>
http OPERATION HOST URL [PARAMETERS]
</pre>
<p>
HOST is matched against the Host header, URL against the path with the query
string removed. A minimal static site:
</p><pre>
auth iponly
allow *
http file * / /usr/local/web/index.html
http file * /*.html "/usr/local/web/$1.html"
http file * /css/*.css "/usr/local/web/css/$1.css"
http cache * /img/** "/usr/local/web/img/$1" * 3600
httpsrv -p80 -i127.0.0.1
</pre>
<p>
<b>Patterns.</b> <code>*</code> stands for any run of characters within one
element of the path and does not cross a <code>/</code>, so a rule cannot reach
into a directory it did not name. <code>**</code> crosses them. Each star, and
each group of a regular expression, is remembered in order: <code>$1</code>
upwards stand for them in the path or location the rule builds, and
<code>$0</code> for the whole request path. A <code>rewrite_host</code> rule
uses the stars of its own host pattern instead, since that is what it is
rewriting. With a PCRE build a pattern may be
written as a regular expression with a <code>pcre:</code> prefix, for the URL and
for the host alike:
</p><pre>
http file * /d/*.txt "/usr/local/web/$1.txt"
http cache * "pcre:^/(.*)/pic/(.*)\.(gif|jpeg)$" "/usr/local/web/picts/$1/$2.$3"
http file status.example.com /** "/usr/local/web/status/$1"
http file "pcre:^(www|web)\.example\.com$" /** "/usr/local/web/$1"
</pre>
<p>
Outside quotes a dollar begins the name of a file to include, so an argument
holding one - a path built with <code>$1</code>, a regular expression anchored
with <code>$</code> - is written in quotes, as above. <code>$$</code> stands for
a single dollar and is not read as an include either.
</p>
<p>
<b>Operations.</b>
</p><pre>
# file - send the file, using sendfile/TransmitFile where the system can
http file * /dl/** "/usr/local/web/dl/$1"
# cache - read it into memory on the first request and answer from there
http cache * /css/*.css "/usr/local/web/css/$1.css"
# redir - answer with a redirect, 302 unless a status is given
http redir * /old/** 301 "https://example.org/$1"
# rewrite - change the path and hand the request to the rules after this one
http rewrite * /alias/** "/w/$1"
# rewrite_host - the same for the host, which decides which rules match next
http rewrite_host *.old.example ** "$1.new.example"
# reply - a status and nothing else
http reply * /health** 200 "X-Health: ok"
http reply * /down** 503 "Retry-After: 30"
# echo, data - describe the request, or generate content of a given size
http echo * /echo**
http data * /gen** size=1048576
</pre>
<p>
<b>What a rule adds to the answer.</b> <code>file</code> and <code>cache</code>
take, after the path, a content type, a max-age, headers to add and a status to
answer with. Each may be left out or written as <code>*</code>:
</p><pre>
http OPERATION HOST URL PATH [TYPE [MAX-AGE [HEADERS [CODE]]]]
# type worked out from the name, cached by clients for an hour
http file * /img/*.png "/usr/local/web/img/$1.png" * 3600
# a type of its own, and a header
http file * /api/*.json "/usr/local/web/api/$1.json" application/json * "X-Api: 1"
# a file serving as the body of an error page
http file * /err/** /usr/local/web/404.html text/html * * 404
</pre>
<p>
HEADERS is one argument holding whole header lines, separated by a backslash and
an n - the two characters, since a configuration line cannot carry a line
ending. Quote it, headers contain spaces. A rule's headers and max-age go with
whatever status that rule asked for, but not 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.
</p>
<p>
Types not known to the server are registered with
<code>http_content_type</code>, and a type named by a rule is used whatever the
name of the file says:
</p><pre>
http_content_type .webp image/webp
http_content_type wasm application/wasm
</pre>
<p>
<b>Files and dates.</b> Only a full path is taken - a relative one would be read
against whatever directory the service happens to be in - and a path holding
<code>.</code> or <code>..</code> as an element, a line ending or a star is
refused. On Windows a path must name a drive or a share (<code>"C:\web\$1"</code>
or <code>"\\host\share\$1"</code>). A request which decodes to a path leaving the
tree is refused before any of this. Every answer carries Last-Modified, and a
request carrying If-Modified-Since is answered 304 with no body when the file
has not changed.
</p>
<p>
<b>Caching.</b> <code>cache</code> reads the file once and answers from memory
afterwards; a file which has changed on disk is read again, and one larger than
a megabyte is sent as <code>file</code> 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 a request costs nothing but the copy
out. Without one every request stats the file and a change is picked up at once.
</p>
<p>
<b>A block page.</b> A service which rejects a request with a redirect can send
the client to an httpsrv running beside it:
</p><pre>
auth iponly
deny * * "pcre:^(ads|track)[0-9]*\.example\.(com|net)$"
allow *
proxy -p3128 -i192.168.1.1
flush
auth iponly
allow *
http file * /** /usr/local/web/blocked.html text/html * * 403
httpsrv -p8080 -i127.0.0.1
</pre>
<p>
<b>Both a site and a proxy.</b> A request may arrive the way it arrives at a
site - a path, with the name in the Host header - or the way it arrives at a
proxy, naming the whole URL, or the host alone with CONNECT. Both are read. A
proxy-form request authenticates with Proxy-Authorization and is refused with
407, the way a proxy refuses one; a site-form request uses Authorization and
401. What answers it is decided by the rules either way.
</p>
<p>
<code>proxypass</code> is the rule which answers by fetching, so one service can
serve what it has and proxy the rest:
</p><pre>
auth iponly