Support acls for UDP ASSOC, fix udppm via SOCKSv5
C/C++ CI Linux / ${{ matrix.target }} (ubuntu-24.04-arm) (push) Waiting to run
C/C++ CI Linux / ${{ matrix.target }} (ubuntu-latest) (push) Waiting to run
C/C++ CI MacOS / ${{ matrix.target }} (macos-15) (push) Waiting to run
C/C++ CI Windows / ${{ matrix.target }} (windows-2022) (push) Waiting to run
C/C++ CI cmake / ${{ matrix.target }} (macos-15) (push) Waiting to run
C/C++ CI cmake / ${{ matrix.target }} (ubuntu-24.04-arm) (push) Waiting to run
C/C++ CI cmake / ${{ matrix.target }} (ubuntu-latest) (push) Waiting to run
C/C++ CI cmake / ${{ matrix.target }} (windows-2022) (push) Waiting to run
C/C++ CI cmake / ubuntu-latest (wolfSSL) (push) Waiting to run

This commit is contained in:
Vladimir Dubrovin committed 2026-08-11 19:02:54 +03:00
1 parent ddb74a111c
commit bebc3894e2
14 files changed
+699 -124

No files matched your search

+133
View File
@@ -428,6 +428,139 @@ use 3proxy's built-in resolver (nserver / nscache / nscache6).
Public resolvers like those from Google have rate limits. For a large number of
requests, install a local caching recursor (ISC bind named, PowerDNS recursor, etc).
<h4>Use the Authentication Cache</h4>
Authentication and authorization are performed for every request. Password
lookup itself is a hash lookup and is cheap, but the ACL is walked linearly,
and with RADIUS or plugin authentication every request costs a network round
trip. 'authcache' keeps the result of a successful authentication for a number
of seconds:
<pre>
authcache &lt;cachetype&gt; &lt;cachetime&gt; &lt;cachesize&gt;
</pre>
'cachetype' lists the fields the entry is keyed by, 'cachetime' is the lifetime
in seconds, and the optional 'cachesize' limits the number of entries. The
cached type must be placed before the real authentication type in the 'auth'
command: a cache miss falls through to the next type in the chain, and a hit
skips it.
<p>There are two cached types:
<ul>
<li>'cache' caches the authentication only; the ACL is still checked on every
request. Use it when ACLs must take effect immediately, or when the
authentication method returns per-user parameters that the authorization step
has to apply.
<li>'cacheacl' also caches the authorization result, so the ACL is not walked
at all on a hit. This is the one that helps with long ACLs, but the key must
cover every field the ACL limits, and it can not be used with redirections.
</ul>
<p><b>'cacheacl' does not work with parent proxies.</b> Redirections are applied
while the ACL is walked, so on a 'cacheacl' hit no redirection happens at all:
the request is sent directly instead of through the 'parent' proxy of the
matching ACL entry, and nothing is reported. The first request for a given key
uses the parent and the rest do not, which makes it look intermittent. Use
'cache' with parent proxies:
<pre>
authcache user,pass 60
auth cache strong
allow user1
parent 1000 socks5 10.0.0.1 1080
proxy
</pre>
The one exception is 'parent ... extip': the external address is stored in the
cache entry and restored on a hit, but only if 'ext' is a part of the key:
<pre>
authcache user,pass,ext 60
auth cacheacl strong
allow user1
parent 1000 extip 1.2.3.4 0
proxy
</pre>
Without 'ext' in the key the external address falls back to the default one on
every cache hit.
<p><b>The key must match the ACL.</b> On a 'cacheacl' hit the cached result is
reused as is, so any field the ACL limits but the key does not contain makes
the cached result apply to a request it was not computed for. Use 'user' and
'pass' for the userlist, 'ip' for the sourcelist, 'dstaddr' and 'dsthost' for
the targetlist, 'dstport' for the targetportlist and 'dstoper' for the
operationlist. For this ACL:
<pre>
allow user1,user2 * * 80,443
deny *
</pre>
the key needs 'user', 'pass' and 'dstport':
<pre>
users $/etc/3proxy/passwd
authcache user,pass,dstport 60 65536
auth cacheacl strong
allow user1,user2 * * 80,443
deny *
proxy
</pre>
<p>With RADIUS the round trip is the expensive part, so cache by whatever
identifies the client:
<pre>
radius secret 1.2.3.4
authcache ip,user,pass 600
auth cache radius
proxy
</pre>
'cache' rather than 'cacheacl' is used here because RADIUS may return per-user
parameters such as the outgoing IP; add 'ext' to the key to cache the external
address returned by RADIUS as well.
<p>Choose 'cachetime' to balance the load against how quickly a password or ACL
change has to take effect. Cache entries are <b>not</b> invalidated by a
configuration reload, so a long lifetime keeps applying the old decision to
existing keys after the new configuration is loaded.
<p>Note that 'ip' alone, or 'ip,user' without 'pass', assigns every connection
from the same address to the same user for the lifetime of the entry without
checking the password. That is a deliberate trade-off for high load; do not use
it where clients share addresses.
<h4>Tune UDP Destination Handling with '-U'</h4>
Within a SOCKSv5 UDP association the destination is taken from every datagram,
so 3proxy authorizes and logs every new destination. One association can reach
any number of destinations: a DNS forwarder produces one record, but a
peer-to-peer or QUIC client can produce hundreds, each costing an authorization
(a network round trip with RADIUS or plugin authentication) and a log record.
The 'socks' service option '-U' controls this:
<pre>
socks -U3 &#35; default: log and authorize every new destination
socks -U2 &#35; authorize, do not log
socks -U1 &#35; log, do not authorize
socks -U0 &#35; neither (same as bare -U)
</pre>
The destination of the first datagram is always authorized and logged, so the
association as a whole is still subject to ACLs, authentication and the choice
of the parent proxy.
<p>Before reaching for the option, note that the cost is already avoided when no
ACL entry reachable by the client limits the destination: in that case the
result can not depend on the destination and no re-authorization is performed
whatever '-U' says. '-U' only matters for configurations that do limit the
destination.
<p>For high load:
<ul>
<li><b>'-U2'</b> is the safe one. Destination ACLs keep working, only the
per-destination log records are dropped. Use it when log volume, not CPU, is
the problem.
<li><b>'-U' ('-U0')</b> removes both costs and is the fastest, but destination
ACLs then apply only to the first destination of each association, and the
parent proxy and external address chosen for it are kept for the whole
association. Use it when UDP destinations are not restricted anyway, or when
the restriction is enforced elsewhere (a firewall, or the parent proxy).
<li>Keep the default '-U3' when destination ACLs are a security boundary, and
make the authorization itself cheap with 'authcache' instead, see "Use the
Authentication Cache" above.
</ul>
<h4>Avoid Large Lists</h4>
Currently, 3proxy is not optimized to use large ACLs, user lists, etc. All lists
+76
View File
@@ -1338,6 +1338,82 @@ the second hop is 192.168.20.1, and the 3rd one is either 192.168.30.1 with a pr
of 30% or 192.168.40.1 with a probability of 70%.
</p>
<li><a name="UDPACL">How to apply ACLs to UDP traffic</a>
<p>
A SOCKSv5 UDP ASSOCIATE request only asks 3proxy to open a relay port, it
carries no destination. The destination is taken from every datagram the client
sends afterwards, so a single association may reach any number of destinations.
3proxy authorizes the destination of every datagram, so ACLs limiting the
destination address, host name or port do apply to UDP traffic.
</p>
<p>
Differences from TCP:
</p>
<ul>
<li>A datagram to a denied destination is dropped, the association is not
terminated.
<li>The parent proxy and the external address are selected for the destination
of the datagram and not for the ASSOCIATE request, and are re-established if a
later destination selects another ACL entry. Only <code>socks5</code> and
<code>socks5+</code> parents can be used for UDP.
<li>ACLs are checked for the datagrams sent by the client only. A datagram
received on the association is relayed to the client without an ACL check: with
a parent proxy only the datagrams from the parent are accepted, 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 received datagrams is not
logged.
<li>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.
<li>Bandwidth limiters and traffic counters which limit the destination are
selected when the destination is authorized, so they are selected for the
destination of the first datagram and are not re-selected for every following
destination. They can not be applied per destination to incoming UDP traffic at
all.
<li>Every change of the destination host name, address or port is authorized
again and logged. Use <code>nscache</code> for host names and the
authentication cache for anything more expensive than 'iponly'. The
<code>-U</code> option of the <code>socks</code> service turns the logging
and/or the re-authorization off; with <code>-U0</code> or <code>-U1</code>
only the first destination of an association is authorized.
</ul>
<p>
Limit the destinations a client may send datagrams to:
</p><pre>
auth iponly
allow * * 8.8.8.8 53
deny *
socks -p1080
</pre>
<p>
The ASSOCIATE request succeeds, datagrams to 8.8.8.8:53 are relayed, datagrams
to any other destination are dropped.
</p>
<p>
The same with 'strong' (or RADIUS, or plugin) authentication, where every new
destination would otherwise be authenticated again:
</p><pre>
users user1:CL:password
authcache user,pass,dstaddr,dstport 60
auth cacheacl strong
allow user1 * 8.8.8.8 53
deny *
socks -p1080
</pre>
<p>
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: 'user' and 'pass' for the
userlist, 'dstaddr' and 'dstport' for the targetlist and the targetportlist,
'ip' for the sourcelist, 'dsthost' for host names in the targetlist, 'dstoper'
for the operationlist. Without the destination in the key the result cached for
one destination is applied to any other destination and the destination is not
checked at all. Use plain 'cache' instead of 'cacheacl' if ACLs may change
during the cache lifetime, or if a parent proxy is used: on a 'cacheacl' hit
the ACL is not walked, so no parent proxy is selected and datagrams are sent
directly.
</p>
<li><A NAME="BANDLIM">How to limit bandwidth</a>
<p>
3proxy supports bandwidth filters. Use the bandlimin/bandlimout and
+79
View File
@@ -1371,6 +1371,85 @@ pcre_extend deny * 192.168.0.1/16
192.168.10.1, второе - 192.168.20.1, а третье - либо 192.168.30.1 с
вероятностью 0.3 либо 192.168.40.1 с вероятностью 0.7
</p>
<li><a name="UDPACL"><i>Как применять ACL к UDP трафику</i></a>
<p>
Запрос SOCKSv5 UDP ASSOCIATE лишь просит 3proxy открыть порт для ретрансляции
и не содержит адреса назначения. Адрес назначения берется из каждой
датаграммы, отправленной клиентом, поэтому одна ассоциация может обращаться
к любому числу адресов назначения. 3proxy авторизует адрес назначения каждой
датаграммы, поэтому ACL, ограничивающие адрес, имя хоста или порт
назначения, применяются и к UDP трафику.
</p>
<p>
Отличия от TCP:
</p>
<ul>
<li>Датаграмма к запрещенному адресу назначения отбрасывается, ассоциация
при этом не завершается.
<li>Вышестоящий прокси и внешний адрес выбираются для адреса назначения
датаграммы, а не для запроса ASSOCIATE, и устанавливаются заново, если
последующий адрес назначения соответствует другой записи ACL. Для UDP
могут использоваться только родители типа <code>socks5</code> и
<code>socks5+</code>.
<li>ACL проверяются только для датаграмм, отправленных клиентом. Датаграмма,
полученная в рамках ассоциации, передается клиенту без проверки ACL: при
использовании вышестоящего прокси принимаются только датаграммы от него, а
ассоциация без вышестоящего прокси принимает датаграмму от любого источника.
Клиенту сообщается фактический адрес источника датаграммы. В журнал записывается адрес назначения, на который клиент
отправлял датаграммы, а не адрес источника полученных датаграмм.
<li>Клиент может использовать одну ассоциацию для обращения ко многим адресам
назначения. Запись ACL, ограничивающая адрес назначения, молча отбрасывает
датаграммы ко всем остальным адресам назначения, поэтому ограничение адреса
назначения для UDP может нарушить работу таких клиентов, и причину трудно
установить. Ограничивайте его, только если это действительно необходимо.
<li>Ограничители полосы и счетчики трафика, ограничивающие адрес назначения,
выбираются при авторизации адреса назначения, поэтому они выбираются для
адреса назначения первой датаграммы и не выбираются заново для каждого
последующего адреса назначения. К входящему UDP трафику они не могут быть
применены по адресу назначения вообще.
<li>Каждое изменение имени хоста, адреса или порта назначения
авторизуется заново и записывается в журнал. Используйте <code>nscache</code>
для имен хостов и кэш аутентификации для всего, что дороже 'iponly'. Опция
<code>-U</code> сервиса <code>socks</code> отключает журналирование и/или
повторную авторизацию; при <code>-U0</code> или <code>-U1</code>
авторизуется только первый адрес назначения ассоциации.
</ul>
<p>
Ограничить адреса назначения, куда клиент может отправлять датаграммы:
</p><pre>
auth iponly
allow * * 8.8.8.8 53
deny *
socks -p1080
</pre>
<p>
Запрос ASSOCIATE выполняется успешно, датаграммы к 8.8.8.8:53 передаются,
датаграммы к любому другому адресу назначения отбрасываются.
</p>
<p>
То же самое с аутентификацией 'strong' (или RADIUS, или через плагин), при
которой иначе каждый новый адрес назначения аутентифицировался бы заново:
</p><pre>
users user1:CL:password
authcache user,pass,dstaddr,dstport 60
auth cacheacl strong
allow user1 * 8.8.8.8 53
deny *
socks -p1080
</pre>
<p>
При 'cacheacl' результат проверки ACL не вычисляется заново при попадании
в кэш, поэтому каждое поле, ограничиваемое в ACL, должно входить в ключ
кэша: 'user' и 'pass' для списка пользователей, 'dstaddr' и 'dstport' для списка
адресов и списка портов назначения, 'ip' для списка источников, 'dsthost'
для имен хостов в списке назначения, 'dstoper' для списка операций. Без
адреса назначения в ключе результат, закэшированный для одного адреса
назначения, применяется к любому другому, и адрес назначения не
проверяется вообще. Используйте 'cache' вместо 'cacheacl', если ACL могут
изменяться в течение времени жизни кэша или если используется вышестоящий
прокси: при попадании в кэш 'cacheacl' обход ACL не выполняется, поэтому
вышестоящий прокси не выбирается и датаграммы отправляются напрямую.
</p>
<li><a name="BANDLIM"><i>Как ограничивать скорости приема</i></a>
<p>
3proxy позволяет устанавливать фильтры ширины потребляемого канала. Для этого
+20
View File
@@ -25,6 +25,26 @@ with an unreachable DNS server (because gethostbyname will block other threads).
user requests can be logged.
<li>Use -xyz+A character filtering sequences for 'logformat', especially with
ODBC logging, to prevent SQL and log record injections.
<li>With the 'cacheacl' authentication type the ACL result is cached and is not
re-evaluated on a cache hit, so every field the ACL limits must be a part of
the 'authcache' key. Any field the ACL limits but the key does not contain
makes the cached result apply to a request it was not computed for, and that
limitation is not enforced. Use 'user' and 'pass' for the userlist, 'ip' for
the sourcelist, 'dstaddr' and 'dsthost' for the targetlist, 'dstport' for the
targetportlist and 'dstoper' for the operationlist. Use plain 'cache' instead
of 'cacheacl' if ACLs may change during the cache lifetime; cache entries are
not invalidated by a configuration reload.
<li>'cacheacl' must not be used together with parent proxies. The ACL is not
walked on a cache hit, so no redirection is applied and the request is sent
directly instead of through the 'parent' proxy of the matching ACL entry,
without any error. If the parent proxy is the only sanctioned path to the
network, this silently bypasses it. Use 'cache' instead. 'parent ... extip'
is the only redirection which survives, and only if 'ext' is a part of the
'authcache' key.
<li>The destination of every datagram of a SOCKSv5 UDP association is
authorized, but only with the default '-U3' (or '-U2') of the 'socks' service.
With '-U0' or '-U1' only the first destination of an association is authorized,
so ACLs limiting the destination do not restrict the rest of the association.
<li>Immediately report all service crashes to the developers.
<li>Participate in code audit :)
</ul>