diff options
Diffstat (limited to 'docs/configuration')
| -rw-r--r-- | docs/configuration/highavailability/index.rst | 2 | ||||
| -rw-r--r-- | docs/configuration/interfaces/bonding.rst | 8 | ||||
| -rw-r--r-- | docs/configuration/interfaces/ethernet.rst | 36 | ||||
| -rw-r--r-- | docs/configuration/interfaces/openvpn.rst | 16 | ||||
| -rw-r--r-- | docs/configuration/protocols/mpls.rst | 6 | ||||
| -rw-r--r-- | docs/configuration/service/webproxy.rst | 459 |
6 files changed, 420 insertions, 107 deletions
diff --git a/docs/configuration/highavailability/index.rst b/docs/configuration/highavailability/index.rst index c4dc443f..a223c283 100644 --- a/docs/configuration/highavailability/index.rst +++ b/docs/configuration/highavailability/index.rst @@ -3,7 +3,7 @@ High availability ================= -VRRP (Virtual Redundancy Protocol) provides active/backup redundancy for +VRRP (Virtual Router Redundancy Protocol) provides active/backup redundancy for routers. Every VRRP router has a physical IP/IPv6 address, and a virtual address. On startup, routers elect the master, and the router with the highest priority becomes the master and assigns the virtual address to its interface. diff --git a/docs/configuration/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 92601b37..bf7cfc2c 100644 --- a/docs/configuration/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst @@ -256,6 +256,13 @@ Bond options The maximum number of targets that can be specified is 16. The default value is no IP addresses. +Offloading +---------- + +.. cmdinclude:: /_include/interface-xdp.txt + :var0: bonding + :var1: bond0 + VLAN ==== @@ -265,6 +272,7 @@ VLAN Port Mirror (SPAN) ================== + .. cmdinclude:: ../../_include/interface-mirror.txt :var0: bonding :var1: bond1 diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst index 25eebf25..3eae0d95 100644 --- a/docs/configuration/interfaces/ethernet.rst +++ b/docs/configuration/interfaces/ethernet.rst @@ -92,13 +92,9 @@ Offloading the IPv4 ID is not sequentially incrementing it will be altered so that it is when a frame assembled via GRO is segmented via GSO. - .. warning:: Recent 1.3 rolling images also support XDP offloading which - stands for eXpress Data Path in the Linux Kernel. You must enable it for - every interface which should participate in the XDP forwarding. - - Enabling this feature will break any form of NAT or Firewalling on this - interface, as XDP is handled way earlier in the driver then NfTables. - +.. cmdinclude:: /_include/interface-xdp.txt + :var0: ethernet + :var1: eth0 VLAN ==== @@ -269,3 +265,29 @@ Operation Vendor SN : FNS092xxxxx Date code : 0506xx +.. stop_vyoslinter + +.. opcmd:: show interfaces ethernet <interface> xdp + + Display XDP forwarding statistics + + .. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth1 xdp + + Collecting stats from BPF map + - BPF map (bpf_map_type:6) id:176 name:xdp_stats_map key_size:4 value_size:16 max_entries:5 + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250340 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250317 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250314 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:0.250313 + + XDP-action + XDP_ABORTED 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000410 + XDP_DROP 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_PASS 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_TX 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + XDP_REDIRECT 0 pkts ( 0 pps) 0 Kbytes ( 0 Mbits/s) period:2.000414 + diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 0e4e9d74..2c273b34 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -317,16 +317,16 @@ commands: vyos@vyos:/config/my-easy-rsa-config$./easyrsa revoke client1 vyos@vyos:/config/my-easy-rsa-config$ ./easyrsa gen-crl -Copy the files to /config/auth/ovpn/ to use in OpenVPN tunnel creation +Copy the files to /config/auth/openvpn/ to use in OpenVPN tunnel creation .. code-block:: none - vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/ovpn - vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/ovpn + vyos@vyos:/config/my-easy-rsa-config$ sudo mkdir /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/ca.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/dh.pem /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/private/central.key /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/issued/central.crt /config/auth/openvpn + vyos@vyos:/config/my-easy-rsa-config$ sudo cp pki/crl.pem /config/auth/openvpn Additionally, each client needs a copy of ca.crt and its own client key and cert files. The files are plaintext so they may be copied either manually, @@ -336,7 +336,7 @@ For example, Branch 1's router might have the following files: .. code-block:: none - vyos@branch1-rtr:$ ls /config/auth/ovpn + vyos@branch1-rtr:$ ls /config/auth/openvpn ca.crt branch1.crt branch1.key Client Authentication diff --git a/docs/configuration/protocols/mpls.rst b/docs/configuration/protocols/mpls.rst index 3b59d8ea..312a0df2 100644 --- a/docs/configuration/protocols/mpls.rst +++ b/docs/configuration/protocols/mpls.rst @@ -155,6 +155,12 @@ Configuration Options the Dual-Stack capability TLV for IPv6 LDP communications. This is related to :rfc:`7552`. +.. cfgcmd:: set protocols mpls ldp parameters ordered-control + + Use this command to use ordered label distribution control mode. FRR + by default uses independent label distribution control mode for label + distribution. This is related to :rfc:`5036`. + .. cfgcmd:: set protocols mpls ldp parameters transport-prefer-ipv4 Use this command to prefer IPv4 for TCP peer transport connection for LDP 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 <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. -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 <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 <domain> - :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 <domain> -* 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 <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 + + +.. cfgcmd:: set service webproxy reply-block-mime <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 <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 <number> - 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 -<http://www.squid-cache.org/Versions/v3/3.2/manuals/basic_ldap_auth.html>`_ + .. 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 <time> -.. code-block:: none + 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 cache-size - Possible completions: - <0-4294967295> - Disk cache size in MB (default 100) - 0 Disable disk caching - 100 + 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. + + +.. opcmd:: update webproxy blacklists + + Download/Update complete blacklist + + .. code-block:: none + + 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 + ... + + Building DB for [webmail/domains] - 374 entries + Building DB for [webmail/urls] - 9 entries + + 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. + +* To auto update the blacklist files + + :code:`set service webproxy url-filtering squidguard auto-update + update-hour 23` + +* To configure blocking add the following to the configuration + + :code:`set service webproxy url-filtering squidguard block-category ads` + + :code:`set service webproxy url-filtering squidguard block-category malware` Bypassing the webproxy -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- + +.. 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: @@ -153,5 +403,32 @@ So sometimes it is useful to bypass a transparent proxy: (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/ +******** +Examples +******** + +.. code-block:: none + + 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 + } + +.. _Squid: http://www.squid-cache.org/ +.. _SquidGuard: http://www.squidguard.org/ |