diff options
Diffstat (limited to 'docs/configuration')
| -rw-r--r-- | docs/configuration/firewall/index.rst | 112 | ||||
| -rw-r--r-- | docs/configuration/interfaces/openvpn.rst | 179 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wwan.rst | 4 | ||||
| -rw-r--r-- | docs/configuration/protocols/rip.rst | 12 |
4 files changed, 107 insertions, 200 deletions
diff --git a/docs/configuration/firewall/index.rst b/docs/configuration/firewall/index.rst index d52d6f2a..b4a884f0 100644 --- a/docs/configuration/firewall/index.rst +++ b/docs/configuration/firewall/index.rst @@ -17,7 +17,7 @@ The firewall supports the creation of groups for ports, addresses, and networks (implemented using netfilter ipset) and the option of interface or zone based firewall policy. -.. note:: **Important note on usage of terms:** +.. note:: **Important note on usage of terms:** The firewall makes use of the terms `in`, `out`, and `local` for firewall policy. Users experienced with netfilter often confuse `in` to be a reference to the `INPUT` chain, and `out` the `OUTPUT` @@ -91,35 +91,35 @@ Some firewall settings are global and have an affect on the whole system. .. cfgcmd:: set firewall send-redirects [enable | disable] - enable or disable ICMPv4 redirect messages send by VyOS + enable or disable ICMPv4 redirect messages send by VyOS The following system parameter will be altered: * ``net.ipv4.conf.all.send_redirects`` .. cfgcmd:: set firewall log-martians [enable | disable] - enable or disable the logging of martian IPv4 packets. + enable or disable the logging of martian IPv4 packets. The following system parameter will be altered: * ``net.ipv4.conf.all.log_martians`` .. cfgcmd:: set firewall source-validation [strict | loose | disable] - Set the IPv4 source validation mode. + Set the IPv4 source validation mode. The following system parameter will be altered: * ``net.ipv4.conf.all.rp_filter`` .. cfgcmd:: set firewall syn-cookies [enable | disable] - Enable or Disable if VyOS use IPv4 TCP SYN Cookies. + Enable or Disable if VyOS use IPv4 TCP SYN Cookies. The following system parameter will be altered: * ``net.ipv4.tcp_syncookies`` .. cfgcmd:: set firewall twa-hazards-protection [enable | disable] - Enable or Disable VyOS to be :rfc:`1337` conform. + Enable or Disable VyOS to be :rfc:`1337` conform. The following system parameter will be altered: * ``net.ipv4.tcp_rfc1337`` @@ -135,7 +135,7 @@ Some firewall settings are global and have an affect on the whole system. .. cfgcmd:: set firewall state-policy invalid log enable - Set the global setting for invalid packets. + Set the global setting for invalid packets. .. cfgcmd:: set firewall state-policy related action [accept | drop | reject] @@ -209,7 +209,7 @@ recommended. .. cfgcmd:: set firewall group ipv6-network-group <name> description <text> Provide a IPv4 or IPv6 network group description. - + Port Groups =========== @@ -292,7 +292,7 @@ Matching criteria There are a lot of matching criteria against which the package can be tested. -.. cfgcmd:: set firewall name <name> rule <1-9999> source address +.. cfgcmd:: set firewall name <name> rule <1-9999> source address [address | addressrange | CIDR] .. cfgcmd:: set firewall name <name> rule <1-9999> destination address [address | addressrange | CIDR] @@ -312,16 +312,16 @@ There are a lot of matching criteria against which the package can be tested. set firewall ipv6-name WAN-IN-v6 rule 100 source address 2001:db8::202 -.. cfgcmd:: set firewall name <name> rule <1-9999> source mac-address +.. cfgcmd:: set firewall name <name> rule <1-9999> source mac-address <mac-address> -.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source mac-address +.. cfgcmd:: set firewall ipv6-name <name> rule <1-9999> source mac-address <mac-address> Only in the source criteria, you can specify a mac-address. .. code-block:: none - set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 + set firewall name LAN-IN-v4 rule 100 source mac-address 00:53:00:11:22:33 set firewall name LAN-IN-v4 rule 101 source mac-address !00:53:00:aa:12:34 .. cfgcmd:: set firewall name <name> rule <1-9999> source port @@ -344,7 +344,7 @@ There are a lot of matching criteria against which the package can be tested. Multiple source ports can be specified as a comma-separated list. The whole list can also be "negated" using '!'. For example: - + .. code-block:: none set firewall ipv6-name WAN-IN-v6 rule 10 source port '!22,https,3333-3338' @@ -388,7 +388,7 @@ There are a lot of matching criteria against which the package can be tested. <0-255> | all | tcp_udp] Match a protocol criteria. A protocol number or a name which is here - defined: ``/etc/protocols``. + defined: ``/etc/protocols``. Special names are ``all`` for all protocols and ``tcp_udp`` for tcp and udp based packets. The ``!`` negate the selected protocol. @@ -404,7 +404,7 @@ There are a lot of matching criteria against which the package can be tested. Allowed values fpr TCP flags: ``SYN``, ``ACK``, ``FIN``, ``RST``, ``URG``, ``PSH``, ``ALL`` When specifying more than one flag, flags should be comma separated. The ``!`` negate the selected protocol. - + .. code-block:: none set firewall name WAN-IN-v4 rule 10 tcp flags 'ACK' @@ -429,7 +429,7 @@ A Rule-Set can be applied to every interface: * ``out``: Ruleset for forwarded packets on an outbound interface * ``local``: Ruleset for packets destined for this router -.. cfgcmd:: set interface ethernet <ethN> firewall [in | out | local] +.. cfgcmd:: set interface ethernet <ethN> firewall [in | out | local] [name | ipv6-name] <rule-set> Here are some examples for applying a rule-set to an interface @@ -487,7 +487,7 @@ To define a zone setup either one with interfaces or a local zone. Applying a Rule-Set to a Zone ============================= -Before you are able to apply a rule-set to a zone you have to create the zones +Before you are able to apply a rule-set to a zone you have to create the zones first. .. cfgcmd:: set zone-policy zone <name> from <name> firewall name @@ -629,7 +629,7 @@ Rule-set overview .. opcmd:: show firewall statistics This will show you a statistic of all rule-sets since the last boot. - + .. opcmd:: show firewall [name | ipv6name] <name> rule <1-9999> This command will give an overview of a rule in a single rule-set @@ -650,7 +650,7 @@ Rule-set overview 443 8080 8443 - + vyos@vyos:~$ show firewall group LANv4 Name : LANv4 Type : network @@ -775,77 +775,3 @@ Example Partial Config } } } - - -.. _routing-mss-clamp: - - -**************** -TCP-MSS Clamping -**************** - -As Internet wide PMTU discovery rarely works, we sometimes need to clamp -our TCP MSS value to a specific value. This is a field in the TCP -Options part of a SYN packet. By setting the MSS value, you are telling -the remote side unequivocally 'do not try to send me packets bigger than -this value'. - -Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS -value for IPv4 and IPv6. - - -.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting - in 1452 bytes on a 1492 byte MTU. - - - -IPv4 -==== - - -.. cfgcmd:: set firewall options interface <interface> adjust-mss - <number-of-bytes> - - Use this command to set the maximum segment size for IPv4 transit - packets on a specific interface (500-1460 bytes). - -Example -------- - -Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and -`1372` -for your WireGuard `wg02` tunnel. - -.. code-block:: none - - set firewall options interface pppoe0 adjust-mss '1452' - set firewall options interface wg02 adjust-mss '1372' - - - -IPv6 -==== - -.. cfgcmd:: set firewall options interface <interface> adjust-mss6 - <number-of-bytes> - - Use this command to set the maximum segment size for IPv6 transit - packets on a specific interface (1280-1492 bytes). - -.. _firewall:ipv6_example: - -Example -------- - -Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and -`wg02` interface. - -.. code-block:: none - - set firewall options interface pppoe0 adjust-mss6 '1280' - set firewall options interface wg02 adjust-mss6 '1280' - - - -.. hint:: When doing your byte calculations, you might find useful this - `Visual packet size calculator <https://baturin.org/tools/encapcalc/>`_. diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 02c5a797..e249af25 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -48,12 +48,11 @@ Site-to-site mode supports x.509 but doesn't require it and can also work with static keys, which is simpler in many cases. In this example, we'll configure a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key. -First, one of the systems generate the key using the operational command -``generate openvpn key <filename>``. This will generate a key with the name -provided in the ``/config/auth/`` directory. Once generated, you will need to -copy this key to the remote router. +First, one of the systems generate the key using the :ref:`generate pki openvpn shared-secret<configuration/pki/index:pki>` +command. Once generated, you will need to install this key on the local system, +then copy and install this key to the remote router. -In our example, we used the filename ``openvpn-1.key`` which we will reference +In our example, we used the key name ``openvpn-1`` which we will reference in our configuration. * The public IP address of the local side of the VPN will be 198.51.100.10. @@ -79,13 +78,18 @@ Local Configuration: .. code-block:: none + run generate pki openvpn shared-secret install openvpn-1 + Configure mode commands to install OpenVPN key: + set pki openvpn shared-secret openvpn-1 key 'generated_key_string' + set pki openvpn shared-secret openvpn-1 version '1' + set interfaces openvpn vtun1 mode site-to-site set interfaces openvpn vtun1 protocol udp set interfaces openvpn vtun1 persistent-tunnel set interfaces openvpn vtun1 remote-host '203.0.113.11 set interfaces openvpn vtun1 local-port '1195' set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 shared-secret-key openvpn-1 set interfaces openvpn vtun1 local-address '10.255.1.1' set interfaces openvpn vtun1 remote-address '10.255.1.2' @@ -93,13 +97,22 @@ Local Configuration - Annotated: .. code-block:: none + run generate pki openvpn shared-secret install openvpn-1 # Locally genearated OpenVPN shared secret. + The generated secret is the output to + the console. + Configure mode commands to install OpenVPN key: + set pki openvpn shared-secret openvpn-1 key 'generated_key_string' # Generated secret displayed in the output to + the console. + set pki openvpn shared-secret openvpn-1 version '1' # Generated secret displayed in the output to + the console. + set interfaces openvpn vtun1 mode site-to-site set interfaces openvpn vtun1 protocol udp set interfaces openvpn vtun1 persistent-tunnel set interfaces openvpn vtun1 remote-host '203.0.113.11' # Pub IP of other site set interfaces openvpn vtun1 local-port '1195' set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 shared-secret-key openvpn-1 # Locally generated secret name set interfaces openvpn vtun1 local-address '10.255.1.1' # Local IP of vtun interface set interfaces openvpn vtun1 remote-address '10.255.1.2' # Remote IP of vtun interface @@ -108,13 +121,16 @@ Remote Configuration: .. code-block:: none + set pki openvpn shared-secret openvpn-1 key 'generated_key_string' + set pki openvpn shared-secret openvpn-1 version '1' + set interfaces openvpn vtun1 mode site-to-site set interfaces openvpn vtun1 protocol udp set interfaces openvpn vtun1 persistent-tunnel set interfaces openvpn vtun1 remote-host '198.51.100.10' set interfaces openvpn vtun1 local-port '1195' set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 shared-secret-key openvpn-1 set interfaces openvpn vtun1 local-address '10.255.1.2' set interfaces openvpn vtun1 remote-address '10.255.1.1' @@ -122,13 +138,17 @@ Remote Configuration - Annotated: .. code-block:: none + set pki openvpn shared-secret openvpn-1 key 'generated_key_string' # Locally genearated OpenVPN shared secret + (from the Local Configuration Block). + set pki openvpn shared-secret openvpn-1 version '1' + set interfaces openvpn vtun1 mode site-to-site set interfaces openvpn vtun1 protocol udp set interfaces openvpn vtun1 persistent-tunnel set interfaces openvpn vtun1 remote-host '198.51.100.10' # Pub IP of other site set interfaces openvpn vtun1 local-port '1195' set interfaces openvpn vtun1 remote-port '1195' - set interfaces openvpn vtun1 shared-secret-key-file '/config/auth/openvpn-1.key' + set interfaces openvpn vtun1 shared-secret-key openvpn-1 # Locally generated secret name set interfaces openvpn vtun1 local-address '10.255.1.2' # Local IP of vtun interface set interfaces openvpn vtun1 remote-address '10.255.1.1' # Remote IP of vtun interface @@ -253,8 +273,8 @@ Server ****** Multi-client server is the most popular OpenVPN mode on routers. It always uses -x.509 authentication and therefore requires a PKI setup. Refer this section -**Generate X.509 Certificate and Keys** to generate a CA certificate, +x.509 authentication and therefore requires a PKI setup. Refer this topic +:ref:`configuration/pki/index:pki` to generate a CA certificate, a server certificate and key, a certificate revocation list, a Diffie-Hellman key exchange parameters file. You do not need client certificates and keys for the server setup. @@ -284,16 +304,30 @@ closing on connection resets or daemon reloads. set interfaces openvpn vtun10 persistent-tunnel set interfaces openvpn vtun10 protocol udp -Then we need to specify the location of the cryptographic materials. Suppose -you keep the files in `/config/auth/openvpn` +Then we need to generate, add and specify the names of the cryptographic materials. .. code-block:: none - set interfaces openvpn vtun10 tls ca-cert-file /config/auth/openvpn/ca.crt - set interfaces openvpn vtun10 tls cert-file /config/auth/openvpn/server.crt - set interfaces openvpn vtun10 tls key-file /config/auth/openvpn/server.key - set interfaces openvpn vtun10 tls crl-file /config/auth/openvpn/crl.pem - set interfaces openvpn vtun10 tls dh-file /config/auth/openvpn/dh2048.pem + run generate pki ca install ca-1 # Follow the instructions to generate CA cert. + Configure mode commands to install: + set pki ca ca-1 certificate 'generated_cert_string' + set pki ca ca-1 private key 'generated_private_key' + + run generate pki certificate sign ca-1 install srv-1 # Follow the instructions to generate server cert. + Configure mode commands to install: + set pki certificate srv-1 certificate 'generated_server_cert' + set pki certificate srv-1 private key 'generated_private_key' + + run generate pki dh install dh-1 # Follow the instructions to generate set of + Diffie-Hellman parameters. + Generating parameters... + Configure mode commands to install DH parameters: + set pki dh dh-1 parameters 'generated_dh_params_set' + + set interfaces openvpn vtun10 tls ca-certificate ca-1 + set interfaces openvpn vtun10 tls certificate srv-1 + set interfaces openvpn vtun10 tls crypt-key srv-1 + set interfaces openvpn vtun10 tls dh-params dh-1 Now we need to specify the server network settings. In all cases we need to specify the subnet for client tunnel endpoints. Since we want clients to access @@ -325,89 +359,30 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: set protocols static route 10.23.0.0/20 interface vtun10 -Generate X.509 Certificate and Keys -=================================== - -OpenVPN ships with a set of scripts called Easy-RSA that can generate the -appropriate files needed for an OpenVPN setup using X.509 certificates. -Easy-RSA comes installed by default on VyOS routers. - -Copy the Easy-RSA scripts to a new directory to modify the values. - -.. code-block:: none - - cp -r /usr/share/easy-rsa/ /config/my-easy-rsa-config - cd /config/my-easy-rsa-config - -To ensure the consistent use of values when generating the PKI, set default -values to be used by the PKI generating scripts. Rename the vars.example -filename to vars - -.. code-block:: none - - mv vars.example vars - -Following is the instance of the file after editing. You may also change other -values in the file at your discretion/need, though for most cases the defaults -should be just fine. (do not leave any of these parameters blank) - -.. code-block:: none - - set_var EASYRSA_DN "org" - set_var EASYRSA_REQ_COUNTRY "US" - set_var EASYRSA_REQ_PROVINCE "California" - set_var EASYRSA_REQ_CITY "San Francisco" - set_var EASYRSA_REQ_ORG "Copyleft Certificate Co" - set_var EASYRSA_REQ_EMAIL "me@example.net" - set_var EASYRSA_REQ_OU "My Organizational Unit" - set_var EASYRSA_KEY_SIZE 2048 - - -init-pki option will create a new pki directory or will delete any previously -generated certificates stored in that folder. The term 'central' is used to -refer server and 'branch' for client - -.. note:: Remember the “CA Key Passphrase” prompted in build-ca command, - as it will be asked in signing the server/client certificate. - -.. code-block:: none +Additionally, each client needs a copy of ca cert and its own client key and +cert files. The files are plaintext so they may be copied either manually from the CLI. +Client key and cert files should be signed with the proper ca cert and generated on the +server side. - vyos@vyos:/config/my-easy-rsa-config$./easyrsa init-pki - vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-ca - vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-req central nopass - vyos@vyos:/config/my-easy-rsa-config$./easyrsa sign-req server central - vyos@vyos:/config/my-easy-rsa-config$./easyrsa gen-dh - vyos@vyos:/config/my-easy-rsa-config$./easyrsa build-client-full branch1 nopass - -To generate a certificate revocation list for any client, execute these -commands: +HQ's router requires the following steps to generate crypto materials for the Branch 1: .. code-block:: none - - 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/openvpn/ to use in OpenVPN tunnel creation - -.. code-block:: none - - 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, -or through a remote file transfer tool like scp. Whichever method you use, -the files need to end up in the proper location on each router. -For example, Branch 1's router might have the following files: + + run generate pki certificate sign ca-1 install branch-1 # Follow the instructions to generate client + cert for Branch 1 + Configure mode commands to install: + +Branch 1's router might have the following lines: .. code-block:: none - vyos@branch1-rtr:$ ls /config/auth/openvpn - ca.crt branch1.crt branch1.key + set pki ca ca-1 certificate 'generated_cert_string' # CA cert generated on HQ router + set pki certificate branch-1 certificate 'generated_branch_cert' # Client cert generated and signed on HQ router + set pki certificate branch-1 private key 'generated_private_key' # Client cert key generated on HQ router + + set interfaces openvpn vtun10 tls ca-cert ca-1 + set interfaces openvpn vtun10 tls certificate branch-1 + set interfaces openvpn vtun10 tls crypt-key branch-1 Client Authentication ===================== @@ -575,10 +550,10 @@ Server Side set interfaces openvpn vtun10 server name-server '172.16.254.30' set interfaces openvpn vtun10 server subnet '10.10.0.0/24' set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' - set interfaces openvpn vtun10 tls cert-file '/config/auth/server.crt' - set interfaces openvpn vtun10 tls dh-file '/config/auth/dh.pem' - set interfaces openvpn vtun10 tls key-file '/config/auth/server.key' + set interfaces openvpn vtun10 tls ca-cert ca-1 + set interfaces openvpn vtun10 tls certificate srv-1 + set interfaces openvpn vtun10 tls crypt-key srv-1 + set interfaces openvpn vtun10 tls dh-params dh-1 set interfaces openvpn vtun10 use-lzo-compression .. _openvpn:client_client: @@ -595,9 +570,9 @@ Client Side set interfaces openvpn vtun10 protocol 'udp' set interfaces openvpn vtun10 remote-host '172.18.201.10' set interfaces openvpn vtun10 remote-port '1194' - set interfaces openvpn vtun10 tls ca-cert-file '/config/auth/ca.crt' - set interfaces openvpn vtun10 tls cert-file '/config/auth/client1.crt' - set interfaces openvpn vtun10 tls key-file '/config/auth/client1.key' + set interfaces openvpn vtun10 tls ca-cert ca-1 + set interfaces openvpn vtun10 tls certificate client-1 + set interfaces openvpn vtun10 tls crypt-key client-1 set interfaces openvpn vtun10 use-lzo-compression Options diff --git a/docs/configuration/interfaces/wwan.rst b/docs/configuration/interfaces/wwan.rst index 0c820471..eb530c27 100644 --- a/docs/configuration/interfaces/wwan.rst +++ b/docs/configuration/interfaces/wwan.rst @@ -39,6 +39,10 @@ Common interface configuration :var0: wwan :var1: wwan0 +.. cmdinclude:: /_include/interface-adjust-mss.txt + :var0: wwan + :var1: wwan0 + .. cmdinclude:: /_include/interface-ip.txt :var0: wwan :var1: wwan0 diff --git a/docs/configuration/protocols/rip.rst b/docs/configuration/protocols/rip.rst index 4d46e2f0..fd20a90c 100644 --- a/docs/configuration/protocols/rip.rst +++ b/docs/configuration/protocols/rip.rst @@ -1,3 +1,5 @@ +:lastproofread: 2021-10-04 + .. _rip: ### @@ -57,20 +59,20 @@ Optional Configuration .. cfgcmd:: set protocols rip default-distance <distance> - This command change distance value of RIP. The distance range is 1 to 255. + This command change the distance value of RIP. The distance range is 1 to 255. .. note:: Routes with a distance of 255 are effectively disabled and not installed into the kernel. .. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> distance <distance> - This command sets default RIP distance to specified value when the route’s + This command sets default RIP distance to a specified value when the routes source IP address matches the specified prefix. .. cfgcmd:: set protocols rip network-distance <A.B.C.D/M> access-list <name> This command can be used with previous command to sets default RIP distance - to specified value when the route’s source IP address matches the specified + to specified value when the route source IP address matches the specified prefix and the specified access-list. .. cfgcmd:: set protocols rip default-information originate @@ -156,7 +158,7 @@ Redistribution Configuration This command modifies the default metric (hop count) value for redistributed routes. The metric range is 1 to 16. The default value is 1. This command does not affect connected route even if it is redistributed by - :cfgcmd:`redistribute connected`. To modify connected route’s metric + :cfgcmd:`redistribute connected`. To modify connected routes metric value, please use :cfgcmd:`redistribute connected metric`. @@ -178,7 +180,7 @@ Interfaces Configuration This command disables split-horizon on the interface. By default, VyOS does not advertise RIP routes out the interface over which they were learned - (split horizon). + (split horizon).3 .. cfgcmd:: set interfaces <inttype> <intname> ip rip split-horizon poison-reverse |