vyos/vyos-documentation
1
0
Fork 0
mirror of https://github.com/vyos/vyos-documentation.git synced 2025-10-26 08:41:46 +01:00
Code Issues Packages Projects Releases Wiki Activity

webproxy: update docs

Browse Source
This commit is contained in:
Christian Poessinger 2020-12-26 16:16:16 +01:00
parent a352a3762e
commit 3caeaac25e
1 changed files with 370 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

463
docs/configuration/service/webproxy.rst
View File

@ -1,68 +1,369 @@
.. _webproxy:
########
Webproxy
--------
########
The proxy service in VyOS is based on Squid3 and some related modules.
The proxy service in VyOS is based on Squid_ and some related modules.
Squid3_ is a caching and forwarding HTTP web proxy. It has a wide variety of
uses, including speeding up a web server by caching repeated requests,
caching web, DNS and other computer network lookups for a group of people
sharing network resources, and aiding security by filtering traffic. Although
primarily used for HTTP and FTP, Squid includes limited support for several
other protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does
not support the SOCKS protocol.
Squid_ is a caching and forwarding HTTP web proxy. It has a wide variety of
uses, including speeding up a web server by caching repeated requests, caching
web, DNS and other computer network lookups for a group of people sharing
network resources, and aiding security by filtering traffic. Although primarily
used for HTTP and FTP, Squid includes limited support for several other
protocols including Internet Gopher, SSL,[6] TLS and HTTPS. Squid does not
support the SOCKS protocol.
All examples here assumes that your inside ip address is ``192.168.0.1``.
Replace with your own where applicable.
URL Filtering is provided by Squidguard_.
URL Filtering is provided by SquidGuard_.
*************
Configuration
^^^^^^^^^^^^^^
*************
.. code-block:: none
.. cfgcmd:: set service webproxy append-domain <domain>
# Enable proxy service
set service webproxy listen-address 192.168.0.1
Use this command to specify a domain name to be appended to domain-names
within URLs that do not include a dot ``.`` the domain is appended.
# By default it will listen to port 3128. If you want something else you have to define that.
set service webproxy listen-address 192.168.0.1 port 2050
Example: to be appended is set to ``vyos.net`` and the URL received is
``www/foo.html``, the system will use the generated, final URL of
``www.vyos.net/foo.html``.
# By default the transparent proxy on that interface is enabled. To disable that you simply
set service webproxy listen-address 192.168.0.1 disable-transparent
.. code-block:: none
# Block specific urls
set service webproxy url-filtering squidguard local-block myspace.com
set service webproxy append-domain vyos.net
# If you want to you can log these blocks
set service webproxy url-filtering squidguard log local-block
.. cfgcmd:: set service webproxy cache-size <size>
The size of the on-disk Proxy cache is user configurable. The Proxies default
cache-size is configured to 100 MB.
Unit of this command is MB.
.. code-block:: none
set service webproxy cache-size 1024
.. cfgcmd:: set service webproxy default-port <port>
Specify the port used on which the proxy service is listening for requests.
This port is the default port used for the specified listen-address.
Default port is 3128.
.. code-block:: none
set service webproxy default-port 8080
.. cfgcmd:: set service webproxy domain-block <domain>
Used to block specific domains by the Proxy. Specifying "vyos.net" will block
all access to vyos.net, and specifying ".xxx" will block all access to URLs
having an URL ending on .xxx.
.. code-block:: none
set service webproxy domain-block vyos.net
.. cfgcmd:: set service webproxy domain-noncache <domain>
Allow access to sites in a domain without retrieving them from the Proxy
cache. Specifying "vyos.net" will allow access to vyos.net but the pages
accessed will not be cached. It useful for working around problems with
"If-Modified-Since" checking at certain sites.
.. code-block:: none
set service webproxy domain-noncache vyos.net
.. cfgcmd:: set service webproxy listen-address <address>
Specifies proxy service listening address. The listen address is the IP
address on which the web proxy service listens for client requests.
For security, the listen address should only be used on internal/trusted
networks!
.. code-block:: none
set service webproxy listen-address 192.0.2.1
.. cfgcmd:: set service webproxy listen-address <address> disable-transparent
Disables web proxy transparent mode at a listening address.
In transparent proxy mode, all traffic arriving on port 80 and destined for
the Internet is automatically forwarded through the proxy. This allows
immediate proxy forwarding without configuring client browsers.
Non-transparent proxying requires that the client browsers be configured with
the proxy settings before requests are redirected. The advantage of this is
that the client web browser can detect that a proxy is in use and can behave
accordingly. In addition, web-transmitted malware can sometimes be blocked by
a non-transparent web proxy, since they are not aware of the proxy settings.
.. code-block:: none
set service webproxy listen-address 192.0.2.1 disable-transparent
.. cfgcmd:: set service webproxy listen-address <address> port <port>
Sets the listening port for a listening address. This overrides the default
port of 3128 on the specific listen address.
.. code-block:: none
set service webproxy listen-address 192.0.2.1 port 8080
Options
*******
.. cfgcmd:: set service webproxy reply-block-mime <mime>
Filtering by category
^^^^^^^^^^^^^^^^^^^^^
Used to block a specific mime-type.
.. code-block:: none
# block all PDFs
set service webproxy reply-block-mime application/pdf
.. cfgcmd:: set service webproxy reply-body-max-size <size>
Specifies the maximum size of a reply body in KB, used to limit the reply
size.
All reply sizes are accepted by default.
.. code-block:: none
set service webproxy reply-body-max-size 2048
Authentication
==============
The embedded Squid proxy can use LDAP to authenticate users against a company
wide directory. The following configuration is an example of how to use Active
Directory as authentication backend. Queries are done via LDAP.
.. cfgcmd:: set service webproxy authentication children <number>
Maximum number of authenticator processes to spawn. If you start too few
Squid will have to wait for them to process a backlog of credential
verifications, slowing it down. When password verifications are done via a
(slow) network you are likely to need lots of authenticator processes.
This defaults to 5.
.. code-block:: none
set service webproxy authentication children 10
.. cfgcmd:: set service webproxy authentication credentials-ttl <time>
Specifies how long squid assumes an externally validated username:password
pair is valid for - in other words how often the helper program is called for
that user. Set this low to force revalidation with short lived passwords.
Time is in minutes and defaults to 60.
.. code-block:: none
set service webproxy authentication credentials-ttl 120
.. cfgcmd:: set service webproxy authentication method <ldap>
Proxy authentication method, currently only LDAP is supported.
.. code-block:: none
set service webproxy authentication method ldap
.. cfgcmd:: set service webproxy authentication realm
Specifies the protection scope (aka realm name) which is to be reported to
the client for the authentication scheme. It is commonly part of the text
the user will see when prompted for their username and password.
.. code-block:: none
set service webproxy authentication realm "VyOS proxy auth"
LDAP
----
.. cfgcmd:: set service webproxy authentication ldap base-dn <base-dn>
Specifies the base DN under which the users are located.
.. code-block:: none
set service webproxy authentication ldap base-dn DC=vyos,DC=net
.. cfgcmd:: set service webproxy authentication ldap bind-dn <bind-dn>
The DN and password to bind as while performing searches.
.. code-block:: none
set service webproxy authentication ldap bind-dn CN=proxyuser,CN=Users,DC=vyos,DC=net
.. cfgcmd:: set service webproxy authentication ldap filter-expression <expr>
LDAP search filter to locate the user DN. Required if the users are in a
hierarchy below the base DN, or if the login name is not what builds the user
specific part of the users DN.
The search filter can contain up to 15 occurrences of %s which will be
replaced by the username, as in "uid=%s" for :rfc:`2037` directories. For a
detailed description of LDAP search filter syntax see :rfc:`2254`.
.. code-block:: none
set service webproxy authentication ldap filter-expression (cn=%s)
.. cfgcmd:: set service webproxy authentication ldap password <password>
The DN and password to bind as while performing searches. As the password
needs to be printed in plain text in your Squid configuration it is strongly
recommended to use a account with minimal associated privileges. This to limit
the damage in case someone could get hold of a copy of your Squid
configuration file.
.. code-block:: none
set service webproxy authentication ldap password vyos
.. cfgcmd:: set service webproxy authentication ldap persistent-connection
Use a persistent LDAP connection. Normally the LDAP connection is only open
while validating a username to preserve resources at the LDAP server. This
option causes the LDAP connection to be kept open, allowing it to be reused
for further user validations.
Recommended for larger installations.
.. code-block:: none
set service webproxy authentication ldap persistent-connection
.. cfgcmd:: set service webproxy authentication ldap port <port>
Specify an alternate TCP port where the ldap server is listening if other than
the default LDAP port 389.
.. code-block:: none
set service webproxy authentication ldap port 389
.. cfgcmd:: set service webproxy authentication ldap server <server>
Specify the LDAP server to connect to.
.. code-block:: none
set service webproxy authentication ldap server ldap.vyos.net
.. cfgcmd:: set service webproxy authentication ldap use-ssl
Use TLS encryption.
.. code-block:: none
set service webproxy authentication ldap use-ssl
.. cfgcmd:: set service webproxy authentication ldap username-attribute <attr>
Specifies the name of the DN attribute that contains the username/login.
Combined with the base DN to construct the users DN when no search filter is
specified (`filter-expression`).
Defaults to 'uid'
.. note:: This can only be done if all your users are located directly under
the same position in the LDAP tree and the login name is used for naming
each user object. If your LDAP tree does not match these criterias or if you
want to filter who are valid users then you need to use a search filter to
search for your users DN (`filter-expression`).
.. code-block:: none
set service webproxy authentication ldap username-attribute uid
.. cfgcmd:: set service webproxy authentication ldap version <2 | 3>
LDAP protocol version. Defaults to 3 if not specified.
.. code-block:: none
set service webproxy authentication ldap version 2
URL filtering
=============
.. include:: /_include/need_improvement.txt
.. cfgcmd:: set service webproxy url-filtering disable
Disables web filtering without discarding configuration.
.. code-block:: none
set service webproxy url-filtering disable
*********
Operation
*********
.. include:: /_include/need_improvement.txt
Filtering
=========
Update
------
If you want to use existing blacklists you have to create/download a database
first. Otherwise you will not be able to commit the config changes.
.. code-block:: none
vyos@vyos# commit
[ service webproxy ]
Warning: no blacklists installed
Unknown block-category [ads] for policy [default]
.. opcmd:: update webproxy blacklists
[[service webproxy]] failed
Commit failed
Download/Update complete blacklist
* Download/Update complete blacklist
.. code-block:: none
:code:`update webproxy blacklists`
vyos@vyos:~$ update webproxy blacklists
Warning: No url-filtering blacklist installed
Would you like to download a default blacklist? [confirm][y]
Connecting to ftp.univ-tlse1.fr (193.49.48.249:21)
blacklists.gz 100% |*************************************************************************************************************| 17.0M 0:00:00 ETA
Uncompressing blacklist...
Checking permissions...
Skip link for [ads] -> [publicite]
Building DB for [adult/domains] - 2467177 entries
Building DB for [adult/urls] - 67798 entries
Skip link for [aggressive] -> [agressif]
Building DB for [agressif/domains] - 348 entries
Building DB for [agressif/urls] - 36 entries
Building DB for [arjel/domains] - 69 entries
...
* Download/Update partial blacklist
Building DB for [webmail/domains] - 374 entries
Building DB for [webmail/urls] - 9 entries
:code:`update webproxy blacklists category ads`
The webproxy daemon must be restarted
Would you like to restart it now? [confirm][y]
[ ok ] Restarting squid (via systemctl): squid.service.
vyos@vyos:~$
.. opcmd:: update webproxy blacklists category <category>
Download/Update partial blacklist.
Use tab completion to get a list of categories.
@ -77,12 +378,34 @@ first. Otherwise you will not be able to commit the config changes.
:code:`set service webproxy url-filtering squidguard block-category malware`
Authentication
^^^^^^^^^^^^^^
Bypassing the webproxy
----------------------
The embedded Squid proxy can use LDAP to authenticate users against a company
wide directory. The following configuration is an example of how to use Active
Directory as authentication backend. Queries are done via LDAP.
.. include:: /_include/need_improvement.txt
Some services don't work correctly when being handled via a web proxy.
So sometimes it is useful to bypass a transparent proxy:
* To bypass the proxy for every request that is directed to a specific
destination:
:code:`set service webproxy whitelist destination-address 198.51.100.33`
:code:`set service webproxy whitelist destination-address 192.0.2.0/24`
* To bypass the proxy for every request that is coming from a specific source:
:code:`set service webproxy whitelist source-address 192.168.1.2`
:code:`set service webproxy whitelist source-address 192.168.2.0/24`
(This can be useful when a called service has many and/or often changing
destination addresses - e.g. Netflix.)
********
Examples
********
.. code-block:: none
@ -107,51 +430,5 @@ Directory as authentication backend. Queries are done via LDAP.
disable-transparent
}
* ``base-dn`` set the base directory for the search
* ``bind-dn`` and ``password``: set the user, which is used for the ldap search
* ``filter-expression``: set the exact filter which a authorized user match in
a ldap-search. In this example every User is able to authorized.
You can find more about the ldap authentication
`here
<http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_
Adjusting cache size
^^^^^^^^^^^^^^^^^^^^
The size of the proxy cache can be adjusted by the user.
.. code-block:: none
set service webproxy cache-size
Possible completions:
<0-4294967295>
Disk cache size in MB (default 100)
0 Disable disk caching
100
Bypassing the webproxy
^^^^^^^^^^^^^^^^^^^^^^
Some services don't work correctly when being handled via a web proxy.
So sometimes it is useful to bypass a transparent proxy:
* To bypass the proxy for every request that is directed to a specific
destination:
:code:`set service webproxy whitelist destination-address 198.51.100.33`
:code:`set service webproxy whitelist destination-address 192.0.2.0/24`
* To bypass the proxy for every request that is coming from a specific source:
:code:`set service webproxy whitelist source-address 192.168.1.2`
:code:`set service webproxy whitelist source-address 192.168.2.0/24`
(This can be useful when a called service has many and/or often changing
destination addresses - e.g. Netflix.)
.. _Squid3: http://www.squid-cache.org/
.. _Squidguard: http://www.squidguard.org/
.. _Squid: http://www.squid-cache.org/
.. _SquidGuard: http://www.squidguard.org/