From 3caeaac25e54a2af9c2c4c3df742e15a76336ecf Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Sat, 26 Dec 2020 16:16:16 +0100 Subject: webproxy: update docs --- docs/configuration/service/webproxy.rst | 459 +++++++++++++++++++++++++------- 1 file changed, 368 insertions(+), 91 deletions(-) (limited to 'docs/configuration/service/webproxy.rst') diff --git a/docs/configuration/service/webproxy.rst b/docs/configuration/service/webproxy.rst index e65c672c..e8f6423e 100644 --- a/docs/configuration/service/webproxy.rst +++ b/docs/configuration/service/webproxy.rst @@ -1,137 +1,387 @@ -Webproxy --------- +.. _webproxy: -The proxy service in VyOS is based on Squid3 and some related modules. +######## +Webproxy +######## -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. +The proxy service in VyOS is based on Squid_ and some related modules. -All examples here assumes that your inside ip address is ``192.168.0.1``. -Replace with your own where applicable. +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. -URL Filtering is provided by Squidguard_. +URL Filtering is provided by SquidGuard_. +************* Configuration -^^^^^^^^^^^^^^ +************* -.. code-block:: none +.. cfgcmd:: set service webproxy append-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 + The size of the on-disk Proxy cache is user configurable. The Proxies default + cache-size is configured to 100 MB. -Options -******* + Unit of this command is MB. -Filtering by category -^^^^^^^^^^^^^^^^^^^^^ + .. code-block:: none -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. + set service webproxy cache-size 1024 -.. code-block:: none +.. cfgcmd:: set service webproxy default-port - vyos@vyos# commit - [ service webproxy ] - Warning: no blacklists installed - Unknown block-category [ads] for policy [default] + 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. - [[service webproxy]] failed - Commit failed + Default port is 3128. -* Download/Update complete blacklist + .. code-block:: none - :code:`update webproxy blacklists` + set service webproxy default-port 8080 -* Download/Update partial blacklist +.. cfgcmd:: set service webproxy domain-block - :code:`update webproxy blacklists category ads` + 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. - Use tab completion to get a list of categories. + .. code-block:: none -* To auto update the blacklist files + set service webproxy domain-block vyos.net - :code:`set service webproxy url-filtering squidguard auto-update - update-hour 23` +.. cfgcmd:: set service webproxy domain-noncache -* To configure blocking add the following to the configuration + 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:`set service webproxy url-filtering squidguard block-category ads` + .. code-block:: none - :code:`set service webproxy url-filtering squidguard block-category malware` + set service webproxy domain-noncache vyos.net + +.. cfgcmd:: set service webproxy listen-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
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
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 + + +.. cfgcmd:: set service webproxy reply-block-mime + + 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 + + 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. -.. code-block:: none +.. cfgcmd:: set service webproxy authentication children - vyos@vyos# show service webproxy - authentication { - children 5 - credentials-ttl 60 - ldap { - base-dn DC=example,DC=local - bind-dn CN=proxyuser,CN=Users,DC=example,DC=local - filter-expression (cn=%s) - password Qwert1234 - server ldap.example.local - username-attribute cn - } - method ldap - realm "VyOS Webproxy" - } - cache-size 100 - default-port 3128 - listen-address 192.168.188.103 { - disable-transparent - } + 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. -* ``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. + This defaults to 5. -You can find more about the ldap authentication -`here -`_ + .. code-block:: none -Adjusting cache size -^^^^^^^^^^^^^^^^^^^^ + set service webproxy authentication children 10 -The size of the proxy cache can be adjusted by the user. +.. cfgcmd:: set service webproxy authentication credentials-ttl