diff options
Diffstat (limited to 'docs/configuration')
32 files changed, 2955 insertions, 2078 deletions
diff --git a/docs/configuration/container/index.rst b/docs/configuration/container/index.rst index 5882f6db..228754cc 100644 --- a/docs/configuration/container/index.rst +++ b/docs/configuration/container/index.rst @@ -282,6 +282,20 @@ Container Registry set container registry 192.168.1.1:8080 insecure +Log Configuration +==================== + +.. cfgcmd:: set container name <name> log-driver [k8s-file | journald | none] + + Set the default log driver for containers. + + - **k8s-file**: Log to a plain text file in Kubernetes-style format. + - **journald**: Log to the system journal + - **none**: Disable logging for the container + + Current default is journald. + + ****************** Operation Commands ****************** diff --git a/docs/configuration/firewall/groups.rst b/docs/configuration/firewall/groups.rst index b7364154..b1accca5 100644 --- a/docs/configuration/firewall/groups.rst +++ b/docs/configuration/firewall/groups.rst @@ -37,6 +37,38 @@ In an **address group** a single IP address or IP address range is defined. Provide a IPv4 or IPv6 address group description +Remote Groups +============== + +A **remote-group** takes an argument of a URL hosting a linebreak-deliminated +list of IPv4 and/or IPv6 addresses, CIDRs and ranges. VyOS will pull this list periodicity +according to the frequency defined in the firewall **resolver-interval** and load +matching entries into the group for use in rules. The list will be cached in +persistent storage, so in cases of update failure rules will still function. + +.. cfgcmd:: set firewall group remote-group <name> url <http(s) url> + + Define remote list of IPv4 and/or IPv6 addresses/ranges/CIDRs to fetch + +.. cfgcmd:: set firewall group remote-group <name> description <text> + + Set a description for a remote group + +The format of the remote list is very flexible. VyOS will attempt to parse the +first word of each line as an entry, and will skip if it cannot find a valid +match. Lines that begin with an alphanumeric character but do not match valid IPv4 +or IPv6 addresses, ranges, or CIDRs will be logged to the system log. Below is a +list of acceptable matches that would be parsed correctly: + +.. code-block:: none + + 127.0.0.1 + 127.0.0.0/24 + 127.0.0.1-127.0.0.254 + 2001:db8::1 + 2001:db8:cafe::/48 + 2001:db8:cafe::1-2001:db8:cafe::ffff + Network Groups ============== @@ -231,7 +263,7 @@ As any other firewall group, dynamic firewall groups can be used in firewall rules as matching options. For example: .. code-block:: none - + set firewall ipv4 input filter rule 10 source group dynamic-address-group FOO set firewall ipv4 input filter rule 10 destination group dynamic-address-group BAR @@ -245,10 +277,10 @@ General example As said before, once firewall groups are created, they can be referenced either in firewall, nat, nat66 and/or policy-route rules. -Here is an example were multiple groups are created: +Here is an example were multiple groups are created: .. code-block:: none - + set firewall group address-group SERVERS address 198.51.100.101 set firewall group address-group SERVERS address 198.51.100.102 set firewall group network-group TRUSTEDv4 network 192.0.2.0/30 @@ -263,7 +295,7 @@ Here is an example were multiple groups are created: And next, some configuration example where groups are used: .. code-block:: none - + set firewall ipv4 output filter rule 10 action accept set firewall ipv4 output filter rule 10 outbound-interface group !LAN set firewall ipv4 forward filter rule 20 action accept @@ -426,4 +458,4 @@ Here is an example of such command: PORT-SERVERS port_group route-PBR-201 443 route-PBR-201 5000-5010 nat-destination-101 http - vyos@vyos:~$
\ No newline at end of file + vyos@vyos:~$ diff --git a/docs/configuration/firewall/zone.rst b/docs/configuration/firewall/zone.rst index 0e659247..836d29fc 100644 --- a/docs/configuration/firewall/zone.rst +++ b/docs/configuration/firewall/zone.rst @@ -65,60 +65,94 @@ Configuration As an alternative to applying policy to an interface directly, a zone-based firewall can be created to simplify configuration when multiple interfaces belong to the same security zone. Instead of applying rule-sets to interfaces, -they are applied to source zone-destination zone pairs. +they are applied to source-destination zone pairs. A basic introduction to zone-based firewalls can be found `here <https://support.vyos.io/en/kb/articles/a-primer-to-zone-based-firewall>`_, and an example at :ref:`examples-zone-policy`. +The following steps are required to create a zone-based firewall: + +1. Define both the source and destination zones +2. Define the rule-set +3. Apply the rule-set to the zones + Define a Zone ============= -To define a zone setup either one with interfaces or a local zone. +To define a zone setup either one with interfaces or the local zone. .. cfgcmd:: set firewall zone <name> interface <interface> - Set interfaces to a zone. A zone can have multiple interfaces. - But an interface can only be a member in one zone. + Assign interfaces as a member of a zone. + + .. note:: + + * An interface can only be a member of one zone. + * A zone can have multiple interfaces, with traffic between interfaces in + the same zone subject to the intra-zone-filtering policy (allowed by + default). .. cfgcmd:: set firewall zone <name> local-zone - Define the zone as a local zone. A local zone has no interfaces and - will be applied to the router itself. + Define the zone as the local zone, for traffic originating from and destined + to the router itself. + + .. note:: + + * A local zone cannot have any member interfaces + * There cannot be multiple local zones .. cfgcmd:: set firewall zone <name> default-action [drop | reject] - Change the default-action with this setting. + Change the zone default-action, which applies to traffic destined to this + zone that doesn't match any of the source zone rulesets applied. + +.. cfgcmd:: set firewall zone <name> default-log + + Enable logging of packets that hit this zone's default-action (disabled by + default). .. cfgcmd:: set firewall zone <name> description Set a meaningful description. -Applying a Rule-Set to a Zone +Defining a Rule-Set ============================= -Before you are able to apply a rule-set to a zone you have to create the zones -first. +Zone-based firewall rule-sets are for traffic from a *Source Zone* to a +*Destination Zone*. -It helps to think of the syntax as: (see below). The 'rule-set' should be -written from the perspective of: *Source Zone*-to->*Destination Zone* +The rule-sets are created as a custom firewall chain using the commands below +(refer to the firewall IPv4/IPv6 sections for the full syntax): -.. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> - firewall name <rule-set> +* For :ref:`IPv4<configuration/firewall/ipv4:Firewall - IPv4 Rules>`: + ``set firewall ipv4 name <name> ...`` +* For :ref:`IPv6<configuration/firewall/ipv6:Firewall - IPv6 Rules>`: + ``set firewall ipv6 name <name> ...`` -.. cfgcmd:: set firewall zone <name> from <name> firewall name - <rule-set> +It can be helpful to name the rule-sets in the format +``<Sourze Zone>-<Destination Zone>-<v4 | v6>`` to make them easily identifiable. -.. cfgcmd:: set firewall zone <name> from <name> firewall ipv6-name - <rule-set> +Applying a Rule-Set to a Zone +============================= - You apply a rule-set always to a zone from an other zone, it is recommended - to create one rule-set for each zone pair. +Once a rule-set has been defined, it can then be applied to the source and +destination zones. The configuration syntax is anchored on the destination +zone, with each of the source zone rulesets listed against the destination. - .. code-block:: none +.. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> + firewall name <ipv4-rule-set-name> + +.. cfgcmd:: set firewall zone <Destination Zone> from <Source Zone> + firewall ipv6-name <ipv6-rule-set-name> + +It is recommended to create two rule-sets for each source-destination zone pair. - set firewall zone DMZ from LAN firewall name LANv4-to-DMZv4 - set firewall zone LAN from DMZ firewall name DMZv4-to-LANv4 +.. code-block:: none + + set firewall zone DMZ from LAN firewall name LAN-DMZ-v4 + set firewall zone LAN from DMZ firewall name DMZ-LAN-v4 ************** Operation-mode @@ -133,13 +167,12 @@ Operation-mode vyos@vyos:~$ show firewall zone-policy Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------ ------------ ----------- --------------- --------------- - LAN eth1 WAN WAN_to_LAN + LAN eth1 WAN WAN-LAN-v4 eth2 - LOCAL LOCAL LAN LAN_to_LOCAL - WAN WAN_to_LOCAL WAN_to_LOCAL_v6 - WAN eth3 LAN LAN_to_WAN - eth0 LOCAL LOCAL_to_WAN - vyos@vyos:~$ + LOCAL LOCAL LAN LAN-LOCAL-v4 + WAN WAN-LOCAL-v4 WAN-LOCAL-v6 + WAN eth3 LAN LAN-WAN-v4 + eth0 LOCAL LOCAL-WAN-v4 .. opcmd:: show firewall zone-policy zone <zone> @@ -150,11 +183,11 @@ Operation-mode vyos@vyos:~$ show firewall zone-policy zone WAN Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------ ------------ ----------- --------------- --------------- - WAN eth3 LAN LAN_to_WAN - eth0 LOCAL LOCAL_to_WAN + WAN eth3 LAN LAN-WAN-v4 + eth0 LOCAL LOCAL-WAN-v4 + vyos@vyos:~$ show firewall zone-policy zone LOCAL Zone Interfaces From Zone Firewall IPv4 Firewall IPv6 ------ ------------ ----------- --------------- --------------- - LOCAL LOCAL LAN LAN_to_LOCAL - WAN WAN_to_LOCAL WAN_to_LOCAL_v6 - vyos@vyos:~$ + LOCAL LOCAL LAN LAN-LOCAL-v4 + WAN WAN-LOCAL-v4 WAN-LOCAL-v6 diff --git a/docs/configuration/interfaces/index.rst b/docs/configuration/interfaces/index.rst index 0f02d1e3..46d521b0 100644 --- a/docs/configuration/interfaces/index.rst +++ b/docs/configuration/interfaces/index.rst @@ -26,5 +26,3 @@ Interfaces vxlan wireless wwan - - diff --git a/docs/configuration/interfaces/openvpn-examples.rst b/docs/configuration/interfaces/openvpn-examples.rst new file mode 100644 index 00000000..c380e7a8 --- /dev/null +++ b/docs/configuration/interfaces/openvpn-examples.rst @@ -0,0 +1,855 @@ + +Site-to-Site +============ + +OpenVPN is popular for client-server setups, but its site-to-site mode +remains a relatively obscure feature, and many router appliances +still don't support it. However, it's very useful for quickly setting up +tunnels between routers. + +As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or +x.509 certificates. + +The pre-shared key mode is deprecated and will be removed from future OpenVPN +versions, so VyOS will have to remove support for that option as well. The +reason is that using pre-shared keys is significantly less secure than using TLS. + +We'll configure OpenVPN using self-signed certificates, and then discuss the +legacy pre-shared key mode. + +In both cases, we will use the following settings: + +* The public IP address of the local side of the VPN will be 198.51.100.10. +* The public IP address of the remote side of the VPN will be 203.0.113.11. +* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. +* The local site will have a subnet of 10.0.0.0/16. +* The remote site will have a subnet of 10.1.0.0/16. +* The official port for OpenVPN is 1194, which we reserve for client VPN; we + will use 1195 for site-to-site VPN. +* The ``persistent-tunnel`` directive will allow us to configure tunnel-related + attributes, such as firewall policy as we would on any normal network + interface. +* If known, the IP of the remote router can be configured using the + ``remote-host`` directive; if unknown, it can be omitted. We will assume a + dynamic IP for our remote router. + +.. figure:: /_static/images/openvpn_site2site_diagram.jpg + +Setting up certificates +----------------------- + +Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose +of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity, +compared to server setups that need to support multiple clients. + +However, since VyOS 1.4, it is possible to verify self-signed certificates using +certificate fingerprints. + +On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type. +You can generate them by executing command ``run generate pki certificate self-signed install <name>`` in the configuration mode. +Once the command is complete, it will add the certificate to the configuration session, to the ``pki`` subtree. +You can then review the proposed changes and commit them. + +.. code-block:: none + + vyos@vyos# run generate pki certificate self-signed install openvpn-local + Enter private key type: [rsa, dsa, ec] (Default: rsa) ec + Enter private key bits: (Default: 256) + Enter country code: (Default: GB) + Enter state: (Default: Some-State) + Enter locality: (Default: Some-City) + Enter organization name: (Default: VyOS) + Enter common name: (Default: vyos.io) + Do you want to configure Subject Alternative Names? [y/N] + Enter how many days certificate will be valid: (Default: 365) + Enter certificate type: (client, server) (Default: server) + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + [edit] + + vyos@vyos# compare + [pki] + + certificate openvpn-local { + + certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" + + private { + + key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" + + } + + } + + [edit] + + vyos@vyos# commit + +You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint. +OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command: + +.. code-block:: none + + vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 + 5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 + +Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary. + +Repeat the procedure on the other router. + +Setting up OpenVPN +------------------ + +Local Configuration: + +.. code-block:: none + + Configure the tunnel: + + 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' # Public IP of the other side + set interfaces openvpn vtun1 local-port '1195' + set interfaces openvpn vtun1 remote-port '1195' + 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 + set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate + set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the remote router + set interfaces openvpn vtun1 tls role active + +Remote Configuration: + +.. code-block:: none + + 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 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 + set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate + set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the local router + set interfaces openvpn vtun1 tls role passive + +Pre-shared keys +--------------- + +Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use +pre-shared keys. That option is still available but it is deprecated and will +be removed in the future. However, if you need to set up a tunnel to an older +VyOS version or a system with older OpenVPN, you need to still need to know how +to use it. + +First, you need to generate a key by running ``run generate pki openvpn shared-secret install <name>`` from configuration mode. +You can use any name, we will use ``s2s``. + +.. code-block:: none + + vyos@local# run generate pki openvpn shared-secret install s2s + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + [edit] + vyos@local# compare + [pki openvpn shared-secret] + + s2s { + + key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" + + version "1" + + } + + [edit] + + vyos@local# commit + [edit] + +Then you need to install the key on the remote router: + +.. code-block:: none + + vyos@remote# set pki openvpn shared-secret s2s key <generated key string> + +Then you need to set the key in your OpenVPN interface settings: + +.. code-block:: none + + set interfaces openvpn vtun1 shared-secret-key s2s + +Firewall Exceptions +------------------- + +For the OpenVPN traffic to pass through the WAN interface, you must create a +firewall exception. + +.. code-block:: none + + set firewall ipv4 name OUTSIDE_LOCAL rule 10 action 'accept' + set firewall ipv4 name OUTSIDE_LOCAL rule 10 description 'Allow established/related' + set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'established' + set firewall ipv4 name OUTSIDE_LOCAL rule 10 state 'related' + set firewall ipv4 name OUTSIDE_LOCAL rule 20 action 'accept' + set firewall ipv4 name OUTSIDE_LOCAL rule 20 description 'OpenVPN_IN' + set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port '1195' + set firewall ipv4 name OUTSIDE_LOCAL rule 20 log + set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol 'udp' + +You should also ensure that the OUTISDE_LOCAL firewall group is applied to the +WAN interface and applied to input filter where traffic destined for the router itself + +.. code-block:: none + + set firewall ipv4 input filter rule 10 action 'jump' + set firewall ipv4 input filter rule 10 inbound-interface name eth0 + set firewall ipv4 input filter rule 10 jump-target OUTSIDE_LOCAL + +Static Routing: + +Static routes can be configured referencing the tunnel interface; for example, +the local router will use a network of 10.0.0.0/16, while the remote has a +network of 10.1.0.0/16: + +Local Configuration: + +.. code-block:: none + + set protocols static route 10.1.0.0/16 interface vtun1 + +Remote Configuration: + +.. code-block:: none + + set protocols static route 10.0.0.0/16 interface vtun1 + +Firewall policy can also be applied to the tunnel interface for input, output and forward directions and functions identically to ethernet interfaces. + +If you are making use of multiple tunnels, OpenVPN must have a way to distinguish between different tunnels aside from the pre-shared-key. This is done either by referencing IP addresses or port numbers. +One option is to dedicate a public IP to each tunnel. Another option is to dedicate a port number to each tunnel (e.g. 1195,1196,1197…). + +OpenVPN status can be verified using the show openvpn operational commands. + +.. code-block:: none + + vyos@vyos:~$ show openvpn site-to-site + + OpenVPN status on vtun1 + + Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since + ----------- ----------------- ----------- ------------ ---------- ---------- ----------------- + N/A 10.110.12.54:1195 N/A N/A 504.0 B 656.0 B N/A + + +Server-Client +============= + +OpenVPN’s server-client mode is a configuration setup where server device acts +as a central hub that multiple other machines (the clients) connect to securely +route their traffic or access a private network. +Multi-client server is the most popular OpenVPN mode on routers. + + +Setting up certificates +----------------------- + +Client-Server always uses x.509 authentication and therefore requires a PKI setup. +The PKI utility now simplifies the creation of Certificate Authorities (CAs), +server and client certificates, and Diffie-Hellman keys directly from the VyOS +using configuration or operational mode commands. + +Usually on server side, you can generate all certificates by executing these +commands in the configuration mode. Once the command is complete, it will add +the certificate to the configuration session, to the ``pki`` subtree. + +Certificate Authority (CA) + +.. code-block:: none + + vyos@vyos# run generate pki ca install ca-1 + Enter private key type: [rsa, dsa, ec] (Default: rsa) + Enter private key bits: (Default: 2048) + Enter country code: (Default: GB) + Enter state: (Default: Some-State) + Enter locality: (Default: Some-City) + Enter organization name: (Default: VyOS) + Enter common name: (Default: vyos.io) ca-1 + Enter how many days certificate will be valid: (Default: 1825) + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + [edit] + vyos@vyos# compare + [pki] + + ca ca-1 { + + certificate "MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4EFgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZzph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHwY6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZWXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyxzRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55YmtmctGO2o+NBCFi0=" + + private { + + key "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDi+v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnDrxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIhBL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs5ggIJYZZkixsCisbtEmbAgMBAAECggEAZdykF6wV8Z4n8NsoG4j8E/ZJbWEhWjO3x1y3JNutJw735LhmmysMSsreToXtxGfgYRTgNwt5l7oHoqmGHCsLxO1NBb5A7JBllIkIwUYqn31syOJofg0NsJpuwZ2zVLfvWe5mGg4tV2lvVPNEWXWwbp+Ow2KLcFWXkA+H8tFuW6F2mH3ntYlIi/WiCNjsEotNx8Kk7OVwt43DbkN/rbF5lxquuLedaSspOHuhIAOfZB5ZySfqohQalSAaguVD66rGPMrerZ2Vc7B1iJ6Mn/KZrSaQeHwyWrwDDHdzVwG9waydevtGTVO0dvH4etWnRypDx8p1FPJJKD4XVcsl3rR6oQKBgQD497Ep2RJcbNnKVj+kNXGriSGmyRSp6CL61KotepzgucK0RtGMeFJge56/otMHMAxIOcDMX6vRn2MB2pqVqwqUBQy6JfLrSemdpIjMN9xlX6Dw3BWP39SdewZ896/Eo0Q1ythMj1ORp+u3PqOlSa14Cy9aPwDWmNy2deD68YDnsQKBgQDpZE/T84BMQ0FzL6NRijZRzR6Dc775hRfmmSTYI0KqpG0gXNSc5UgrWSLN5H7fnx36mT01P7UkgXCInV0AlJOfkt4a8QTqM1Fh/rZbLLWpQE55S6Fs28GDiFYl2kvZT/TtxhA/E0POf/YXl/8KITS7ZVAZxE8rxBe1hVUfDbnlCwKBgQDeWUguGaGeTdCMNk8MNnbYPdaCAB+mRp3G6ls51sF4qi5Lltva2jKn3H/AoohZaP3vGzUm0WLACdsAct2QQXtnCsN9FBtJK2+qzKEn0dPR7X/s3IGdRse6BX+b6BFgSnfGmuxmI7L86L1JoHXCTnTQOx0FOjNjdI3ZnplZRIpdYQKBgFJacASU9l9yl+SiGZnLEDG7FBpEPE3lVbKrtSGDB6IY1NzHhMo76URKdop6Jv6XMcfcTIm+ihdwiRnblRaAVrrG4xJUm2xcYUoXy5bOZudq5oXMVxCHVngoImXG6l6q5P0Fl3P6Q0HZSye2HWsgnm/FZwdAisMhtU/61TdY65BTAoGBAM4jKeImiXta5lz1RgNiW/TPhft3UbOLj3TbzchNCNAamqCv4Tmh9YKB2d/mz2hNxbnAGe2cYn4iRYKcjJLMZ0UfBL2WxlrgQYQPPGzSD0fH1pLIXPohpBZpsGqNR3Nc8Jd+Uw3IiIJ2oxPCOPTOJsklNB0Xf1AlUUagB16bhhZZ" + + } + + } + + [edit] + vyos@vyos# commit + + +Server Certificate + +.. code-block:: none + + vyos@vyos# run generate pki certificate sign ca-1 install srv-1 + Do you already have a certificate request? [y/N] N + Enter private key type: [rsa, dsa, ec] (Default: rsa) + Enter private key bits: (Default: 2048) + Enter country code: (Default: GB) + Enter state: (Default: Some-State) + Enter locality: (Default: Some-City) + Enter organization name: (Default: VyOS) + Enter common name: (Default: vyos.io) srv-1 + Do you want to configure Subject Alternative Names? [y/N] + Enter how many days certificate will be valid: (Default: 365) + Enter certificate type: (client, server) (Default: server) server + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] + 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + [edit] + vyos@vyos# compare + [pki certificate] + + srv-1 { + + certificate "MIIDrDCCApSgAwIBAgIULpu+qZjfG01kUI58XNmqXbQC3qQwDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTMxMDJaFw0yNjA2MTExMTMxMDJaMFUxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxDjAMBgNVBAMMBXNydi0xMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAysTrMfVH63aVidJT7bIf+zLwkLse07nGsv4aliGEbufr239RBHV4Jn8LbQ+nB/8mhYGjNY4OnZ7NYz3FU/iglo8qFtaZ26mWtPWpv2xW1F8JAEK7l5BAg42cBucxiIZFeRm+jkE6VN1bcNU0utnn3sbCwZMyH6pS9k08G1qrrFLA7ZFhv5AmgJcODmO8sigSAu7rRS/6O3eO6ICnVjvIfHLb+9DKKUEffHzFV8RrkqVCGmgisz9fF+j1Rvg9s+ylNc2lZJTbb1XnzixvSRro4t9I3uIWdpJ0iOu09YiTXGQgH9ER6V3rFiX00RdSiSXf+MJCV64hC1msg+8V3Nrw9QIDAQABo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUzH0h4vBxma89HF9rUQ+DW052c5swHwYDVR0jBBgwFoAUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAI/Cyd0y7AJ7wY3yRssCud2iJAl9/ZjgxzXOUo6ibawYIYOnSf9tS3eD4CIH4BgppDXoJZ/qEA4WvIsLx3yvnyOxiqyk3TQmKIZ27VJH+yQkgzPeiKrHn1pCXBKEb1/jlT8Ozu4Lmn/oFwDH6nk8toxI8DM+qsTxqUFlTA3ea9yaRtxeNPMWJdaxZSUYGVSZL0wVKw5ZuQ1Gn7vGVApWlYDKYbMozCuZUG1q8wMzFBRa7x0anvh5hM4bksLz+Y1ujCS8f8b4Xtb8KIdFrZtTvtl97crv62bN05VueAcbwtYbIBNWNoT/CvmqV7k3uPg95GYSNddFqEMbQHoyd8hdDCo=" + + private { + + key "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDKxOsx9UfrdpWJ0lPtsh/7MvCQux7Tucay/hqWIYRu5+vbf1EEdXgmfwttD6cH/yaFgaM1jg6dns1jPcVT+KCWjyoW1pnbqZa09am/bFbUXwkAQruXkECDjZwG5zGIhkV5Gb6OQTpU3Vtw1TS62efexsLBkzIfqlL2TTwbWqusUsDtkWG/kCaAlw4OY7yyKBIC7utFL/o7d47ogKdWO8h8ctv70MopQR98fMVXxGuSpUIaaCKzP18X6PVG+D2z7KU1zaVklNtvVefOLG9JGuji30je4hZ2knSI67T1iJNcZCAf0RHpXesWJfTRF1KJJd/4wkJXriELWayD7xXc2vD1AgMBAAECggEACsUk3PVzSX11+ekTDigM7NHK11UpEQPoGu/GR70mBKIK9BCyI/N9W0YaPEO9kn4p9KNrINgXzKV3sVLBnXEyTmzyRl5Fs9YxLBF0X7eIcSVPHBVvU2CVHKez5uX2ypKfNAx7A6FRUNqlFbwtXdNfLoUOKSwBWI86ctytWaKaRb/TTSGQkaP/z/cwIsXOLfG9m6iFkw98ShUzalrUWNo/4fJKlO1+DvXVYE9sv9rjD8J7DtAbr5KykQ5n0AAlZTCWQ7jwMybSnjjY9ypZUms0l17raJrfhrdbWayc6xMDvtrmNIDebkF+J7cHU06aEV+yQXV/7yjyZgUSM2ANcHMdzQKBgQDmTi5tUeaj1JUSl9lAP/XUzcElw2tcU1B8qpX69J4ofjTNgj5okLWQZVIy1UyAfLOI3LJbHTBUtSvedhH0VaMulq99NXs5qnbPGG3//RBAc0wKhJknB5Qv0D3FxMI14kMO6jzPly+aIGEk4dTtHvZuHbbVHbKSZ5MMouLyT+SS7wKBgQDhZETARZ0MazeWRaPJwdkjlfNcqqcsnDicdcppCkcDCjeLxkVPZc8ej37rshOvw2Pf1D0PddGyOhJoWCWA8QE2LQoDHLaDnQ0L6aQ3yjN5Gxx9RCDFi3Zuat/mPcv3tFO7uUmeYvRC5fGYrghq29NADmUefOopAc06Izd4A3iqWwKBgQC1uPrpR7a1jwgRo7/I8q8HO1MseQY903+u3ut5GYuyZ+NCRYL4/zZEua4ibivvNnZzh7E0M9PvAwWag4+nO+uG11+hbJHO7rLQtnYVh5lLQa6+neI66cAD+kzDwH1+BwriufFB3Amzk9kTQR7B+6x3NvsNLmG5JADj96Mbj+7MAQKBgFIevEXplyzdK6WevexWqoyip8aNjtdcG+w1pofa7MCYymAs3zfseihCVBYADdguModsxsqJPNvY+Lf31cJDDRP2GP3FSmJtqEE84U5KZ7KqRBkH54DSLVZRrj4vKc+YbiGpgr8ogqKVMQ9V6U81xKREGmefT5mdRG74Qc+CREadAoGAFtdsH5js1yFEeGFad4BZJ69grEavD3pNCfIe9oIPtXvvFdzxd+QbKgqFf3JMJp/HYi8A0iv/i4mzf00KXzF4JU7bIJYrUVlk/w8x77gzDRIphsPqpMBJkTI0jisQHZKWNEe7IbmM/dWW2S4jvCkrhB7F5Szf72Q+j/lPbfx2g/8=" + + } + + } + + [edit] + vyos@vyos# commit + + +DH Key + +.. code-block:: none + + vyos@vyos# run generate pki dh install dh-1 + Enter DH parameters key size: (Default: 2048) + Generating parameters... + 1 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. + [edit] + vyos@vyos# compare + [pki] + + dh dh-1 { + + parameters "MIIBCAKCAQEAp25kxwZeLZ7wcbRii5E5RD4uWCUOBxarzKEE0msa84omh5nZ9dv/4bfJw4gIXlA2+sGc2lLV/jajZminMryiSwJdisyVuUdOB7sJWZwrzHBAY0qFbNyaRMVJBar2xVm+XcKd3A2eNTEgn10G7rPPvf6CJ5isUKFaKT8ymUv+mI0upLneYdGs8/yS3sAojzeulCf49fa5SiaGCcZZkdOI3Nby1u/ZG4okqJ2wE2c2hRVLs1k5qrrono0OF4Dh0B91ihnywRfp1xPYeqpiln+OPh+PPgTuBxkz4VxwRDoQ+NhVr/LOCb3vbhnyFisxI0w4r3109cA3QiDmo1L14aKl1wIBAg==" + + } + + [edit] + vyos@vyos# commit + +Client Certificate + +.. code-block:: none + + vyos@vyos:~$ generate pki certificate sign ca-1 install client1 + Do you already have a certificate request? [y/N] N + Enter private key type: [rsa, dsa, ec] (Default: rsa) + Enter private key bits: (Default: 2048) + Enter country code: (Default: GB) + Enter state: (Default: Some-State) + Enter locality: (Default: Some-City) + Enter organization name: (Default: VyOS) + Enter common name: (Default: vyos.io) client1 + Do you want to configure Subject Alternative Names? [y/N] + Enter how many days certificate will be valid: (Default: 365) + Enter certificate type: (client, server) (Default: server) client + Note: If you plan to use the generated key on this router, do not encrypt the private key. + Do you want to encrypt the private key with a passphrase? [y/N] + You are not in configure mode, commands to install manually from configure mode: + set pki certificate client1 certificate 'MIIDrjCCApagAwIBAgIUPvtffeYTdoOiHxu++wdrjHwwVX4wDQYJKoZIhvcNAQELBQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2MTExMTQxMDlaFw0yNjA2MTExMTQxMDlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0PAQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQnUyqEzG+AqZzsdSud5MDqsOxiXTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTANBgkqhkiG9w0BAQsFAAOCAQEAplItvZpoX/joG3QREu9tHVKwDTmXB2lwUM5G8iKPgd6D6oOILZMe2KuvWt12dcdEzUCGfJwJJ8M8R2WD0OmcLdFqvM/8UM1hYzUP2BCnFCLtElVD+b4wMlQNpdHqNbdckw8J4MLQlhUgu9rZAZ0XjWCprr+U50bX++vYRw7Un3Ds6ETEvjflm5WAPb2e0V1hhISPl8K+VXO7RAwxy0DHcDuR+YaD+hnNgMsJV3/QwA17Iy8x86RpOgqmesbt0U7e9Rmo81aVgiy/V4OCV7u6bPX03fmZNS8UwwJuRUlxkjO+epHNYB2cnOcjSkUxaIJ9Hv3tMWHQEtbVZsNYSOZozw==' + set pki certificate client1 private key 'MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC9H6E6gm0PfXO1n/WoA9xlg89/bnScLmfztVDn1uyNn8epE6zAi2GWBhtj4ixLllIwLdkJ7L2mF3yUZtA1Q0oYbGIqTbnaZ37JydCygVGnlLT7UX9zfRfS3KebCIvIte7OyCmnUfVfFzdIsp+4LI3S2wX/9Vyn4UBAR8QQNbezRB3XPMk9gzULnuLhmEDP6GVcPq7RzGXoXUMqsCxfEOJBjej0y4ANKH07HGVVrfVRiY+zlGkM4TFjVuZKnEA0BO6dhOA0E+7gsIXsC06UzzatkjsyWHpb2/DOECIifBoYej9DITu8VxyyZmgaINHEn2gGb0LRHO7rvQapc+XZ2z9DAgMBAAECggEAPS/Fhtt5k2BgFivZW3FcVc+OS0keGwV8hkFsGoXTZIKEIzSFWIn/mX0CUY90C0Rn9MRwiqB4PwssOAsHY6QQjdRK8irRbVK8l2ZeydHC7DfVUdXtKR0YnxTaePML3nTV/TqPF14Rx6EINtHrkLeBbu2DhGsKfhoHIoTVbvUiKLHa2TkGJOkhvjsyMSPKzUXa1AzLmu+UBIhRYpEPHj0SQUUJJnKgIb7mTR2fhJScHcKwsrPq6S8OpChvsYZ6zatgrTFz9tuhD4IjL7NBiYP45BwGaLIaQjph8yAJwwHWoOP+TTj5WYflkW6Uu8F9gC0ve6dPGPNEi2TUdirvAe4LYQKBgQD0UfAPm6tQg8pdkvfMBvYc21fk8zqmgcA4OtvDi60aXuv5jI5+faISvOG2JLuFhKIDOb5ZerzGvkN+LvWgzr9H7YdGZNNtwKgpS/MGqcuuHncTxWBAwYgKhf26a/tqFZRNurJ6GowxDiAcQEc1mWnmdngRa+dvvCwNbXvGVqfVEQKBgQDGKi447TqD76QfvRPn/fRSjM+QE1duk+XorEJ0HHIha5HV9kCrZdV/olGRjDLwPJO6JW7iE2FUsS9SsIrccFE/9P2ZUqfYP2wL5vNO5kAmoLLUl0gwqg1WnBTPJfXeKReTj2uGmOdEuuMPXpL/49hDuPViiE2Q4MGe2Z+oEYN/EwKBgHfQMuTEl2e9qaDn8OM6SrluC5V4fjunh6dLnfgwaCx1fk1702lOnQuJWzsiml9o4raoO6PP4AGqzphz2PsKSJ2ya1NnIJRDFXRjDYQoAn2Z7RViBsja36chfINObxXgDUFtHBdrK3LnFXIlR4aOfHOLh2grvWx7IDNZjIiAeH+xAoGAJlmFZnjqiRv4bDgAQTZRcSRVCvHjSsAOj0++8I+MutEBgSHN9B2aCsBT/tHeDcX7ZNvXsKLFhElh+iO2S+DkqHb2GRT47I2hkFAaqBtBMPiKgz/ftaNDP46nLEuRYHQdXu4zhfHTV+a/CHtqAWGLuddyjaYJNM96SQ6eqjzxcMcCgYAzdxOF2e27hIgo2ttjsROMGqW0/0r/HsKGKPnao7xHQNCAswTnBT+QGugPCe0NXjuxbySP7V1GeWMWF+WV5khtteWerT1/ELAC48NSDpaMxVa4GP8Q/0w6+ZyJty3UGbCYQzZZue81dU+42LUIaVJ4NAc2tYj3jD780udasawS6w==' + +Remember to copy the CA and client certificate/key manually to the client side +and commit before using under the openvpn interface configuration + +Refer this topic :ref:`configuration/pki/index:pki` for more options. + +Setting up OpenVPN +------------------ + +In this example we will use the most complicated case: a setup where each client +is a router that has its own subnet (think HQ and branch offices), since simpler +setups are subsets of it. + +Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and all +client subnets belong to 10.23.0.0/20. All clients need access to the +192.168.0.0/16 network. + +Server Configuration: + +.. code-block:: none + + set interfaces openvpn vtun10 encryption data-ciphers 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 local-host '172.18.201.10' + set interfaces openvpn vtun10 local-port '1194' + set interfaces openvpn vtun10 mode 'server' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 server client client1 ip '10.23.1.10' + set interfaces openvpn vtun10 server client client1 subnet '10.23.2.0/25' + set interfaces openvpn vtun10 server domain-name 'vyos.net' + set interfaces openvpn vtun10 server max-connections '250' + set interfaces openvpn vtun10 server name-server '172.16.254.30' + set interfaces openvpn vtun10 server subnet '10.23.1.0/24' + set interfaces openvpn vtun10 server topology 'subnet' + set interfaces openvpn vtun10 tls ca-cert ca-1 + set interfaces openvpn vtun10 tls certificate srv-1 + set interfaces openvpn vtun10 tls dh-params dh-1 + +The configurations above uses 1194/UDP default port, 256-bit AES for +encryption, SHA-512 for HMAC authentication and the persistent-tunnel option +which is recommended, as it prevents the TUN/TAP device from closing on connection resets or daemon reloads. +Remember, clients are identified using their CN attribute in the SSL certificate. + +To allow clients to access a specific network behind the router, we'll use the +push-route option to automatically install the appropriate route on each client. + +.. code-block:: none + + set interfaces openvpn vtun10 server push-route 192.168.0.0/16 + +OpenVPN will not automatically create routes in the kernel for client subnets +when they connect and will only use client-subnet association internally, so we +need to create a route to the 10.23.0.0/20 network ourselves: + +.. code-block:: none + + set protocols static route 10.23.0.0/20 interface vtun10 + +Client +------ + +VyOS can not only act as an OpenVPN site-to-site or server for multiple clients +but you can also configure any VyOS OpenVPN interface as an OpenVPN client that +connects to a VyOS OpenVPN server or any other OpenVPN server. + +Client Configuration: + +.. code-block:: none + + set interfaces openvpn vtun10 encryption data-ciphers 'aes256' + set interfaces openvpn vtun10 hash 'sha512' + set interfaces openvpn vtun10 mode 'client' + set interfaces openvpn vtun10 persistent-tunnel + 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 ca-1 + set interfaces openvpn vtun10 tls certificate client1 + +Output +------ + +Check the tunnel status: + +.. code-block:: none + + vyos@vyos:~$ show openvpn server + + OpenVPN status on vtun10 + + Client CN Remote Host Tunnel IP Local Host TX bytes RX bytes Connected Since + ----------- ------------------ ----------- ---------------- ---------- ---------- ------------------- + client1 172.110.12.54:33166 10.23.1.10 172.18.201.10:1194 3.4 KB 3.4 KB 2024-06-11 12:07:25 + + + +Server Bridge +============= + +In Ethernet bridging configurations, OpenVPN's server mode can be set as a +'bridge' where the VPN tunnel encapsulates entire Ethernet frames +(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup +allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below, +we outline a basic configuration to achieve this: + + +Server Side: + +.. code-block:: none + + set interfaces bridge br10 member interface eth1.10 + set interfaces bridge br10 member interface vtun10 + set interfaces openvpn vtun10 device-type 'tap' + set interfaces openvpn vtun10 encryption data-ciphers 'aes192' + set interfaces openvpn vtun10 hash 'sha256'' + set interfaces openvpn vtun10 local-host '172.18.201.10' + set interfaces openvpn vtun10 local-port '1194' + set interfaces openvpn vtun10 mode 'server' + set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' + set interfaces openvpn vtun10 server bridge start '10.10.0.100' + set interfaces openvpn vtun10 server bridge stop '10.10.0.200' + set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' + set interfaces openvpn vtun10 server topology 'subnet' + set interfaces openvpn vtun10 tls ca-certificate 'ca-1' + set interfaces openvpn vtun10 tls certificate 'srv-1' + set interfaces openvpn vtun10 tls dh-params 'srv-1' + +Client Side : + +.. code-block:: none + + set interfaces openvpn vtun10 device-type 'tap' + set interfaces openvpn vtun10 encryption data-ciphers 'aes192' + set interfaces openvpn vtun10 hash 'sha256'' + set interfaces openvpn vtun10 mode 'client' + 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-certificate 'ca-1' + set interfaces openvpn vtun10 tls certificate 'client-1' + + + +Server LDAP Authentication +========================== + +LDAP +---- + +Enterprise installations usually ship a kind of directory service which is used +to have a single password store for all employees. VyOS and OpenVPN support +using LDAP/AD as single user backend. + +Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is +shipped with every VyOS installation. A dedicated configuration file is +required. It is best practise to store it in ``/config`` to survive image +updates + +.. code-block:: none + + set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + +The required config file may look like this: + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://ldap.example.com + # Bind DN (If your LDAP server doesn't support anonymous binds) + BindDN cn=LDAPUser,dc=example,dc=com + # Bind Password password + Password S3cr3t + # Network timeout (in seconds) + Timeout 15 + </LDAP> + + <Authorization> + # Base DN + BaseDN "ou=people,dc=example,dc=com" + # User Search Filter + SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" + # Require Group Membership - allow all users + RequireGroup false + </Authorization> + +Active Directory +^^^^^^^^^^^^^^^^ + +Despite the fact that AD is a superset of LDAP + +.. code-block:: none + + <LDAP> + # LDAP server URL + URL ldap://dc01.example.com + # Bind DN (If your LDAP server doesn’t support anonymous binds) + BindDN CN=LDAPUser,DC=example,DC=com + # Bind Password + Password mysecretpassword + # Network timeout (in seconds) + Timeout 15 + # Enable Start TLS + TLSEnable no + # Follow LDAP Referrals (anonymously) + FollowReferrals no + </LDAP> + + <Authorization> + # Base DN + BaseDN "DC=example,DC=com" + # User Search Filter, user must be a member of the VPN AD group + SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" + # Require Group Membership + RequireGroup false # already handled by SearchFilter + <Group> + BaseDN "OU=Groups,DC=example,DC=com" + SearchFilter "(|(cn=VPN))" + MemberAttribute memberOf + </Group> + </Authorization> + +If you only want to check if the user account is enabled and can authenticate +(against the primary group) the following snipped is sufficient: + +.. code-block:: none + + <LDAP> + URL ldap://dc01.example.com + BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com + Password ThisIsTopSecret + Timeout 15 + TLSEnable no + FollowReferrals no + </LDAP> + + <Authorization> + BaseDN "DC=example,DC=com" + SearchFilter "sAMAccountName=%u" + RequireGroup false + </Authorization> + +A complete LDAP auth OpenVPN configuration could look like the following +example: + +.. code-block:: none + + vyos@vyos# show interfaces openvpn + openvpn vtun0 { + mode server + openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" + openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" + openvpn-option "--push redirect-gateway" + openvpn-option --duplicate-cn + openvpn-option "--verify-client-cert none" + openvpn-option --comp-lzo + openvpn-option --persist-key + openvpn-option --persist-tun + server { + domain-name example.com + max-connections 5 + name-server 203.0.113.0.10 + name-server 198.51.100.3 + subnet 172.18.100.128/29 + } + tls { + ca-certificate ca.crt + certificate server.crt + dh-params dh1024.pem + } + } + +For detailed example, refer this topic :doc:`OpenVPN with LDAP</configexamples/autotest/OpenVPN_with_LDAP/OpenVPN_with_LDAP>` + +Multi-factor Authentication +=========================== + +VyOS supports multi-factor authentication (MFA) or two-factor authentication +using Time-based One-Time Password (TOTP). Compatible with Google Authenticator +software token, other software tokens. + +Server side +----------- + +.. code-block:: none + + set interfaces openvpn vtun20 encryption cipher 'aes256' + set interfaces openvpn vtun20 hash 'sha512' + set interfaces openvpn vtun20 mode 'server' + set interfaces openvpn vtun20 persistent-tunnel + set interfaces openvpn vtun20 server client user1 + set interfaces openvpn vtun20 server mfa totp challenge 'disable' + set interfaces openvpn vtun20 server subnet '10.10.2.0/24' + set interfaces openvpn vtun20 server topology 'subnet' + set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' + set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' + set interfaces openvpn vtun20 tls dh-params 'dh-pem' + +For every client in the openvpn server configuration a totp secret is created. +To display the authentication information, use the command ``show interfaces openvpn vtun20 user user1 mfa qrcode`` + +An example: + +.. code-block:: none + + vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode + █████████████████████████████████████ + █████████████████████████████████████ + ████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ + ████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ + ████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ + ████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ + ████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ + ████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ + ████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ + ████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ + ████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ + ████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ + ████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ + ████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ + ████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ + ████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ + ████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ + █████████████████████████████████████ + █████████████████████████████████████ + +Use the QR code to add the user account in Google authenticator application and +on client side, use the OTP number as password. + +Authentication with Username/Password +===================================== + +OpenVPN server allows to securely obtain a username and password from a connecting +client, and to use that information as a basis for authenticating the client. + +First, configure the server to use an authentication plugin, which may be a +script. The OpenVPN server will call the plugin every time a client tries to +connect, passing it the username/password entered on the client + +In this exammple, the ``--auth-user-pass-verify`` directive is used with the +via-env method and a specified script path to validate the username and password provided by the client. + +Server +------ + +.. code-block:: none + + set interfaces openvpn vtun10 local-port '1194' + set interfaces openvpn vtun10 mode 'server' + set interfaces openvpn vtun10 openvpn-option '--auth-user-pass-verify /config/auth/check_user.sh via-env' + set interfaces openvpn vtun10 openvpn-option '--script-security 3' + set interfaces openvpn vtun10 persistent-tunnel + set interfaces openvpn vtun10 protocol 'udp' + set interfaces openvpn vtun10 server client client-1 ip '10.10.10.55' + set interfaces openvpn vtun10 server push-route 192.0.2.0/24 + set interfaces openvpn vtun10 server subnet '10.10.10.0/24' + set interfaces openvpn vtun10 server topology 'subnet' + set interfaces openvpn vtun10 tls ca-certificate 'ca-1' + set interfaces openvpn vtun10 tls certificate 'srv-1' + set interfaces openvpn vtun10 tls dh-params 'dh-1' + +Example of /config/auth/check_user.sh, includes two testing users: + +.. code-block:: none + + #!/bin/bash + USERNAME="$username" + PASSWORD="$password" + + # Replace this with real user checking logic or use getent + if [[ "$USERNAME" == "client1" && "$PASSWORD" == "pass123" ]]; then + exit 0 + elif [[ "$USERNAME" == "peter" && "$PASSWORD" == "qwerty" ]]; then + exit 0 + else + exit 1 + fi + +Client +------ + +One advantage of having the client certificate stored locally is the ability to create the client configuration. +Use this command: + +.. code-block:: none + + vyos@vyos:~$ generate openvpn client-config interface vtun10 ca ca-1 certificate client1 + +Save the output to a file, and add the ``auth-user-pass`` directive to the client +configuration. It will direct the OpenVPN client to query the user for a +username/password, passing it on to the server over the secure TLS channel. +You can use this file to import to any clients. + +.. code-block:: none + + client + dev tun + proto udp + remote 192.168.77.10 1194 + + remote-cert-tls server + proto udp + dev tun + dev-type tun + persist-key + persist-tun + verb 3 + auth-user-pass + + + <ca> + -----BEGIN CERTIFICATE----- + MIIDlzCCAn+gAwIBAgIUQW7AtPu0Qzp7VzT0TyYx83/ME8swDQYJKoZIhvcNAQEL + BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM + CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 + MTExMTIyMjJaFw0zMDA2MTAxMTIyMjJaMFQxCzAJBgNVBAYTAkdCMRMwEQYDVQQI + DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx + DTALBgNVBAMMBGNhLTEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDi + +v6i241T9ABxq1ngjWxDQITkqjV0nq2Jb3HSSuQpXRCu7DWdQZlbvnMHnkV/WTL0 + RNgkhS4iV/WYhE+bLihwiZ0GTeQnUd1QJSkusFROX46w6kKXYUR5IQtcBC+vdky8 + PESynPd+DXsJn5X9JTWqDeviUAQz/ZjDzWk+71MBCqa+Zps1zpIjK0ywn7pR/HnD + rxJOQXlBMNgvbv8U3IAZ2jJp0jTB8TnuDtWSA+XZejMm/EN/AWUQyliX6OJFSCIh + BL2BZ9lmVms4/HkRpbd50k3vvCoz+lAOEE6VsH0fEdLC3lZ+CtXZ7kjp2wdWWuSs + 5ggIJYZZkixsCisbtEmbAgMBAAGjYTBfMA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0P + AQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMCBggrBgEFBQcDATAdBgNVHQ4E + FgQUAG9lvr7AzJ/y4vY/XlWxXru+6m0wDQYJKoZIhvcNAQELBQADggEBAKsu4eZa + 8Fha9aKfuKqlGQHPpEFfVDaVJmebw0uMw+b5Y8EpBxzZrgbqbk3Mty8pBjNa9jkZ + zph04gHN4pR6kg3iQlUKGxZUfsB9ZUjKhkgNdUI9zq1323MKEvuIuYdt61DCfBHw + Y6Xax5Ge+BahR2bXdPaQH452/+xMTqkukkpLbioTeIDg6FCU2HYPY5emDF5DDZAZ + WXtTqi0zdT3Y6FqiTvs5VuWwXCcp+HM+Lwe1/VVJhwi4CHTq0CKWnQIH5blYjmyx + zRBlrlZm4ntWlL5Mtepa1A3DJirY4kw/SqMAAh/Q9lh41JzBc8epf+OdnOzK55Ym + tmctGO2o+NBCFi0= + -----END CERTIFICATE----- + + </ca> + + <cert> + -----BEGIN CERTIFICATE----- + MIIDrjCCApagAwIBAgIUN6vPxDEW89cfbEFPa0tZlnsW1GkwDQYJKoZIhvcNAQEL + BQAwVDELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcM + CVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzENMAsGA1UEAwwEY2EtMTAeFw0yNTA2 + MTExMTQ0MjlaFw0yNjA2MTExMTQ0MjlaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQI + DApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1Mx + EDAOBgNVBAMMB2NsaWVudDEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIB + AQCdOWq8vdO8CznGN83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmu + QBmeCj7SlbYtVYo1uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/ + RcZcW530pu/QpYinKTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585 + A7L40043VtsVVbPjQq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3 + UtRHiq74CfGtJzYtplgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6 + QjEL0RkYloMgkbv/2HLCu09hAgMBAAGjdTBzMAwGA1UdEwEB/wQCMAAwDgYDVR0P + AQH/BAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMB0GA1UdDgQWBBQCkfdfq3hv + 7UtqAxq/5VDRIdgJLTAfBgNVHSMEGDAWgBQAb2W+vsDMn/Li9j9eVbFeu77qbTAN + BgkqhkiG9w0BAQsFAAOCAQEAJ43+aDVRC+y2vsu6WRG2l6zYnLoIJZW4afdKMC1a + nhTWhj4AhAt8evhVbAxi/8qhQX3yXF2bUQKdS++8AVcvZFlSES32S5eBx83AwGLt + QkgvGx+QThKmoJwrelyuS2X0XX3P0WzohYI6HzSr6p9F8KhTvSW97E6SnldpdvEM + uG1C+61/Vys7WLmDBh1PZTGE03nRp3H4Q9ynyXEEf1MK3eZkzg5H3Evj66p82pD5 + 8IauRfghMHJf3tOC+y0YIoXshF3lPq4nYso5Jc/HGCHlsboCODMCnY3CZsH7/O1n + /MI710KpzZTCLnv4Qtx9JpZxR7FTddl36OOuYUXU3Gcnsg== + -----END CERTIFICATE----- + + </cert> + + <key> + -----BEGIN PRIVATE KEY----- + MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCdOWq8vdO8CznG + N83uAXCuN4PcdTJaRFEdJIEfqHjlcG0MZQuPIAlDbOU+IWmuQBmeCj7SlbYtVYo1 + uQOMUaIrAvxLIQUaL1Y60oLVTF5eAPrGV+NSTQR5uMApcH9/RcZcW530pu/QpYin + KTbGkEd54so6YRVPmYbIOPNUMbnZbccpinYi5t2dqubBb585A7L40043VtsVVbPj + Qq5V0HDursvqlaMqMRcffhR8H4B4ByU/EPRK4yTKm1hi19v3UtRHiq74CfGtJzYt + plgrLJBON7TsbIi/fEux4q1yhbKA0S66L6e5DZldRxNZOXG6QjEL0RkYloMgkbv/ + 2HLCu09hAgMBAAECggEAOR3xRVUO9Sr816JRSQwz486eNDpNSxazgwtOb3JUTUH9 + E7onq1y/kMOgOmSIEHoP9GaTcQxbbPe86IxomhLT/50ri52YzWzx/heY2SVPyQXB + FMo79putKw0vnj5UyydNiyLrbMQyrhFc5iFmWVdz5/c4cWHwjIThPp7V4znXYwHZ + OB/Xn1NNHDNy872oQn5wZWzuA4ml0OqjU5D+Ne9srODl3r4OTo3lb1N3JuH3aOSA + cACl1JnN/KElN8IotIdweeUFAdn2jsGjZnCpGaJvZQ+2iMn6doJXHgFiF5+GMF7o + aOatglElIuqgPtB/4nvnegSL0DSnB36ojqv2PAh24wKBgQDPBt4S4muqo8SqP2e0 + 8X78MyK3tz1VmgPKn3O68Vdi1V7FPz0RHRGsw/kdgxXsJlfZTWgzcq2NNFu0yPBJ + A/h7qo16mv8GW7cJCd2exjb+/oq4r5iWeqLdSsMUXN87x02LRaMNd9wz1mls1Z73 + oQ5hJ7zTtlyYXnvKPQo8X1ImjwKBgQDCaptQxZ/a3tcUQQlXAFMAScviODZd0LCL + 30ZalwpNs6nVVIPoZHD3tlzWN5Es74gndfkC7/Gm2cnsOW9QQaU56q+5LeNXItW8 + rc6yXq3vNQerqJxHNUmKWwLCQtSyLRjFqpGTl/PyX2bGXQ7/zjTL3W8VMD5otf4Y + SJJB+sKjDwKBgHSVX3WvAAamFtfwwMwKuwH3IfPnQqj0BHKUfK2nvxgvJCFbzV3X + yt5Jtf3ClhPYO9xpVOa0C7va4lHaXkYf8Exj7SxAIKFKALccUStaYBoU6bW7XOhQ + w2pu8ZCEBEo7oBVv77Rj7SNb+R6K5ex5TAm2QQXQSjCb9IYc/ail3TNNAoGBALu6 + GPMrgKnlFyV1j0E1DPBwUbDEuqpoArFtDRAYXFifLVTS4PQbWIG403f9++659Gy2 + G5ZcfqiwD6xL4VJLsPF1zewvhR/0gRJJehb+GVGrkRaOHykbKUGxk75kreDGbu8f + PqaXyXS17hWIch1Lzes0jDiXdwvA//QOzztqmVq9AoGAVMbmf04+QtzckLolAP4q + Uwr5svfy14A7V3IGkwlsHZdm37L26lfxW0kpOOE7g7D6gdinuALo6oopP7RN/IDq + PLaaHaGrIoLAEVFa0bRLGsrU2q87ytwfSgdra4jmsTn+xEabdI4IgmqWgwSRvGVf + KN18e19Ssw5x7Wq0Rsw/3VM= + -----END PRIVATE KEY----- + + </key> + +Login using the username and password, once prompted in the dialog. diff --git a/docs/configuration/interfaces/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index b320f59d..a13ebad1 100644 --- a/docs/configuration/interfaces/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -1,5 +1,3 @@ -:lastproofread: 2024-07-04 - .. _openvpn: ####### @@ -32,861 +30,417 @@ Disadvantages are: In the VyOS CLI, a key point often overlooked is that rather than being configured using the `set vpn` stanza, OpenVPN is configured as a network -interface using `set interfaces openvpn`. +`interface using `set interfaces openvpn`. + +************* +Configuration +************* -************ -Site-to-Site -************ +.. cfgcmd:: set interfaces openvpn <interface> authentication password <text> -.. figure:: /_static/images/openvpn_site2site_diagram.jpg + Provide a password for auth-user-pass authentication method (client-only option) -OpenVPN is popular for client-server setups, but its site-to-site mode -remains a relatively obscure feature, and many router appliances -still don't support it. However, it's very useful for quickly setting up -tunnels between routers. - -As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or -x.509 certificates. - -The pre-shared key mode is deprecated and will be removed from future OpenVPN -versions, so VyOS will have to remove support for that option as well. The -reason is that using pre-shared keys is significantly less secure than using TLS. - -We'll configure OpenVPN using self-signed certificates, and then discuss the -legacy pre-shared key mode. +.. cfgcmd:: set interfaces openvpn <interface> authentication username <text> -In both cases, we will use the following settings: - -* The public IP address of the local side of the VPN will be 198.51.100.10. -* The public IP address of the remote side of the VPN will be 203.0.113.11. -* The tunnel will use 10.255.1.1 for the local IP and 10.255.1.2 for the remote. -* The local site will have a subnet of 10.0.0.0/16. -* The remote site will have a subnet of 10.1.0.0/16. -* The official port for OpenVPN is 1194, which we reserve for client VPN; we - will use 1195 for site-to-site VPN. -* The ``persistent-tunnel`` directive will allow us to configure tunnel-related - attributes, such as firewall policy as we would on any normal network - interface. -* If known, the IP of the remote router can be configured using the - ``remote-host`` directive; if unknown, it can be omitted. We will assume a - dynamic IP for our remote router. - -Setting up certificates -======================= - -Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose -of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity, -compared to server setups that need to support multiple clients. - -However, since VyOS 1.4, it is possible to verify self-signed certificates using -certificate fingerprints. - -On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type. -You can generate them by executing command ``run generate pki certificate self-signed install <name>`` in the configuration mode. -Once the command is complete, it will add the certificate to the configuration session, to the ``pki`` subtree. -You can then review the proposed changes and commit them. - -.. code-block:: none - - vyos@vyos# run generate pki certificate self-signed install openvpn-local - Enter private key type: [rsa, dsa, ec] (Default: rsa) ec - Enter private key bits: (Default: 256) - Enter country code: (Default: GB) - Enter state: (Default: Some-State) - Enter locality: (Default: Some-City) - Enter organization name: (Default: VyOS) - Enter common name: (Default: vyos.io) - Do you want to configure Subject Alternative Names? [y/N] - Enter how many days certificate will be valid: (Default: 365) - Enter certificate type: (client, server) (Default: server) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - - vyos@vyos# compare - [pki] - + certificate openvpn-local { - + certificate "MIICJTCCAcugAwIBAgIUMXLfRNJ5iOjk/ uAZqUe4phW8MdgwCgYIKoZIzj0EAwIwVzELMAkGA1UEBhMCR0IxEzARBgNVBAgMClNvbWUtU3RhdGUxEjAQBgNVBAcMCVNvbWUtQ2l0eTENMAsGA1UECgwEVnlPUzEQMA4GA1UEAwwHdnlvcy5pbzAeFw0yMzA5MDcyMTQzMTNaFw0yNDA5MDYyMTQzMTNaMFcxCzAJBgNVBAYTAkdCMRMwEQYDVQQIDApTb21lLVN0YXRlMRIwEAYDVQQHDAlTb21lLUNpdHkxDTALBgNVBAoMBFZ5T1MxEDAOBgNVBAMMB3Z5b3MuaW8wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMWo3UwczAMBgNVHRMBAf8EAjAAMA4GA1UdDwEB/wQEAwIHgDATBgNVHSUEDDAKBggrBgEFBQcDATAdBgNVHQ4EFgQUBrAxRdFppdG/UBRdo7qNyHutaTQwHwYDVR0jBBgwFoAUBrAxRdFppdG/UBRdo7qNyHutaTQwCgYIKoZIzj0EAwIDSAAwRQIhAI2+8C92z9wTcTWkQ/goRxs10EBC+h78O+vgo9k97z5iAiBSeqfaVr5taQTS31+McGTAK3cYWNTg0DlOBI8aKO2oRg==" - + private { - + key "MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQgtOeEb0dMb5P/2Exi09WWvk6Cvz0oOBoDuP68ZimS2LShRANCAASp7D0vE3SKSAWAzr/lw9Eq9Q89r247AJR6ec/GT26AIcVA1bsongV1YaWvRwzTPC/yi5pkzV/PcT/WU7JQIyMW" - + } - + } + Provide a username for auth-user-pass authentication method (client-only option) - [edit] +.. cfgcmd:: set interfaces openvpn <interface> description <description> - vyos@vyos# commit + set description <text> for openvpn interface being configured -You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint. -OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command: +.. cfgcmd:: set interfaces openvpn <interface> device-type <tap | tun> + + * ``tun`` - devices encapsulate IPv4 or IPv6 (OSI Layer 3), default value + * ``tap`` - devices encapsulate Ethernet 802.3 (OSI Layer 2). -.. code-block:: none +.. cfgcmd:: set interfaces openvpn <interface> disable - vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 - 5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79 - -Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary. + Administratively disable interface -Repeat the procedure on the other router. +.. cfgcmd:: set interfaces openvpn <interface> encryption <cipher | data-ciphers> < 3des | aes128 | aes128gcm | none | ...> + + * ``cipher`` - Standard Data Encryption Algorithm + * ``data-ciphers`` - Cipher negotiation list for use in server or client mode -Setting up OpenVPN -================== +.. cfgcmd:: set interfaces openvpn <interface> hash <md5 | sha1 | sha256 | ...> -Local Configuration: + Configure a secure hash algorithm -.. code-block:: none +.. cmdinclude:: /_include/interface-ip.txt + :var0: openvpn + :var1: vtun0 - Configure the tunnel: +.. cmdinclude:: /_include/interface-ipv6.txt + :var0: openvpn + :var1: vtun0 - 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' # Public IP of the other side - set interfaces openvpn vtun1 local-port '1195' - set interfaces openvpn vtun1 remote-port '1195' - 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 - set interfaces openvpn vtun1 tls certificate 'openvpn-local' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <remote cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the remote router - set interfaces openvpn vtun1 tls role active +.. cfgcmd:: set interfaces openvpn <interface> keep-alive failure-count <value> -Remote Configuration: + Maximum number of keepalive packet failures. The default value is 60 -.. code-block:: none +.. cfgcmd:: set interfaces openvpn <interface> keep-alive interval <value> - 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 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 - set interfaces openvpn vtun1 tls certificate 'openvpn-remote' # The self-signed certificate - set interfaces openvpn vtun1 tls peer-fingerprint <local cert fingerprint> # The output of 'run show pki certificate <name> fingerprint sha256 on the local router - set interfaces openvpn vtun1 tls role active + Send keepalive packet every interval seconds. Default value is 10 -Pre-shared keys -=============== +.. cfgcmd:: set interfaces openvpn <interface> local-address <address> + + Define local IP address of tunnel (site-to-site mode only) -Until VyOS 1.4, the only option for site-to-site OpenVPN without PKI was to use -pre-shared keys. That option is still available but it is deprecated and will -be removed in the future. However, if you need to set up a tunnel to an older -VyOS version or a system with older OpenVPN, you need to still need to know how -to use it. +.. cfgcmd:: set interfaces openvpn <interface> local-host <address> -First, you need to generate a key by running ``run generate pki openvpn shared-secret install <name>`` from configuration mode. -You can use any name, we will use ``s2s``. + Local IP address to accept connections. If specified, OpenVPN will bind to + this address only. If unspecified, OpenVPN will bind to all interfaces. -.. code-block:: none +.. cfgcmd:: set interfaces openvpn <interface> local-port <port> - vyos@local# run generate pki openvpn shared-secret install s2s - 2 value(s) installed. Use "compare" to see the pending changes, and "commit" to apply. - [edit] - vyos@local# compare - [pki openvpn shared-secret] - + s2s { - + key "7c73046a9da91e874d31c7ad894a32688cda054bde157c64270f28eceebc0bb2f44dbb70335fad45148b0456aaa78cb34a34c0958eeed4f75e75fd99ff519ef940f7029a316c436d2366a2b0fb8ea1d1c792a65f67d10a461af83ef4530adc25d1c872de6d9c7d5f338223d1f3b66dc3311bbbddc0e05228c47b91c817c721aadc7ed18f0662df52ad14f898904372679e3d9697d062b0869d12de47ceb2e626fa12e1926a3119be37dd29c9b0ad81997230f4038926900d5edb78522d2940cfe207f8e2b948e0d459fa137ebb18064ac5982b28dd1899020b4f2b082a20d5d4eb65710fbb1e62b5e061df39620267eab429d3eedd9a1ae85957457c8e4655f3" - + version "1" - + } + Define local port number to accept connections - [edit] +.. cfgcmd:: set interfaces openvpn <interface> mirror egress <monitor-interface> - vyos@local# commit - [edit] + Configure port mirroring for interface outbound traffic and copy the traffic + to monitor-interface -Then you need to install the key on the remote router: +.. cfgcmd:: set interfaces openvpn <interface> mirror ingress <monitor-interface> -.. code-block:: none + Configure port mirroring for interface inbound traffic and copy the traffic + to monitor-interface - vyos@remote# set pki openvpn shared-secret s2s key <generated key string> +.. cfgcmd:: set interfaces openvpn <interface> mode <site-to-site | server | client> -Then you need to set the key in your OpenVPN interface settings: + Define a mode for OpenVPN operation -.. code-block:: none + * **site-to-site** - enables site-to-site VPN connection + * **client** - acts as client in server-client mode + * **server** - acts as server in server-client mode - set interfaces openvpn vtun1 shared-secret-key s2s +.. cfgcmd:: set interfaces openvpn <interface> offload dco -Firewall Exceptions -=================== + OpenVPN Data Channel Offload (DCO) enables significant performance enhancement + in encrypted OpenVPN data processing. By minimizing context switching for each + packet, DCO effectively reduces overhead. This optimization is achieved by + keeping most data handling tasks within the kernel, avoiding frequent switches + between kernel and user space for encryption and packet handling. -For the OpenVPN traffic to pass through the WAN interface, you must create a -firewall exception. + As a result, the processing of each packet becomes more efficient, + potentially leveraging hardware encryption offloading support available in + the kernel. -.. code-block:: none + .. note:: OpenVPN DCO is not a fully supported OpenVPN feature, and is currently + considered experimental. Furthermore, there are certain OpenVPN features and + use cases that remain incompatible with DCO. To get a comprehensive + understanding of the limitations associated with DCO, refer to the list of + known limitations in the documentation. - set firewall name OUTSIDE_LOCAL rule 10 action accept - set firewall name OUTSIDE_LOCAL rule 10 description 'Allow established/related' - set firewall name OUTSIDE_LOCAL rule 10 state established enable - set firewall name OUTSIDE_LOCAL rule 10 state related enable - set firewall name OUTSIDE_LOCAL rule 20 action accept - set firewall name OUTSIDE_LOCAL rule 20 description OpenVPN_IN - set firewall name OUTSIDE_LOCAL rule 20 destination port 1195 - set firewall name OUTSIDE_LOCAL rule 20 log enable - set firewall name OUTSIDE_LOCAL rule 20 protocol udp - set firewall name OUTSIDE_LOCAL rule 20 source + https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features -You should also ensure that the OUTISDE_LOCAL firewall group is applied to the -WAN interface and a direction (local). -.. code-block:: none + Enabling OpenVPN DCO + ==================== - set firewall interface eth0 local name 'OUTSIDE-LOCAL' + DCO support is a per-tunnel option and it is not automatically enabled by + default for new or upgraded tunnels. Existing tunnels will continue to function + as they have in the past. + DCO can be enabled for both new and existing tunnels. VyOS adds an option in + each tunnel configuration where we can enable this function. The current best + practice is to create a new tunnel with DCO to minimize the chance of problems + with existing clients. -Static Routing: + Example: -Static routes can be configured referencing the tunnel interface; for example, -the local router will use a network of 10.0.0.0/16, while the remote has a -network of 10.1.0.0/16: + .. code-block:: none -Local Configuration: + set interfaces openvpn vtun0 offload dco -.. code-block:: none + Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel + module. - set protocols static route 10.1.0.0/16 interface vtun1 + Disabled by default - no kernel module loaded. -Remote Configuration: + .. note:: Enable this feature causes an interface reset. + +.. cfgcmd:: set interfaces openvpn <interface> openvpn-option <text> + + OpenVPN has a lot of options, all of them are not included in VyOS CLI. + If an option is missing, a feature request may be opened at Phabricator_ so + all users can benefit from it (see :ref:`issues_features`). Alternatively, + use ``openvpn-option`` for passing raw OpenVPN options to openvpn.conf file. -.. code-block:: none + .. note:: Please use this only as last resort - things might break and OpenVPN + won’t start if you pass invalid options/syntax. Check system logs for errors. - set protocols static route 10.0.0.0/16 interface vtun1 + Example: -The configurations above will default to using 256-bit AES in GCM mode -for encryption (if both sides support data cipher negotiation) and SHA-1 for HMAC authentication. -SHA-1 is considered weak, but other hashing algorithms are available, as are -encryption algorithms: + .. code-block:: none -For Encryption: + set interfaces openvpn vtun0 openvpn-option 'persist-key' -This sets the cipher when NCP (Negotiable Crypto Parameters) is disabled or -OpenVPN version < 2.4.0. This option should not be used any longer in TLS -mode and still exists for compatibility with old configurations. + This will add ``persist-key`` to the generated OpenVPN configuration. This + option solves the problem by persisting keys across resets, so they + don't need to be re-read. -.. code-block:: none + .. code-block:: none - vyos@vyos# set interfaces openvpn vtun1 encryption cipher - Possible completions: - des DES algorithm - 3des DES algorithm with triple encryption - bf128 Blowfish algorithm with 128-bit key - bf256 Blowfish algorithm with 256-bit key - aes128 AES algorithm with 128-bit key CBC - aes128gcm AES algorithm with 128-bit key GCM - aes192 AES algorithm with 192-bit key CBC - aes192gcm AES algorithm with 192-bit key GCM - aes256 AES algorithm with 256-bit key CBC - aes256gcm AES algorithm with 256-bit key GCM + set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"' -This option was called --ncp-ciphers in OpenVPN 2.4 but has been renamed -to --data-ciphers in OpenVPN 2.5 to more accurately reflect its meaning. -The first cipher in that list that is also in the client's --data-ciphers list -is chosen. If no common cipher is found the client is rejected. + This will add ``route-up "/config/auth/tun_up.sh arg1"`` to the generated OpenVPN + config file. This option is executed after connection authentication, either + immediately after, or some number of seconds after as defined. The path and + arguments need to be single- or double-quoted. -.. code-block:: none + .. note:: Sometimes option lines in the generated OpenVPN configuration require + quotes. This is done through a hack on our config generator. You can pass + quotes using the ``"`` statement. - vyos@vyos# set int open vtun0 encryption data-ciphers - Possible completions: - none Disable encryption - 3des DES algorithm with triple encryption - aes128 AES algorithm with 128-bit key CBC - aes128gcm AES algorithm with 128-bit key GCM - aes192 AES algorithm with 192-bit key CBC - aes192gcm AES algorithm with 192-bit key GCM - aes256 AES algorithm with 256-bit key CBC - aes256gcm AES algorithm with 256-bit key GCM +.. cfgcmd:: set interfaces openvpn <interface> persistent-tunnel -For Hashing: + This option prevents the TUN/TAP device from closing or reopening on + connection resets or daemon reloads. -.. code-block:: none +.. cfgcmd:: set interfaces openvpn <interface> protocol <udp | tcp-passive | tcp-active > - vyos@vyos# set interfaces openvpn vtun1 hash - Possible completions: - md5 MD5 algorithm - sha1 SHA-1 algorithm - sha256 SHA-256 algorithm - sha512 SHA-512 algorithm + Define a protocol for OpenVPN communication with remote host -If you change the default encryption and hashing algorithms, be sure that the -local and remote ends have matching configurations, otherwise the tunnel will -not come up. + * **udp** - default protocol is udp when not defined + * **tcp-passive** - TCP protocol and accepts connections passively + * **tcp-active** - TCP protocol and initiates connections actively +.. cfgcmd:: set interfaces openvpn <interface> redirect <interface> -Firewall policy can also be applied to the tunnel interface for `local`, `in`, -and `out` directions and functions identically to ethernet interfaces. + This option redirects incoming packets to destination -If you're making use of multiple tunnels, OpenVPN must have a way to -distinguish between different tunnels aside from the pre-shared-key. This is -done either by referencing IP addresses or port numbers. One option is to -dedicate a public IP to each tunnel. Another option is to dedicate a port -number to each tunnel (e.g. 1195,1196,1197...). +.. cfgcmd:: set interfaces openvpn <interface> remote-address <address> -OpenVPN status can be verified using the `show openvpn` operational commands. -See the built-in help for a complete list of options. + Define remote IP address of tunnel (site-to-site mode only) -****** -Server -****** +.. cfgcmd:: set interfaces openvpn <interface> remote-host <address | host> -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 topic -:ref:`configuration/pki/index:pki` to generate a CA certificate, -a server certificate and key, a certificate revocation list, and a Diffie-Hellman -key exchange parameters file. You do not need client certificates and keys for -the server setup. + Define an IPv4/IPv6 address or hostname of server device if OpenVPN is being + run in client mode, and is undefined in server mode. -In this example we will use the most complicated case: a setup where each -client is a router that has its own subnet (think HQ and branch offices), since -simpler setups are subsets of it. +.. cfgcmd:: set interfaces openvpn <interface> remote-port <port> -Suppose you want to use 10.23.1.0/24 network for client tunnel endpoints and -all client subnets belong to 10.23.0.0/20. All clients need access to the -192.168.0.0/16 network. + Define a remote port number to connect to server -First we need to specify the basic settings. 1194/UDP is the default. The -``persistent-tunnel`` option is recommended, as it prevents the TUN/TAP device -from closing on connection resets or daemon reloads. +.. cfgcmd:: set interfaces openvpn <interface> replace-default-route -.. note:: Using **openvpn-option -reneg-sec** can be tricky. This option is - used to renegotiate data channel after n seconds. When used on both the - server and client, the lower value will trigger the renegotiation. If you - set it to 0 on one side of the connection (to disable it), the chosen value - on the other side will determine when the renegotiation will occur. + This option will make OpenVPN tunnel to be used as the default route -.. code-block:: none +.. cfgcmd:: set interfaces openvpn <interface> server bridge disable - set interfaces openvpn vtun10 mode server - set interfaces openvpn vtun10 local-port 1194 - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol udp + Disable the given instance. -Then we need to generate, add and specify the names of the cryptographic materials. -Each of the install commands should be applied to the configuration and commited -before using under the openvpn interface configuration. +.. cfgcmd:: set interfaces openvpn <interface> server bridge gateway <ipv4 address> -.. code-block:: none + Define a gateway ip address - 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' +.. cfgcmd:: set interfaces openvpn <interface> server bridge start <ipv4 address> - 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' + First IP address in the pool to allocate to connecting clients - 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' +.. cfgcmd:: set interfaces openvpn <interface> server bridge stop <ipv4 address> - set interfaces openvpn vtun10 tls ca-certificate ca-1 - set interfaces openvpn vtun10 tls certificate srv-1 - set interfaces openvpn vtun10 tls dh-params dh-1 + Last IP address in the pool to allocate to connecting clients -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 -a specific network behind our router, we will use a push-route option for -installing that route on clients. +.. cfgcmd:: set interfaces openvpn <interface> server bridge subnet-mask <ipv4 subnet mask> -.. code-block:: none + Define subnet mask pushed to dynamic clients. - set interfaces openvpn vtun10 server push-route 192.168.0.0/16 - set interfaces openvpn vtun10 server subnet 10.23.1.0/24 +.. cfgcmd:: set interfaces openvpn <interface> server client <name> -Since it's a HQ with branch offices setup, we will want all clients to have -fixed addresses and we will route traffic to specific subnets through them. We -need configuration for each client to achieve this. + Define the common name specified in client certificate -.. note:: Clients are identified by the CN field of their x.509 certificates, - in this example the CN is ``client0``: +.. cfgcmd:: set interfaces openvpn <interface> server client <name> disable -.. code-block:: none + Disable the client connection - set interfaces openvpn vtun10 server client client0 ip 10.23.1.10 - set interfaces openvpn vtun10 server client client0 subnet 10.23.2.0/25 +.. cfgcmd:: set interfaces openvpn <interface> server client <name> ip <address> -OpenVPN **will not** automatically create routes in the kernel for client -subnets when they connect and will only use client-subnet association -internally, so we need to create a route to the 10.23.0.0/20 network ourselves: + Set a specific IPv4/IPv6 address to the client -.. code-block:: none - - set protocols static route 10.23.0.0/20 interface vtun10 - -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 manually from the CLI. -Client key and cert files should be signed with the proper ca cert and generated -on the server side. - -HQ's router requires the following steps to generate crypto materials for the Branch 1: - -.. code-block:: none - - 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 - - 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 - -Client Authentication -===================== - -LDAP ----- - -Enterprise installations usually ship a kind of directory service which is used -to have a single password store for all employees. VyOS and OpenVPN support -using LDAP/AD as single user backend. - -Authentication is done by using the ``openvpn-auth-ldap.so`` plugin which is -shipped with every VyOS installation. A dedicated configuration file is -required. It is best practise to store it in ``/config`` to survive image -updates - -.. code-block:: none - - set interfaces openvpn vtun0 openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - -The required config file may look like this: - -.. code-block:: none - - <LDAP> - # LDAP server URL - URL ldap://ldap.example.com - # Bind DN (If your LDAP server doesn't support anonymous binds) - BindDN cn=LDAPUser,dc=example,dc=com - # Bind Password password - Password S3cr3t - # Network timeout (in seconds) - Timeout 15 - </LDAP> - - <Authorization> - # Base DN - BaseDN "ou=people,dc=example,dc=com" - # User Search Filter - SearchFilter "(&(uid=%u)(objectClass=shadowAccount))" - # Require Group Membership - allow all users - RequireGroup false - </Authorization> - -Active Directory -^^^^^^^^^^^^^^^^ - -Despite the fact that AD is a superset of LDAP - -.. code-block:: none - - <LDAP> - # LDAP server URL - URL ldap://dc01.example.com - # Bind DN (If your LDAP server doesn’t support anonymous binds) - BindDN CN=LDAPUser,DC=example,DC=com - # Bind Password - Password mysecretpassword - # Network timeout (in seconds) - Timeout 15 - # Enable Start TLS - TLSEnable no - # Follow LDAP Referrals (anonymously) - FollowReferrals no - </LDAP> - - <Authorization> - # Base DN - BaseDN "DC=example,DC=com" - # User Search Filter, user must be a member of the VPN AD group - SearchFilter "(&(sAMAccountName=%u)(memberOf=CN=VPN,OU=Groups,DC=example,DC=com))" - # Require Group Membership - RequireGroup false # already handled by SearchFilter - <Group> - BaseDN "OU=Groups,DC=example,DC=com" - SearchFilter "(|(cn=VPN))" - MemberAttribute memberOf - </Group> - </Authorization> - -If you only want to check if the user account is enabled and can authenticate -(against the primary group) the following snipped is sufficient: - -.. code-block:: none - - <LDAP> - URL ldap://dc01.example.com - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,DC=example,DC=com - Password ThisIsTopSecret - Timeout 15 - TLSEnable no - FollowReferrals no - </LDAP> - - <Authorization> - BaseDN "DC=example,DC=com" - SearchFilter "sAMAccountName=%u" - RequireGroup false - </Authorization> - -A complete LDAP auth OpenVPN configuration could look like the following -example: - -.. code-block:: none - - vyos@vyos# show interfaces openvpn - openvpn vtun0 { - mode server - openvpn-option "--tun-mtu 1500 --fragment 1300 --mssfix" - openvpn-option "--plugin /usr/lib/openvpn/openvpn-auth-ldap.so /config/auth/ldap-auth.config" - openvpn-option "--push redirect-gateway" - openvpn-option --duplicate-cn - openvpn-option "--verify-client-cert none" - openvpn-option --comp-lzo - openvpn-option --persist-key - openvpn-option --persist-tun - server { - domain-name example.com - max-connections 5 - name-server 203.0.113.0.10 - name-server 198.51.100.3 - subnet 172.18.100.128/29 - } - tls { - ca-certificate ca.crt - certificate server.crt - dh-params dh1024.pem - } - } - - -****** -Client -****** - -VyOS can not only act as an OpenVPN site-to-site or server for multiple clients -but you can also configure any VyOS OpenVPN interface as an OpenVPN client that -connects to a VyOS OpenVPN server or any other OpenVPN server. - -Given the following example we have one VyOS router acting as an OpenVPN server -and another VyOS router acting as an OpenVPN client. The server also pushes a -static client IP address to the OpenVPN client. Remember, clients are identified -using their CN attribute in the SSL certificate. - -.. _openvpn:client_server: +.. cfgcmd:: set interfaces openvpn <interface> server client <name> push-route <subnet> -Configuration -============= - -Server Side ------------ - -.. code-block:: none - - set interfaces openvpn vtun10 encryption data-ciphers 'aes256' - set interfaces openvpn vtun10 hash 'sha512' - set interfaces openvpn vtun10 local-host '172.18.201.10' - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 persistent-tunnel - set interfaces openvpn vtun10 protocol 'udp' - set interfaces openvpn vtun10 server client client1 ip '10.10.0.10' - set interfaces openvpn vtun10 server domain-name 'vyos.net' - set interfaces openvpn vtun10 server max-connections '250' - 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 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: - -Client Side ------------ - -.. code-block:: none - - set interfaces openvpn vtun10 encryption data-ciphers 'aes256' - set interfaces openvpn vtun10 hash 'sha512' - set interfaces openvpn vtun10 mode 'client' - set interfaces openvpn vtun10 persistent-tunnel - 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 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 - -.. note:: Compression is generally not recommended. VPN tunnels which use - compression are susceptible to the VORALCE attack vector. Enable compression - if needed. - -Options -======= - -We do not have CLI nodes for every single OpenVPN option. If an option is -missing, a feature request should be opened at Phabricator_ so all users can -benefit from it (see :ref:`issues_features`). - -If you are a hacker or want to try on your own we support passing raw OpenVPN -options to OpenVPN. - -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option 'persist-key' - -Will add ``persist-key`` to the generated OpenVPN configuration. -Please use this only as last resort - things might break and OpenVPN won't start -if you pass invalid options/syntax. - -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option - 'push keepalive 10 60' - -Will add ``push "keepalive 1 10"`` to the generated OpenVPN config file. - -.. cfgcmd:: set interfaces openvpn vtun10 openvpn-option - 'route-up "/config/auth/tun_up.sh arg1"' - -Will add ``route-up "/config/auth/tun_up.sh arg1"`` to the generated OpenVPN -config file. The path and arguments need to be single- or double-quoted. - -.. note:: Sometimes option lines in the generated OpenVPN configuration require - quotes. This is done through a hack on our config generator. You can pass - quotes using the ``"`` statement. - -Server bridge -============= - -In Ethernet bridging configurations, OpenVPN's server mode can be set as a -'bridge' where the VPN tunnel encapsulates entire Ethernet frames -(up to 1514 bytes) instead of just IP packets (up to 1500 bytes). This setup -allows clients to transmit Layer 2 frames through the OpenVPN tunnel. Below, -we outline a basic configuration to achieve this: - - -Server Side: - -.. code-block:: none - - set interfaces bridge br10 member interface eth1.10 - set interfaces bridge br10 member interface vtun10 - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256'' - set interfaces openvpn vtun10 local-host '172.18.201.10' - set interfaces openvpn vtun10 local-port '1194' - set interfaces openvpn vtun10 mode 'server' - set interfaces openvpn vtun10 server bridge gateway '10.10.0.1' - set interfaces openvpn vtun10 server bridge start '10.10.0.100' - set interfaces openvpn vtun10 server bridge stop '10.10.0.200' - set interfaces openvpn vtun10 server bridge subnet-mask '255.255.255.0' - set interfaces openvpn vtun10 server topology 'subnet' - set interfaces openvpn vtun10 tls ca-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'srv-1' - set interfaces openvpn vtun10 tls dh-params 'srv-1' - -Client Side : - -.. code-block:: none - - set interfaces openvpn vtun10 device-type 'tap' - set interfaces openvpn vtun10 encryption data-ciphers 'aes192' - set interfaces openvpn vtun10 hash 'sha256'' - set interfaces openvpn vtun10 mode 'client' - 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-certificate 'ca-1' - set interfaces openvpn vtun10 tls certificate 'client-1' + Define a route to be pushed to a specific client + +.. cfgcmd:: set interfaces openvpn <interface> server client <name> subnet <subnet> + + Define this option to route a fixed subnet from the server to a particular + client. Used as OpenVPN iroute directive. + +.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool start <address> + + Define a first IP address from IPv4 pool of subnet to be dynamically + allocated to connecting clients + +.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool stop <address> + + Define a last IP address from IPv4 pool of subnet to be dynamically allocated + to connecting clients + +.. cfgcmd:: set interfaces openvpn <interface> server client-ip-pool subnet <netmask> + + Define a subnet mask pushed to dynamic clients. This option is only used for + device type tap, not to be used with bridged interfaces. + +.. cfgcmd:: set interfaces openvpn <interface> server client-ipv6-pool base <ipv6addr/bits> + + Define an IPv6 address pool for dynamic assignment to clients + +.. cfgcmd:: set interfaces openvpn <interface> server domain-name <name> + + DNS suffix to be pushed to all clients -*************************** -Multi-factor Authentication -*************************** - -VyOS supports multi-factor authentication (MFA) or two-factor authentication -using Time-based One-Time Password (TOTP). Compatible with Google Authenticator -software token, other software tokens. - -MFA TOTP options -================ +.. cfgcmd:: set interfaces openvpn <interface> server max-connections <1-4096> + + Define the maximum number of client connections .. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable> - If set to enable, openvpn-otp will expect password as result of challenge/ - response protocol. + If set to enable, openvpn-otp will expect password as result of challenge/ + response protocol. + +.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535> -.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535> + Configure number of digits to use for totp hash (default: 6) - Configure number of digits to use for totp hash (default: 6) - .. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535> - Configure time drift in seconds (default: 0) + Configure time drift in seconds (default: 0) .. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535> - Configure maximum allowed clock slop in seconds (default: 180) + Configure maximum allowed clock slop in seconds (default: 180) .. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535> - Configure step value for totp in seconds (default: 30) + Configure step value for totp in seconds (default: 30) -Example -======= +.. cfgcmd:: set interfaces openvpn <interface> server name-server <address> -.. code-block:: none + Define Client DNS configuration to be used with the connection - set interfaces openvpn vtun20 encryption cipher 'aes256' - set interfaces openvpn vtun20 hash 'sha512' - set interfaces openvpn vtun20 mode 'server' - set interfaces openvpn vtun20 persistent-tunnel - set interfaces openvpn vtun20 server client user1 - set interfaces openvpn vtun20 server mfa totp challenge 'disable' - set interfaces openvpn vtun20 server subnet '10.10.2.0/24' - set interfaces openvpn vtun20 server topology 'subnet' - set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20' - set interfaces openvpn vtun20 tls dh-params 'dh-pem' +.. cfgcmd:: set interfaces openvpn <interface> server push-route <subnet> -For every client in the openvpn server configuration a totp secret is created. -To display the authentication information, use the command: + Define a route to be pushed to all clients -.. cfgcmd:: show interfaces openvpn <interface> user <username> mfa <qrcode|secret|uri> +.. cfgcmd:: set interfaces openvpn <interface> server reject-unconfigured-client -An example: + Reject connections from clients that are not explicitly configured -.. code-block:: none +.. cfgcmd:: set interfaces openvpn <interface> server subnet <subnet> - vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode - █████████████████████████████████████ - █████████████████████████████████████ - ████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████ - ████ █ █ █▀▀▄ █▀▀▀█▀██ █ █ █ ████ - ████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████ - ████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████ - ████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████ - ████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████ - ████ ▄█▀▀▄▄ ▄█▀ ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████ - ████▄█ ▀▄▄▄▀ ▀ ▄█ ▄ █▄█▀ █▀ █▀█████ - ████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀ ▀ ▀ ▄█▀████ - ████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█ █▀██▀████ - ████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████ - ████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀ █▄█ ██▀█████ - ████ █ █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄ ████ - ████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████ - ████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████ - █████████████████████████████████████ - █████████████████████████████████████ + Manadatory field to define in server mode, set ipv4 or ipv6 network -Use the QR code to add the user account in Google authenticator application and -on client side, use the OTP number as password. +.. cfgcmd:: set interfaces openvpn <interface> server topology < net30 | point-to-point | subnet> + Define virtual addressing topology when running in ``tun`` mode. This directive + has no meaning in ``tap`` mode, which always uses a subnet topology. -********************************** -OpenVPN Data Channel Offload (DCO) -********************************** + * **subnet** - This topology is the current recommended and default topology. + This mode allocates a single IP address per connecting client. + * **net30** - This is the old topology for support with Windows clients, by + allocating one /30 subnet per client. It is effictively depcrecated. + * **point-to-point** - Use a point-to-point topology where the remote endpoint + of the client's tun interface always points to the local endpoint of the + server's tun interface. This mode allocates a single IP address per connecting + client. Only use when none of the connecting clients are Windows systems. -OpenVPN Data Channel Offload (DCO) enables significant performance enhancement -in encrypted OpenVPN data processing. By minimizing context switching for each -packet, DCO effectively reduces overhead. This optimization is achieved by -keeping most data handling tasks within the kernel, avoiding frequent switches -between kernel and user space for encryption and packet handling. -As a result, the processing of each packet becomes more efficient, potentially -leveraging hardware encryption offloading support available in the kernel. +.. cfgcmd:: set interfaces openvpn <interface> shared-secret-key <key> -.. note:: OpenVPN DCO is not a fully supported OpenVPN feature, and is currently - considered experimental. Furthermore, there are certain OpenVPN features and - use cases that remain incompatible with DCO. To get a comprehensive - understanding of the limitations associated with DCO, refer to the list of - known limitations in the documentation. + Define a static secret key, used with site-to-site OpenVPN option only - https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features +.. cfgcmd:: set interfaces openvpn <interface> tls auth-key <key> + Define a tls secret key for tls-auth which adds an additional HMAC signature + to all SSL/TLS handshake packets for integrity verification. Use ``run generate pki openvpn shared-secret install <name>`` to generate the key. -Enabling OpenVPN DCO -==================== +.. cfgcmd:: set interfaces openvpn <interface> tls ca-certificate <name> -DCO support is a per-tunnel option and it is not automatically enabled by -default for new or upgraded tunnels. Existing tunnels will continue to function -as they have in the past. + Define Certificate Authority chain in PKI configuration -DCO can be enabled for both new and existing tunnels. VyOS adds an option in -each tunnel configuration where we can enable this function. The current best -practice is to create a new tunnel with DCO to minimize the chance of problems -with existing clients. +.. cfgcmd:: set interfaces openvpn <interface> tls certificate <name> -.. cfgcmd:: set interfaces openvpn <name> offload dco + Define a name of certificate in PKI configuration - Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel - module. +.. cfgcmd:: set interfaces openvpn <interface> tls crypt-key - Disabled by default - no kernel module loaded. + Define a shared secret key to provide an additional level of security, + a variant similar to tls-auth - .. note:: Enable this feature causes an interface reset. +.. cfgcmd:: set interfaces openvpn <interface> tls dh-params + Define Diffie Hellman parameters, required only on server mode -Troubleshooting -=============== +.. cfgcmd:: set interfaces openvpn <interface> tls peer-fingerprint <text> -VyOS provides some operational commands on OpenVPN. + Peer certificate SHA256 fingerprint, configured in site-to-site mode -Check status ------------- +.. cfgcmd:: set interfaces openvpn <interface> tls role <active | passive> -The following commands let you check tunnel status. + Define a role for TLS negotiation, preferably used in site-to-site mode -.. opcmd:: show openvpn client + * **active** - Initiate TLS negotiation actively + * **passive** - Wait for incoming TLS connection - Use this command to check the tunnel status for OpenVPN client interfaces. +.. cfgcmd:: set interfaces openvpn <interface> tls tls-version-min <1.0 | 1.1 | 1.2 | 1.4 > -.. opcmd:: show openvpn server + This option sets the minimum TLS version which will accept from the peer + +.. cfgcmd:: set interfaces openvpn <interface> use-lzo-compression + + Use fast LZO compression on this TUN/TAP interface + +.. cfgcmd:: set interfaces openvpn <interface> vrf <name> + + Place interface in given VRF instance. - Use this command to check the tunnel status for OpenVPN server interfaces. +************** +Operation Mode +************** .. opcmd:: show openvpn site-to-site - Use this command to check the tunnel status for OpenVPN site-to-site - interfaces. + Show tunnel status for OpenVPN site-to-site interfaces -OpenVPN Logs ------------- +.. opcmd:: show openvpn server -.. opcmd:: show log openvpn + Shows tunnel status for Openvpn server interfaces - Use this command to check log messages which include entries for successful - connections as well as failures and errors related to all OpenVPN interfaces. +.. opcmd:: show openvpn client -.. opcmd:: show log openvpn interface <name> + Shows tunnel status for OpenVPN client interfaces - Use this command to check log messages specific to an interface. +.. opcmd:: show log openvpn + Show logs for all OpenVPN interfaces -Reset OpenVPN -------------- +.. opcmd:: show log openvpn interface <interface> -The following commands let you reset OpenVPN. + Show logs for specific OpenVPN interface .. opcmd:: reset openvpn client <text> - Use this command to reset the specified OpenVPN client. + Reset specified OpenVPN client .. opcmd:: reset openvpn interface <interface> - Use this command to reset the OpenVPN process on a specific interface. + Reset OpenVPN process on specified interface + +.. opcmd:: generate openvpn client-config interface <interface> ca <name> certificate <name> + + Generate OpenVPN client configuration file in ovpn format to load in client machines + +******** +Examples +******** + +This section covers examples of OpenVPN configurations for various deployments. +.. toctree:: + :maxdepth: 1 + :includehidden: + openvpn-examples .. include:: /_include/common-references.txt diff --git a/docs/configuration/interfaces/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index db2ff2c7..b4e4d8db 100644 --- a/docs/configuration/interfaces/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst @@ -220,14 +220,15 @@ firewall exception. set firewall ipv4 name OUTSIDE_LOCAL rule 20 destination port 51820 set firewall ipv4 name OUTSIDE_LOCAL rule 20 log enable set firewall ipv4 name OUTSIDE_LOCAL rule 20 protocol udp - set firewall ipv4 name OUTSIDE_LOCAL rule 20 source You should also ensure that the OUTSIDE_LOCAL firewall group is applied to the -WAN interface and a direction (local). +WAN interface and in an input (local) direction. .. code-block:: none - set interfaces ethernet eth0 firewall local name 'OUTSIDE-LOCAL' + set firewall ipv4 input filter rule 10 action jump + set firewall ipv4 input filter rule 10 jump-target 'OUTSIDE_LOCAL' + set firewall ipv4 input filter rule 10 inbound-interface name 'eth0' Assure that your firewall rules allow the traffic, in which case you have a working VPN using WireGuard. diff --git a/docs/configuration/policy/route.rst b/docs/configuration/policy/route.rst index b818d238..1ddd04cf 100644 --- a/docs/configuration/policy/route.rst +++ b/docs/configuration/policy/route.rst @@ -51,6 +51,20 @@ in this section. Set match criteria based on connection mark. +.. cfgcmd:: set policy route <name> rule <n> mark <match_criteria> +.. cfgcmd:: set policy route6 <name> rule <n> mark <match_criteria> + + Match based on the firewall mark (fwmark), where <match_criteria> can be: + + * <0-2147483647> a single fwmark + * !<0-2147483647> everything except a single fwmark + * <start-end> a range of marks + * !<start-end> everything except the range of marks + + .. note:: When using the ``set table`` or ``set vrf`` commands the mark + settings are ignored and overwritten with a table-specific mark that + is set to 0x7FFFFFFF - the id of the table/VRF. + .. cfgcmd:: set policy route <name> rule <n> source address <match_criteria> .. cfgcmd:: set policy route <name> rule <n> destination address @@ -273,7 +287,20 @@ setting a different routing table. Set the routing table to forward packet with. + .. note:: When using the ``set table`` or ``set vrf`` commands matching + against the mark is not possible, because it gets overwritten with a + table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. + .. cfgcmd:: set policy route <name> rule <n> set tcp-mss <500-1460> .. cfgcmd:: set policy route6 <name> rule <n> set tcp-mss <500-1460> Set packet modifications: Explicitly set TCP Maximum segment size value. + +.. cfgcmd:: set policy route <name> rule <n> set vrf <default | text > +.. cfgcmd:: set policy route6 <name> rule <n> set vrf <default | text > + + Set the VRF to forward packet with. + + .. note:: When using the ``set table`` or ``set vrf`` commands matching + against the mark is not possible, because it gets overwritten with a + table-specific mark that is 0x7FFFFFFF - the id of the table/VRF. diff --git a/docs/configuration/protocols/bgp.rst b/docs/configuration/protocols/bgp.rst index 3c983aae..71ba533b 100644 --- a/docs/configuration/protocols/bgp.rst +++ b/docs/configuration/protocols/bgp.rst @@ -627,6 +627,12 @@ Common parameters Disable immediate session reset if peer's connected link goes down. +.. cfgcmd:: set protocols bgp parameters no-ipv6-auto-ra + + By default, FRR sends router advertisement packets when Extended Next Hop is + on or when a connection is established directly using the device name (Unnumbered BGP). + Setting this option prevents FRR from sending router advertisement packets, but could break Unnumbered BGP. + .. cfgcmd:: set protocols bgp listen range <prefix> peer-group <name> This command is useful if one desires to loosen the requirement for BGP diff --git a/docs/configuration/protocols/failover.rst b/docs/configuration/protocols/failover.rst index 8088e104..651fc5c3 100644 --- a/docs/configuration/protocols/failover.rst +++ b/docs/configuration/protocols/failover.rst @@ -3,7 +3,7 @@ Failover ######## Failover routes are manually configured routes, but they only install -to the routing table if the health-check target is alive. +to the routing table as kernel routes if the health-check target is alive. If the target is not alive the route is removed from the routing table until the target becomes available. @@ -28,7 +28,12 @@ Failover Routes .. cfgcmd:: set protocols failover route <subnet> next-hop <address> check type <protocol> - Defines protocols for checking ARP, ICMP, TCP + Defines protocols for checking ARP, ICMP, TCP. +* ICMP probe sends 2 ICMP request packets with a response timeout of 1 second. + If one ICMP response is received, the health check is successful. +* ARP probe sends 2 ARP requests with a response timeout of 1 second. + If one response is received, the health check is successful. +* TCP probe checks whether the destination port is open. Default is ``icmp``. diff --git a/docs/configuration/service/dhcp-server.rst b/docs/configuration/service/dhcp-server.rst index eaa6a9f2..00ba179a 100644 --- a/docs/configuration/service/dhcp-server.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -49,15 +49,15 @@ Configuration Inform client that the DNS server can be found at `<address>`. This is the configuration parameter for the entire shared network definition. - All subnets will inherit this configuration item if not specified locally. + All subnets will inherit this configuration item if not specified locally. Multiple DNS servers can be defined. -.. cfgcmd:: set service dhcp-server shared-network-name <name> option +.. cfgcmd:: set service dhcp-server shared-network-name <name> option vendor-option <option-name> - This configuration parameter lets you specify a vendor-option for the - entire shared network definition. All subnets will inherit this - configuration item if not specified locally. An example for Ubiquiti is + This configuration parameter lets you specify a vendor-option for the + entire shared network definition. All subnets will inherit this + configuration item if not specified locally. An example for Ubiquiti is shown below: **Example:** @@ -66,14 +66,14 @@ Pass address of Unifi controller at ``172.16.100.1`` to all clients of ``NET1`` .. code-block:: none - set service dhcp-server shared-network-name 'NET1' option vendor-option + set service dhcp-server shared-network-name 'NET1' option vendor-option ubiquiti '172.16.100.1' .. cfgcmd:: set service dhcp-server listen-address <address> - This configuration parameter lets the DHCP server to listen for DHCP - requests sent to the specified address, it is only realistically useful for - a server whose only clients are reached via unicasts, such as via DHCP relay + This configuration parameter lets the DHCP server to listen for DHCP + requests sent to the specified address, it is only realistically useful for + a server whose only clients are reached via unicasts, such as via DHCP relay agents. Individual Client Subnet @@ -148,24 +148,205 @@ Individual Client Subnet request where no full FQDN is passed. This option can be given multiple times if you need multiple search domains (DHCP Option 119). -.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> +.. cfgcmd:: set service dhcp-server shared-network-name <name> subnet <subnet> option vendor-option <option-name> This configuration parameter lets you specify a vendor-option for the - subnet specified within the shared network definition. An example for + subnet specified within the shared network definition. An example for Ubiquiti is shown below: **Example:** -Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of +Create ``172.18.201.0/24`` as a subnet within ``NET1`` and pass address of Unifi controller at ``172.16.100.1`` to clients of that subnet. .. code-block:: none - set service dhcp-server shared-network-name 'NET1' subnet + set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' option vendor-option ubiquiti '172.16.100.1' +Dynamic DNS Update (RFC 2136) +----------------------------- + +VyOS DHCP service supports RFC-2136 DDNS protocol. Based on DHCP lease change +events, DHCP server generates DDNS update requests (defines as NameChangeRequests +or NCRs) and posts them to a compliant DNS server, that will update its name +database accordingly. + +VyOS built-in DNS Forwarder does not support DDNS, you will need an external DNS +server with RFC-2136 DDNS support. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update + + Enables DDNS globally. + +**Behavioral settings** + +These settings can be configured on the global level and overridden on the scope +level, i.e. for individual shared networks or subnets. See examples below. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update send-updates [ enable + | disable ] + + If set to ``enable`` on global level, updates for all scopes will be enabled, + except if explicitly set to ``disable`` on the scope level. If set to ``disable``, + updates will only be sent for scopes, where ``send-updates`` is explicity + set to ``enable``. + + This model is followed for a few behavioral settings below: if the option is + not set, the setting is inherited from the parent scope. You can override the + parent scope setting by setting the option explicitly. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-no-update [ enable + | disable ] + + VyOS will ignore client request not to update DNS records and send DDNS + update requests regardless. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update override-client-update [ enable + | disable ] + + VyOS will override client DDNS request settings and always update both + forward and reverse DNS records. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update update-on-renew [ enable + | disable ] + + Issue DDNS update requests on DHCP lease renew. In busy networks this may + generate a lot of traffic. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update conflict-resolution [ enable + | disable ] + + Use RFC-4703 conflict resolution. This algorithm helps in situation when + multiple clients reserve same IP addresses or advertise identical hostnames. + Should be used in most situations. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update replace-client-name [ never + | always | when-present | when-not-present ] + + * **never**: use the name sent by the client. If the client didn't provide any, + do not generate one. This is the default behavior + + * **always**: always generate a name for the client + + * **when-present**: replace the name the client sent with a generated one, if + the client didn't send any, do not generate one + + * **when-not-present**: use the name sent by the client. If the client didn't + send any, generate one for the client + + The names are generated using ``generated-prefix``, ``qualifying-suffix`` and the + client's IP address string. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update generated-prefix <prefix> + + Prefix used in client name generation. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update qualifying-suffix <suffix> + + DNS suffix used in client name generation. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update ttl-percent <0-100> + + TTL of the DNS record as a percentage of the DHCP lease time. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-set + <character string> + + Characters, that are considered invalid in the client name. They will be replaced + with ``hostname-char-replacement`` string. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update hostname-char-replacement + <character string> + + Replacement string for the invalid characters defined by ``hostname-char-set``. + +**TSIG keys definition** + +This is the global list of TSIG keys for DDNS updates. They need to be specified by +the name in the DNS domain definitions. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> + algorithm <algorithm> + + Sets the algorithm for the TSIG key. Supported algorithms are ``hmac-md5``, + ``hmac-sha1``, ``hmac-sha224``, ``hmac-sha256``, ``hmac-sha384``, ``hmac-sha512`` + +.. cfgcmd:: set service dhcp-server dynamic-dns-update tsig-key <key-name> + secret <key-secret> + + base64-encoded TSIG key secret value + +**DNS domains definition** + +This is global configuration of DNS servers for the updatable forward and reverse +DNS domains. For every domain multiple DNS servers can be specified. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> key-name <tsig-key-name> + + TSIG key used for the domain. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> dns-server <number> address <ip-address> + + IP address of the DNS server. + +.. cfgcmd:: set service dhcp-server dynamic-dns-update [forward|reverse]-domain + <domain-name> dns-server <number> port <port> + + UDP port of the DNS server. ``53`` is the default. + +**Example:** + +Global configuration you will most likely want: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update send-updates enable + set service dhcp-server dynamic-dns-update conflict-resolution enable + +Override the above configuration for a shared network NET1: + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update replace-client-name when-not-present + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update generated-prefix ip + set service dhcp-server shared-network-name 'NET1' dynamic-dns-update qualifying-suffix mybigdomain.net + +And in a subnet within the same shared network: + +.. code-block:: none + + set service dhcp-server shared-network-name 'NET1' subnet '172.18.201.0/24' dynamic-dns-update qualifying-suffix mydomain.net + +Configure TSIG keys: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update tsig-key mydomain-net algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key mydomain-net secret eWF5YW15bGl0dGxla2V5IQ== + set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 algorithm hmac-sha256 + set service dhcp-server dynamic-dns-update tsig-key reverse-172-18-201 secret eWF5YW15YW5vdGhlcmxpdHRsZWtleSE= + +Configure DDNS domains: + +.. code-block:: none + + set service dhcp-server dynamic-dns-update forward-domain mydomain.net key-name mydomain-net + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update forward-domain mydomain.net dns-server 2 port 53 + set service dhcp-server dynamic-dns-update forward-domain 201.18.172.in-addr.arpa key-name reverse-172-18-201 + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 address '172.18.0.254' + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 1 port 1053 + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 address '192.168.124.254' + set service dhcp-server dynamic-dns-update reverse-domain 201.18.172.in-addr.arpa dns-server 2 port 53 + + High Availability ----------------- @@ -198,9 +379,7 @@ statements on both servers: .. cfgcmd:: set service dhcp-server high-availability name <name> - A generic `<name>` referencing this sync service. - - .. note:: `<name>` must be identical on both sides! + Define the name of the peer server to establish and identify the HA (High Availability) connection. .. cfgcmd:: set service dhcp-server high-availability status <primary | secondary> @@ -429,8 +608,8 @@ Configuration of a DHCP HA pair: * Setup DHCP HA for network 192.0.2.0/24 * Use active-active HA mode. * Default gateway and DNS server is at `192.0.2.254` -* The primary DHCP server uses address `192.168.189.252` -* The secondary DHCP server uses address `192.168.189.253` +* The primary DHCP server named dhcp-primary uses address `192.168.189.252` +* The secondary DHCP server with named dhcp-secondary uses address `192.168.189.253` * DHCP range spans from `192.168.189.10` - `192.168.189.250` Common configuration, valid for both primary and secondary node. @@ -451,7 +630,7 @@ Common configuration, valid for both primary and secondary node. set service dhcp-server high-availability mode 'active-active' set service dhcp-server high-availability source-address '192.168.189.252' - set service dhcp-server high-availability name 'NET-VYOS' + set service dhcp-server high-availability name 'dhcp-secondary' set service dhcp-server high-availability remote '192.168.189.253' set service dhcp-server high-availability status 'primary' @@ -461,7 +640,7 @@ Common configuration, valid for both primary and secondary node. set service dhcp-server high-availability mode 'active-active' set service dhcp-server high-availability source-address '192.168.189.253' - set service dhcp-server high-availability name 'NET-VYOS' + set service dhcp-server high-availability name 'dhcp-primary' set service dhcp-server high-availability remote '192.168.189.252' set service dhcp-server high-availability status 'secondary' @@ -645,7 +824,7 @@ used: .. cfgcmd:: set service dhcpv6-server shared-network-name <name> subnet - <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> + <prefix> prefix-delegation prefix <pd-prefix> excluded-prefix-length <length> Define lenght of exclude prefix in `<pd-prefix>`. @@ -663,8 +842,7 @@ used: set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 range 1 stop 2001:db8::199 set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: delegated-length '64' set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 prefix-delegation prefix 2001:db8:0:10:: prefix-length '60' - - + set service dhcpv6-server shared-network-name 'PD-NET' subnet 2001:db8::/64 subnet-id 1 Address pools ------------- diff --git a/docs/configuration/service/ids.rst b/docs/configuration/service/ids.rst deleted file mode 100644 index 8a64467f..00000000 --- a/docs/configuration/service/ids.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _ids: - -############### -DDoS Protection -############### - -********** -FastNetMon -********** - -FastNetMon is a high-performance DDoS detector/sensor built on top of multiple -packet capture engines: NetFlow, IPFIX, sFlow, AF_PACKET (port mirror). It can -detect hosts in the deployed network sending or receiving large volumes of -traffic, packets/bytes/flows per second and perform a configurable action to -handle that event, such as calling a custom script. - -VyOS includes the FastNetMon Community Edition. - -Configuration -============= - -.. cfgcmd:: set service ids ddos-protection alert-script <text> - - Configure alert script that will be executed when an attack is detected. - -.. cfgcmd:: set service ids ddos-protection ban-time <1-4294967294> - - Configure how long an IP (attacker) should be kept in blocked state. - Default value is 1900. - -.. cfgcmd:: set service ids ddos-protection direction [in | out] - - Configure direction for processing traffic. - -.. cfgcmd:: set service ids ddos-protection exclude-network <x.x.x.x/x> -.. cfgcmd:: set service ids ddos-protection exclude-network <h:h:h:h:h:h:h:h/x> - - Specify IPv4 and/or IPv6 networks which are going to be excluded. - -.. cfgcmd:: set service ids ddos-protection listen-interface <text> - - Configure listen interface for mirroring traffic. - -.. cfgcmd:: set service ids ddos-protection mode [mirror | sflow] - - Configure traffic capture mode. - -.. cfgcmd:: set service ids ddos-protection network <x.x.x.x/x> -.. cfgcmd:: set service ids ddos-protection network <h:h:h:h:h:h:h:h/x> - - Specify IPv4 and/or IPv6 networks that should be protected/monitored. - -.. cfgcmd:: set service ids ddos-protection sflow listen-address <x.x.x.x> - - Configure local IPv4 address to listen for sflow. - -.. cfgcmd:: set service ids ddos-protection sflow port <1-65535> - - Configure port number to be used for sflow connection. Default port is 6343. - -.. cfgcmd:: set service ids ddos-protection threshold general - [fps | mbps | pps] <0-4294967294> - - Configure general threshold parameters. - -.. cfgcmd:: set service ids ddos-protection threshold icmp - [fps | mbps | pps] <0-4294967294> - - Configure ICMP threshold parameters. - -.. cfgcmd:: set service ids ddos-protection threshold tcp - [fps | mbps | pps] <0-4294967294> - - Configure TCP threshold parameters - -.. cfgcmd:: set service ids ddos-protection threshold udp - [fps | mbps | pps] <0-4294967294> - - Configure UDP threshold parameters - -Example -======= - -A configuration example can be found in this section. -In this simplified scenario, main things to be considered are: - - * Network to be protected: 192.0.2.0/24 (public IPs use by - customers) - - * **ban-time** and **threshold**: these values are kept very low in order - to easily identify and generate and attack. - - * Direction: **in** and **out**. Protect public network from external - attacks, and identify internal attacks towards internet. - - * Interface **eth0** used to connect to upstream. - -Since we are analyzing attacks to and from our internal network, two types -of attacks can be identified, and different actions are needed: - - * External attack: an attack from the internet towards an internal IP - is identify. In this case, all connections towards such IP will be - blocked - - * Internal attack: an attack from the internal network (generated by a - customer) towards the internet is identify. In this case, all connections - from this particular IP/Customer will be blocked. - - -So, firewall configuration needed for this setup: - -.. code-block:: none - - set firewall group address-group FNMS-DST-Block - set firewall group address-group FNMS-SRC-Block - - set firewall ipv4 forward filter rule 10 action 'drop' - set firewall ipv4 forward filter rule 10 description 'FNMS - block destination' - set firewall ipv4 forward filter rule 10 destination group address-group 'FNMS-DST-Block' - - set firewall ipv4 forward filter rule 20 action 'drop' - set firewall ipv4 forward filter rule 20 description 'FNMS - Block source' - set firewall ipv4 forward filter rule 20 source group address-group 'FNMS-SRC-Block' - -Then, FastNetMon configuration: - -.. code-block:: none - - set service ids ddos-protection alert-script '/config/scripts/fnm-alert.sh' - set service ids ddos-protection ban-time '10' - set service ids ddos-protection direction 'in' - set service ids ddos-protection direction 'out' - set service ids ddos-protection listen-interface 'eth0' - set service ids ddos-protection mode 'mirror' - set service ids ddos-protection network '192.0.2.0/24' - set service ids ddos-protection threshold general pps '100' - -And content of the script: - -.. code-block:: none - - #!/bin/bash - - # alert-script is called twice. - # When an attack occurs, the program calls a bash script twice: - # 1st time when threshold exceed - # 2nd when we collect 100 packets for detailed audit of what happened. - - # Do nothing if “attack_details” is passed as an argument - if [ "${4}" == "attack_details" ]; then - # Do nothing - exit - fi - # Arguments: - ip=$1 - direction=$2 - pps_rate=$3 - action=$4 - - logger -t FNMS "** Start - Running alert script **" - - if [ "${direction}" == "incoming" ] ; then - group="FNMS-DST-Block" - origin="external" - else - group="FNMS-SRC-Block" - origin="internal" - fi - - if [ "${action}" == "ban" ] ; then - logger -t FNMS "Attack detected for IP ${ip} and ${direction} direction from ${origin} network. Need to block IP address." - logger -t FNMS "Adding IP address ${ip} to firewall group ${group}." - sudo nft add element ip vyos_filter A_${group} { ${ip} } - else - logger -t FNMS "Timeout for IP ${ip}, removing it from group ${group}." - sudo nft delete element ip vyos_filter A_${group} { ${ip} } - fi - logger -t FNMS "** End - Running alert script **" - exit diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst index f5c97d14..fb6f8413 100644 --- a/docs/configuration/service/index.rst +++ b/docs/configuration/service/index.rst @@ -16,7 +16,6 @@ Service dns eventhandler https - ids ipoe-server lldp mdns diff --git a/docs/configuration/service/ipoe-server.rst b/docs/configuration/service/ipoe-server.rst index ef06bcd5..5d7acd5a 100644 --- a/docs/configuration/service/ipoe-server.rst +++ b/docs/configuration/service/ipoe-server.rst @@ -174,11 +174,12 @@ RADIUS advanced options .. cfgcmd:: set service ipoe-server authentication radius dynamic-author server <address> - Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + Specifies IP address for Dynamic Authorization Extension server (DM/CoA). + This IP must exist on any VyOS interface or it can be ``0.0.0.0``. .. cfgcmd:: set service ipoe-server authentication radius dynamic-author port <port> - Port for Dynamic Authorization Extension server (DM/CoA) + UDP port for Dynamic Authorization Extension server (DM/CoA) .. cfgcmd:: set service ipoe-server authentication radius dynamic-author key <secret> diff --git a/docs/configuration/service/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 6d818c70..f763536a 100644 --- a/docs/configuration/service/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst @@ -144,12 +144,13 @@ RADIUS advanced options .. cfgcmd:: set service pppoe-server authentication radius dynamic-author server <address> - Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + Specifies IP address for Dynamic Authorization Extension server (DM/CoA). + This IP must exist on any VyOS interface or it can be ``0.0.0.0``. .. cfgcmd:: set service pppoe-server authentication radius dynamic-author port <port> - Port for Dynamic Authorization Extension server (DM/CoA) + UDP port for Dynamic Authorization Extension server (DM/CoA) .. cfgcmd:: set service pppoe-server authentication radius dynamic-author key <secret> @@ -681,4 +682,4 @@ a /56 subnet for the clients internal use. .. _dictionary: https://github.com/accel-ppp/accel-ppp/blob/master/ accel-pppd/radius/dict/dictionary.rfc6911 .. _`ACCEL-PPP attribute`: https://github.com/accel-ppp/accel-ppp/ - blob/master/accel-pppd/radius/dict/dictionary.accel
\ No newline at end of file + blob/master/accel-pppd/radius/dict/dictionary.accel diff --git a/docs/configuration/service/router-advert.rst b/docs/configuration/service/router-advert.rst index 365017dd..cb9a6037 100644 --- a/docs/configuration/service/router-advert.rst +++ b/docs/configuration/service/router-advert.rst @@ -46,6 +46,7 @@ Configuration "Interval", "interval", "Min and max intervals between unsolicited multicast RAs" "DNSSL", "dnssl", "DNS search list to advertise" "Name Server", "name-server", "Advertise DNS server per https://tools.ietf.org/html/rfc6106" + "Auto Ignore Prefix", "auto-ignore", "Exclude a prefix from being advertised when the wildcard ::/64 prefix is used" .. start_vyoslinter @@ -56,8 +57,8 @@ Advertising a Prefix .. cfgcmd:: set service router-advert interface <interface> prefix <prefix/mask> .. note:: You can also opt for using `::/64` as prefix for your :abbr:`RAs (Router - Advertisements)`. This will take the IPv6 GUA prefix assigned to the interface, - which comes in handy when using DHCPv6-PD. + Advertisements)`. This is a special wildcard prefix that will emit :abbr:`RAs (Router Advertisements)` for every prefix assigned to the interface. + This comes in handy when using dynamically obtained prefixes from DHCPv6-PD. .. stop_vyoslinter diff --git a/docs/configuration/service/ssh.rst b/docs/configuration/service/ssh.rst index 4fa44d3e..c9969aa6 100644 --- a/docs/configuration/service/ssh.rst +++ b/docs/configuration/service/ssh.rst @@ -129,11 +129,34 @@ Configuration ``rsa-sha2-256-cert-v01@openssh.com``, ``rsa-sha2-512``, ``rsa-sha2-512-cert-v01@openssh.com`` -.. cfgcmd:: set service ssh trusted-user-ca-key ca-certificate <ca_cert_name> +.. cfgcmd:: set service ssh trusted-user-ca <name> + + Specify the name of the OpenSSH key-pair that acts as certificate authority + and will be used to verify user certificates. + + You can use it by adding the OpenSSH key-pair under the PKI subsystem. + + Example: + + .. code-block:: none + + # Generate key-pair acting as CA + $ ssh-keygen -f vyos-ssh-ca.key + + # Generate key for user: vyos_testca + $ ssh-keygen -f vyos_testca -C "vyos_tesca@vyos.net" + + # Sign public key from user vyos_testca and insert principal names: vyos, vyos_testca + # with a key lifetime of two weeks - after which the key is unusable + $ ssh-keygen -s vyos-ssh-ca.key -I vyos_testca@vyos.net -n vyos,vyos_testca -V +2w vyos_testca.pub + + $ set system login user vyos_testca + $ set pki openssh test_ca public key AAAAB3N..... + $ set pki openssh test_ca public type ssh-rsa + $ set service ssh trusted-user-ca test_ca + + You can now log into the system using: ``ssh -i vyos_testca vyos_testca@vyos.test.com`` - Specify the name of the CA certificate that will be used to verify the user - certificates. - You can use it by adding the CA certificate with the PKI command. Dynamic-protection ================== diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst index a422388f..27b0870c 100644 --- a/docs/configuration/system/ip.rst +++ b/docs/configuration/system/ip.rst @@ -27,6 +27,20 @@ System configuration commands Use this command to use Layer 4 information for IPv4 ECMP hashing. +.. cfgcmd:: set system ip import-table <table-id> + + Use this command to immport the table, by given table id, into the main RIB. + +.. cfgcmd:: set system ip import-table <table-id> distance <distance> + + Use this command to override the default distance when importing routers + from the alternate table. + +.. cfgcmd:: set system ip import-table <table-id> route-map <route-map> + + Use this command to filter routes that are imported into the main table + from alternate table using route-map. + Zebra/Kernel route filtering ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/configuration/system/login.rst b/docs/configuration/system/login.rst index 3a7481eb..1c4e041d 100644 --- a/docs/configuration/system/login.rst +++ b/docs/configuration/system/login.rst @@ -34,6 +34,13 @@ Local Setup encrypted password for given username. This is useful for transferring a hashed password from system to system. +.. cfgcmd:: set system login user <name> authentication principal <principal> + + When using SSH certificate based authentication, define which principals are + alled to use this account. + + If unset, the principal will be set to the login name of the user bz default. + .. cfgcmd:: set system login user <name> disable Disable (lock) account. User will not be able to log in. diff --git a/docs/configuration/system/option.rst b/docs/configuration/system/option.rst index b5ebaaee..a13e38a8 100644 --- a/docs/configuration/system/option.rst +++ b/docs/configuration/system/option.rst @@ -18,6 +18,16 @@ General Automatically reboot system on kernel panic after 60 seconds. +.. cfgcmd:: set system option reboot-on-upgrade-failure <timeout> + + Automatically reboot after `timeout` minutes into the previous running + image, that was used to perform the image upgrade. + + Reboot `timeout` is configurable in minutes. This gives the user the change + to log into the system and perform some analysis before automatic rebooting. + + Automatic reboot can be cancelled after login using: :opcmd:`reboot cancel` + .. cfgcmd:: set system option startup-beep Play an audible beep to the system speaker when system is ready. @@ -72,6 +82,11 @@ Kernel .. seealso:: https://docs.kernel.org/admin-guide/pm/amd-pstate.html +.. cfgcmd:: set system option kernel quiet + + Suppress most kernel messages during boot. This is useful for systems with + embedded serial console interfaces to speed up the boot process. + *********** HTTP client *********** diff --git a/docs/configuration/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst index e58eecbc..59f5af1e 100644 --- a/docs/configuration/vpn/dmvpn.rst +++ b/docs/configuration/vpn/dmvpn.rst @@ -146,7 +146,7 @@ NHRP protocol configuration IPSEC configuration ============================== -* Please refer to the :ref:`ipsec` documentation for the individual IPSec +* Please refer to the :ref:`ipsec_general` documentation for the individual IPSec related options. .. note:: NHRP daemon based on FRR nhrpd. It controls IPSEC. That's why 'close-action' diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst index cf825a63..d0121abd 100644 --- a/docs/configuration/vpn/index.rst +++ b/docs/configuration/vpn/index.rst @@ -7,7 +7,7 @@ VPN :maxdepth: 1 :includehidden: - ipsec + ipsec/index l2tp openconnect pptp @@ -22,5 +22,3 @@ pages to sort :includehidden: dmvpn - site2site_ipsec - remoteaccess_ipsec diff --git a/docs/configuration/vpn/ipsec.rst b/docs/configuration/vpn/ipsec.rst deleted file mode 100644 index 5e44312d..00000000 --- a/docs/configuration/vpn/ipsec.rst +++ /dev/null @@ -1,657 +0,0 @@ -.. _ipsec: - -##### -IPsec -##### - -:abbr:`GRE (Generic Routing Encapsulation)`, GRE/IPsec (or IPIP/IPsec, -SIT/IPsec, or any other stateless tunnel protocol over IPsec) is the usual way -to protect the traffic inside a tunnel. - -An advantage of this scheme is that you get a real interface with its own -address, which makes it easier to setup static routes or use dynamic routing -protocols without having to modify IPsec policies. The other advantage is that -it greatly simplifies router to router communication, which can be tricky with -plain IPsec because the external outgoing address of the router usually doesn't -match the IPsec policy of a typical site-to-site setup and you would need to -add special configuration for it, or adjust the source address of the outgoing -traffic of your applications. GRE/IPsec has no such problem and is completely -transparent for applications. - -GRE/IPIP/SIT and IPsec are widely accepted standards, which make this scheme -easy to implement between VyOS and virtually any other router. - -For simplicity we'll assume that the protocol is GRE, it's not hard to guess -what needs to be changed to make it work with a different protocol. We assume -that IPsec will use pre-shared secret authentication and will use AES128/SHA1 -for the cipher and hash. Adjust this as necessary. - -.. NOTE:: VMware users should ensure that a VMXNET3 adapter is used. E1000 - adapters have known issues with GRE processing. - -************************************** -IKE (Internet Key Exchange) Attributes -************************************** - -IKE performs mutual authentication between two parties and establishes -an IKE security association (SA) that includes shared secret information -that can be used to efficiently establish SAs for Encapsulating Security -Payload (ESP) or Authentication Header (AH) and a set of cryptographic -algorithms to be used by the SAs to protect the traffic that they carry. -https://datatracker.ietf.org/doc/html/rfc5996 - -In VyOS, IKE attributes are specified through IKE groups. -Multiple proposals can be specified in a single group. - -VyOS IKE group has the next options: - -* ``close-action`` defines the action to take if the remote peer unexpectedly - closes a CHILD_SA: - - * ``none`` set action to none (default); - - * ``trap`` installs a trap policy for the CHILD_SA; - - * ``start`` tries to immediately re-create the CHILD_SA; - -* ``dead-peer-detection`` controls the use of the Dead Peer Detection protocol - (DPD, RFC 3706) where R_U_THERE notification messages (IKEv1) or empty - INFORMATIONAL messages (IKEv2) are periodically sent in order to check the - liveliness of the IPsec peer: - - * ``action`` keep-alive failure action: - - * ``trap`` installs a trap policy, which will catch matching traffic - and tries to re-negotiate the tunnel on-demand; - - * ``clear`` closes the CHILD_SA and does not take further action (default); - - * ``restart`` immediately tries to re-negotiate the CHILD_SA - under a fresh IKE_SA; - - * ``interval`` keep-alive interval in seconds <2-86400> (default 30); - - * ``timeout`` keep-alive timeout in seconds <2-86400> (default 120) IKEv1 only - -* ``ikev2-reauth`` whether rekeying of an IKE_SA should also reauthenticate - the peer. In IKEv1, reauthentication is always done. - Setting this parameter enables remote host re-authentication during an IKE - rekey. - -* ``key-exchange`` which protocol should be used to initialize the connection - If not set both protocols are handled and connections will use IKEv2 when - initiating, but accept any protocol version when responding: - - * ``ikev1`` use IKEv1 for Key Exchange; - - * ``ikev2`` use IKEv2 for Key Exchange; - -* ``lifetime`` IKE lifetime in seconds <0-86400> (default 28800); - -* ``disable-mobike`` disables MOBIKE Support. MOBIKE is only available for IKEv2 - and enabled by default. - -* ``mode`` IKEv1 Phase 1 Mode Selection: - - * ``main`` use Main mode for Key Exchanges in the IKEv1 Protocol - (Recommended Default); - - * ``aggressive`` use Aggressive mode for Key Exchanges in the IKEv1 protocol - aggressive mode is much more insecure compared to Main mode; - -* ``proposal`` the list of proposals and their parameters: - - * ``dh-group`` dh-group; - - * ``encryption`` encryption algorithm; - - * ``hash`` hash algorithm. - - * ``prf`` pseudo-random function. - -*********************************************** -ESP (Encapsulating Security Payload) Attributes -*********************************************** - -ESP is used to provide confidentiality, data origin authentication, -connectionless integrity, an anti-replay service (a form of partial sequence -integrity), and limited traffic flow confidentiality. -https://datatracker.ietf.org/doc/html/rfc4303 - -In VyOS, ESP attributes are specified through ESP groups. -Multiple proposals can be specified in a single group. - -VyOS ESP group has the next options: - -* ``compression`` Enables the IPComp(IP Payload Compression) protocol which - allows compressing the content of IP packets. - -* ``life-bytes`` ESP life in bytes <1024-26843545600000>. - Number of bytes transmitted over an IPsec SA before it expires; - -* ``life-packets`` ESP life in packets <1000-26843545600000>. - Number of packets transmitted over an IPsec SA before it expires; - -* ``lifetime`` ESP lifetime in seconds <30-86400> (default 3600). - How long a particular instance of a connection (a set of - encryption/authentication keys for user packets) should last, - from successful negotiation to expiry; - -* ``mode`` the type of the connection: - - * ``tunnel`` tunnel mode (default); - - * ``transport`` transport mode; - -* ``pfs`` whether Perfect Forward Secrecy of keys is desired on the - connection's keying channel and defines a Diffie-Hellman group for PFS: - - * ``enable`` Inherit Diffie-Hellman group from IKE group (default); - - * ``disable`` Disable PFS; - - * ``< dh-group >`` defines a Diffie-Hellman group for PFS; - -* ``proposal`` ESP-group proposal with number <1-65535>: - - * ``encryption`` encryption algorithm (default 128 bit AES-CBC); - - * ``hash`` hash algorithm (default sha1). - - * ``disable-rekey`` Do not locally initiate a re-key of the SA, remote - peer must re-key before expiration. - -*********************************************** -Options (Global IPsec settings) Attributes -*********************************************** - -* ``options`` - - * ``disable-route-autoinstall`` Do not automatically install routes to remote - networks; - - * ``flexvpn`` Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco - FlexVPN vendor ID payload (IKEv2 only), which is required in order to make - Cisco brand devices allow negotiating a local traffic selector (from - strongSwan's point of view) that is not the assigned virtual IP address if - such an address is requested by strongSwan. Sending the Cisco FlexVPN - vendor ID prevents the peer from narrowing the initiator's local traffic - selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0 - instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco - template but should also work for GRE encapsulation; - - * ``interface`` Interface Name to use. The name of the interface on which - virtual IP addresses should be installed. If not specified the addresses - will be installed on the outbound interface; - - * ``virtual-ip`` Allows the installation of virtual-ip addresses. A comma - separated list of virtual IPs to request in IKEv2 configuration payloads or - IKEv1 Mode Config. The wildcard addresses 0.0.0.0 and :: request an - arbitrary address, specific addresses may be defined. The responder may - return a different address, or none at all. Define the ``virtual-address`` - option to configure the IP address in a site-to-site hierarchy. - -************************* -IPsec policy matching GRE -************************* - -The first and arguably cleaner option is to make your IPsec policy match GRE -packets between external addresses of your routers. This is the best option if -both routers have static external addresses. - -Suppose the LEFT router has external address 192.0.2.10 on its eth0 interface, -and the RIGHT router is 203.0.113.45 - -On the LEFT: - -.. code-block:: none - - # GRE tunnel - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 source-address 192.0.2.10 - set interfaces tunnel tun0 remote 203.0.113.45 - set interfaces tunnel tun0 address 10.10.10.1/30 - - ## IPsec - set vpn ipsec interface eth0 - - # Pre-shared-secret - set vpn ipsec authentication psk vyos id 192.0.2.10 - set vpn ipsec authentication psk vyos id 203.0.113.45 - set vpn ipsec authentication psk vyos secret MYSECRETKEY - - # IKE group - set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group '2' - set vpn ipsec ike-group MyIKEGroup proposal 1 encryption 'aes128' - set vpn ipsec ike-group MyIKEGroup proposal 1 hash 'sha1' - - # ESP group - set vpn ipsec esp-group MyESPGroup proposal 1 encryption 'aes128' - set vpn ipsec esp-group MyESPGroup proposal 1 hash 'sha1' - - # IPsec tunnel - set vpn ipsec site-to-site peer right authentication mode pre-shared-secret - set vpn ipsec site-to-site peer right authentication remote-id 203.0.113.45 - - set vpn ipsec site-to-site peer right ike-group MyIKEGroup - set vpn ipsec site-to-site peer right default-esp-group MyESPGroup - - set vpn ipsec site-to-site peer right local-address 192.0.2.10 - set vpn ipsec site-to-site peer right remote-address 203.0.113.45 - - # This will match all GRE traffic to the peer - set vpn ipsec site-to-site peer right tunnel 1 protocol gre - -On the RIGHT, setup by analogy and swap local and remote addresses. - - -Source tunnel from dummy interface -================================== - -The scheme above doesn't work when one of the routers has a dynamic external -address though. The classic workaround for this is to setup an address on a -loopback interface and use it as a source address for the GRE tunnel, then setup -an IPsec policy to match those loopback addresses. - -We assume that the LEFT router has static 192.0.2.10 address on eth0, and the -RIGHT router has a dynamic address on eth0. - -The peer names RIGHT and LEFT are used as informational text. - -**Setting up the GRE tunnel** - -On the LEFT: - -.. code-block:: none - - set interfaces dummy dum0 address 192.168.99.1/32 - - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 address 10.10.10.1/30 - set interfaces tunnel tun0 source-address 192.168.99.1 - set interfaces tunnel tun0 remote 192.168.99.2 - -On the RIGHT: - -.. code-block:: none - - set interfaces dummy dum0 address 192.168.99.2/32 - - set interfaces tunnel tun0 encapsulation gre - set interfaces tunnel tun0 address 10.10.10.2/30 - set interfaces tunnel tun0 source-address 192.168.99.2 - set interfaces tunnel tun0 remote 192.168.99.1 - -**Setting up IPSec** - -However, now you need to make IPsec work with dynamic address on one side. The -tricky part is that pre-shared secret authentication doesn't work with dynamic -address, so we'll have to use RSA keys. - -First, on both routers run the operational command "generate pki key-pair -install <key-pair name>". You may choose different length than 2048 of course. - -.. code-block:: none - - vyos@left# run generate pki key-pair install ipsec-LEFT - Enter private key type: [rsa, dsa, ec] (Default: rsa) - Enter private key bits: (Default: 2048) - Note: If you plan to use the generated key on this router, do not encrypt the private key. - Do you want to encrypt the private key with a passphrase? [y/N] N - Configure mode commands to install key pair: - Do you want to install the public key? [Y/n] Y - set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' - Do you want to install the private key? [Y/n] Y - set pki key-pair ipsec-LEFT private key 'MIIEvgIBADAN...' - [edit] - -Configuration commands for the private and public key will be displayed on the -screen which needs to be set on the router first. -Note the command with the public key -(set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...'). -Then do the same on the opposite router: - -.. code-block:: none - - vyos@left# run generate pki key-pair install ipsec-RIGHT - -Note the command with the public key -(set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...'). - -Now the noted public keys should be entered on the opposite routers. - -On the LEFT: - -.. code-block:: none - - set pki key-pair ipsec-RIGHT public key 'FAAOCAQ8AMII...' - -On the RIGHT: - -.. code-block:: none - - set pki key-pair ipsec-LEFT public key 'MIIBIjANBgkqh...' - -Now you are ready to setup IPsec. You'll need to use an ID instead of address -for the peer. - -On the LEFT (static address): - -.. code-block:: none - - set vpn ipsec interface eth0 - - set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 - set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 - - set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 - set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 - set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - - set vpn ipsec site-to-site peer RIGHT authentication local-id LEFT - set vpn ipsec site-to-site peer RIGHT authentication mode rsa - set vpn ipsec site-to-site peer RIGHT authentication rsa local-key ipsec-LEFT - set vpn ipsec site-to-site peer RIGHT authentication rsa remote-key ipsec-RIGHT - set vpn ipsec site-to-site peer RIGHT authentication remote-id RIGHT - set vpn ipsec site-to-site peer RIGHT default-esp-group MyESPGroup - set vpn ipsec site-to-site peer RIGHT ike-group MyIKEGroup - set vpn ipsec site-to-site peer RIGHT local-address 192.0.2.10 - set vpn ipsec site-to-site peer RIGHT connection-type respond - set vpn ipsec site-to-site peer RIGHT tunnel 1 local prefix 192.168.99.1/32 # Additional loopback address on the local - set vpn ipsec site-to-site peer RIGHT tunnel 1 remote prefix 192.168.99.2/32 # Additional loopback address on the remote - -On the RIGHT (dynamic address): - -.. code-block:: none - - set vpn ipsec interface eth0 - - set vpn ipsec esp-group MyESPGroup proposal 1 encryption aes128 - set vpn ipsec esp-group MyESPGroup proposal 1 hash sha1 - - set vpn ipsec ike-group MyIKEGroup proposal 1 dh-group 2 - set vpn ipsec ike-group MyIKEGroup proposal 1 encryption aes128 - set vpn ipsec ike-group MyIKEGroup proposal 1 hash sha1 - - set vpn ipsec site-to-site peer LEFT authentication local-id RIGHT - set vpn ipsec site-to-site peer LEFT authentication mode rsa - set vpn ipsec site-to-site peer LEFT authentication rsa local-key ipsec-RIGHT - set vpn ipsec site-to-site peer LEFT authentication rsa remote-key ipsec-LEFT - set vpn ipsec site-to-site peer LEFT authentication remote-id LEFT - set vpn ipsec site-to-site peer LEFT connection-type initiate - set vpn ipsec site-to-site peer LEFT default-esp-group MyESPGroup - set vpn ipsec site-to-site peer LEFT ike-group MyIKEGroup - set vpn ipsec site-to-site peer LEFT local-address any - set vpn ipsec site-to-site peer LEFT remote-address 192.0.2.10 - set vpn ipsec site-to-site peer LEFT tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local - set vpn ipsec site-to-site peer LEFT tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote - - -******************************************* -IKEv2 IPSec road-warriors remote-access VPN -******************************************* - -Internet Key Exchange version 2, IKEv2 for short, is a request/response -protocol developed by both Cisco and Microsoft. It is used to establish and -secure IPv4/IPv6 connections, be it a site-to-site VPN or from a -road-warrior connecting to a hub site. IKEv2, when run in point-to-multipoint, -or remote-access/road-warrior mode, secures the server-side with another layer -by using an x509 signed server certificate. - -Key exchange and payload encryption is still done using IKE and ESP proposals -as known from IKEv1 but the connections are faster to establish, more reliable, -and also support roaming from IP to IP (called MOBIKE which makes sure your -connection does not drop when changing networks from e.g. WIFI to LTE and back). - -This feature closely works together with :ref:`pki` subsystem as you required -a x509 certificate. - -Example -======= - -This example uses CACert as certificate authority. - -.. code-block:: - - set pki ca CAcert_Class_3_Root certificate 'MIIGPTCCBCWgAwIBAgIDFOIoMA0GCSqGSIb3DQEBDQUAMHkxEDAOBgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYSc3VwcG9ydEBjYWNlcnQub3JnMB4XDTIxMDQxOTEyMTgzMFoXDTMxMDQxNzEyMTgzMFowVDEUMBIGA1UEChMLQ0FjZXJ0IEluYy4xHjAcBgNVBAsTFWh0dHA6Ly93d3cuQ0FjZXJ0Lm9yZzEcMBoGA1UEAxMTQ0FjZXJ0IENsYXNzIDMgUm9vdDCCAiIwDQYJKoZIhvcNAQEBBQADggIPADCCAgoCggIBAKtJNRFIfNImflOUz0Op3SjXQiqL84d4GVh8D57aiX3h++tykA10oZZkq5+gJJlz2uJVdscXe/UErEa4w75/ZI0QbCTzYZzA8pD6Ueb1aQFjww9W4kpCz+JEjCUoqMV5CX1GuYrz6fM0KQhF5Byfy5QEHIGoFLOYZcRD7E6CjQnRvapbjZLQ7N6QxX8KwuPr5jFaXnQ+lzNZ6MMDPWAzv/fRb0fEze5ig1JuLgiapNkVGJGmhZJHsK5I6223IeyFGmhyNav/8BBdwPSUp2rVO5J+TJAFfpPBLIukjmJ0FXFuC3ED6q8VOJrU0gVyb4z5K+taciX5OUbjchs+BMNkJyIQKopPWKcDrb60LhPtXapI19V91Cp7XPpGBFDkzA5CW4zt2/LP/JaT4NsRNlRiNDiPDGCbO5dWOK3z0luLoFvqTpa4fNfVoIZwQNORKbeiPK31jLvPGpKK5DR7wNhsX+kKwsOnIJpa3yxdUly6R9Wb7yQocDggL9V/KcCyQQNokszgnMyXS0XvOhAKq3A6mJVwrTWx6oUrpByAITGprmB6gCZIALgBwJNjVSKRPFbnr9s6JfOPMVTqJouBWfmh0VMRxXudA/Z0EeBtsSw/LIaRmXGapneLNGDRFLQsrJ2vjBDTn8Rq+G8T/HNZ92ZCdB6K4/jc0m+YnMtHmJVABfvpAgMBAAGjgfIwge8wDwYDVR0TAQH/BAUwAwEB/zBhBggrBgEFBQcBAQRVMFMwIwYIKwYBBQUHMAGGF2h0dHA6Ly9vY3NwLkNBY2VydC5vcmcvMCwGCCsGAQUFBzAChiBodHRwOi8vd3d3LkNBY2VydC5vcmcvY2xhc3MzLmNydDBFBgNVHSAEPjA8MDoGCysGAQQBgZBKAgMBMCswKQYIKwYBBQUHAgEWHWh0dHA6Ly93d3cuQ0FjZXJ0Lm9yZy9jcHMucGhwMDIGA1UdHwQrMCkwJ6AloCOGIWh0dHBzOi8vd3d3LmNhY2VydC5vcmcvY2xhc3MzLmNybDANBgkqhkiG9w0BAQ0FAAOCAgEAxh6td1y0KJvRyI1EEsC9dnYEgyEH+BGCf2vBlULAOBG1JXCNiwzB1Wz9HBoDfIv4BjGlnd5BKdSLm4TXPcE3hnGjH1thKR5dd3278K25FRkTFOY1gP+mGbQ3hZRB6IjDX+CyBqS7+ECpHTms7eo/mARN+Yz5R3lzUvXs3zSX+z534NzRg4i6iHNHWqakFcQNcA0PnksTB37vGD75pQGqeSmx51L6UzrIpn+274mhsaFNL85jhX+lKuk71MGjzwoThbuZ15xmkITnZtRQs6HhLSIqJWjDILIrxLqYHehK71xYwrRNhFb3TrsWaEJskrhveM0Os/vvoLNkh/L3iEQ5/LnmLMCYJNRALF7I7gsduAJNJrgKGMYvHkt1bo8uIXO8wgNV7qoU4JoaB1ML30QUqGcFr0TI06FFdgK2fwy5hulPxm6wuxW0v+iAtXYx/mRkwQpYbcVQtrIDvx1CT1k50cQxi+jIKjkcFWHw3kBoDnCos0/ukegPT7aQnk2AbL4c7nCkuAcEKw1BAlSETkfqi5btdlhh58MhewZv1LcL5zQyg8w1puclT3wXQvy8VwPGn0J/mGD4gLLZ9rGcHDUECokxFoWk+u5MCcVqmGbsyG4q5suS3CNslsHURfM8bQK4oLvHR8LCHEBMRcdFBn87cSvOK6eB1kdGKLA8ymXxZp8=' - set pki ca CAcert_Signing_Authority certificate 'MIIG7jCCBNagAwIBAgIBDzANBgkqhkiG9w0BAQsFADB5MRAwDgYDVQQKEwdSb290IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNBIENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRAY2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAOBgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEiMCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJARYSc3VwcG9ydEBjYWNlcnQub3JnMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAziLA4kZ97DYoB1CW8qAzQIxL8TtmPzHlawI229Z89vGIj053NgVBlfkJ8BLPRoZzYLdufujAWGSuzbCtRRcMY/pnCujW0r8+55jE8Ez64AO7NV1sId6eINm6zWYyN3L69wj1x81YyY7nDl7qPv4coRQKFWyGhFtkZip6qUtTefWIonvuLwphK42yfk1WpRPs6tqSnqxEQR5YYGUFZvjARL3LlPdCfgv3ZWiYUQXw8wWRBB0bF4LsyFe7w2t6iPGwcswlWyCR7BYCEo8y6RcYSNDHBS4CMEK4JZwFaz+qOqfrU0j36NK2B5jcG8Y0f3/JHIJ6BVgrCFvzOKKrF11myZjXnhCLotLddJr3cQxyYN/Nb5gznZY0dj4kepKwDpUeb+agRThHqtdB7Uq3EvbXG4OKDy7YCbZZ16oE/9KTfWgu3YtLq1i6L43qlaegw1SJpfvbi1EinbLDvhG+LJGGi5Z4rSDTii8aP8bQUWWHIbEZAWV/RRyH9XzQQUxPKZgh/TMfdQwEUfoZd9vUFBzugcMd9Zi3aQaRIt0AUMyBMawSB3s42mhb5ivUfslfrejrckzzAeVLIL+aplfKkQABi6F1ITe1Yw1nPkZPcCBnzsXWWdsC4PDSy826YreQQejdIOQpvGQpQsgi3Hia/0PsmBsJUUtaWsJx8cTLc6nloQsCAwEAAaOCAX8wggF7MB0GA1UdDgQWBBQWtTIb1Mfz4OaO873SsDrusjkY0TAPBgNVHRMBAf8EBTADAQH/MDQGCWCGSAGG+EIBCAQnFiVodHRwOi8vd3d3LmNhY2VydC5vcmcvaW5kZXgucGhwP2lkPTEwMFYGCWCGSAGG+EIBDQRJFkdUbyBnZXQgeW91ciBvd24gY2VydGlmaWNhdGUgZm9yIEZSRUUgaGVhZCBvdmVyIHRvIGh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzAxBgNVHR8EKjAoMCagJKAihiBodHRwOi8vY3JsLmNhY2VydC5vcmcvcmV2b2tlLmNybDAzBglghkgBhvhCAQQEJhYkVVJJOmh0dHA6Ly9jcmwuY2FjZXJ0Lm9yZy9yZXZva2UuY3JsMDIGCCsGAQUFBwEBBCYwJDAiBggrBgEFBQcwAYYWaHR0cDovL29jc3AuY2FjZXJ0Lm9yZzAfBgNVHSMEGDAWgBQWtTIb1Mfz4OaO873SsDrusjkY0TANBgkqhkiG9w0BAQsFAAOCAgEAR5zXs6IX01JTt7Rq3b+bNRUhbO9vGBMggczo7R0qIh1kdhS6WzcrDoO6PkpuRg0L3qM7YQB6pw2V+ubzF7xl4C0HWltfzPTbzAHdJtjaJQw7QaBlmAYpN2CLB6Jeg8q/1Xpgdw/+IP1GRwdg7xUpReUA482l4MH1kf0W0ad94SuIfNWQHcdLApmno/SUh1bpZyeWrMnlhkGNDKMxCCQXQ360TwFHc8dfEAaq5ry6cZzm1oetrkSviE2qofxvv1VFiQ+9TX3/zkECCsUB/EjPM0lxFBmu9T5Ih+Eqns9ivmrEIQDv9tNyJHuLsDNqbUBal7OoiPZnXk9LH+qb+pLf1ofv5noy5vX2a5OKebHe+0Ex/A7e+G/HuOjVNqhZ9j5Nispfq9zNyOHGWD8ofj8DHwB50L1Xh5H+EbIoga/hJCQnRtxWkHP699T1JpLFYwapgplivF4TFv4fqp0nHTKC1x9gGrIgvuYJl1txIKmxXdfJzgscMzqpabhtHOMXOiwQBpWzyJkofF/w55e0LttZDBkEsilV/vW0CJsPs3eNaQF+iMWscGOkgLFlWsAS3HwyiYLNJo26aqyWPaIdc8E4ck7Sk08WrFrHIK3EHr4n1FZwmLpFAvucKqgl0hr+2jypyh5puA3KksHF3CsUzjMUvzxMhykh9zrMxQAHLBVrGwc=' - -After you obtain your server certificate you can import it from a file on the -local filesystem, or paste it into the CLI. Please note that when entering the -certificate manually you need to strip the ``-----BEGIN KEY-----`` and -``-----END KEY-----`` tags. Also, the certificate or key needs to be presented -in a single line without line breaks (``\n``). - -To import it from the filesystem use: - -.. code-block:: - - import pki certificate <name> file /path/to/cert.pem - -In our example the certificate name is called vyos: - -.. code-block:: - - set pki certificate vyos certificate 'MIIE45s...' - set pki certificate vyos private key 'MIIEvgI...' - -After the PKI certs are all set up we can start configuring our IPSec/IKE -proposals used for key-exchange end data encryption. The used encryption -ciphers and integrity algorithms vary from operating system to operating -system. The ones used in this post are validated to work on both Windows 10 -and iOS/iPadOS 14 to 17. - -.. code-block:: - - set vpn ipsec esp-group ESP-RW compression 'disable' - set vpn ipsec esp-group ESP-RW lifetime '3600' - set vpn ipsec esp-group ESP-RW pfs 'disable' - set vpn ipsec esp-group ESP-RW proposal 10 encryption 'aes128gcm128' - set vpn ipsec esp-group ESP-RW proposal 10 hash 'sha256' - - set vpn ipsec ike-group IKE-RW key-exchange 'ikev2' - set vpn ipsec ike-group IKE-RW lifetime '7200' - set vpn ipsec ike-group IKE-RW mobike 'enable' - set vpn ipsec ike-group IKE-RW proposal 10 dh-group '14' - set vpn ipsec ike-group IKE-RW proposal 10 encryption 'aes128gcm128' - set vpn ipsec ike-group IKE-RW proposal 10 hash 'sha256' - -Every connection/remote-access pool we configure also needs a pool where -we can draw our client IP addresses from. We provide one IPv4 and IPv6 pool. -Authorized clients will receive an IPv4 address from the 192.0.2.128/25 prefix -and an IPv6 address from the 2001:db8:2000::/64 prefix. We can also send some -DNS nameservers down for our clients to use with their connection. - -.. code-block:: - - set vpn ipsec remote-access pool ra-rw-ipv4 name-server '192.0.2.1' - set vpn ipsec remote-access pool ra-rw-ipv4 prefix '192.0.2.128/25' - set vpn ipsec remote-access pool ra-rw-ipv6 name-server '2001:db8:1000::1' - set vpn ipsec remote-access pool ra-rw-ipv6 prefix '2001:db8:2000::/64' - -VyOS supports multiple IKEv2 remote-access connections. Every connection can -have its own dedicated IKE/ESP ciphers, certificates or local listen address -for e.g. inbound load balancing. - -We configure a new connection named ``rw`` for road-warrior, that identifies -itself as ``192.0.2.1`` to the clients and uses the ``vyos`` certificate -signed by the `CAcert_Class3_Root`` intermediate CA. We select our previously -specified IKE/ESP groups and also link the IP address pool to draw addresses -from. - -.. code-block:: - - set vpn ipsec remote-access connection rw authentication id '192.0.2.1' - set vpn ipsec remote-access connection rw authentication server-mode 'x509' - set vpn ipsec remote-access connection rw authentication x509 ca-certificate 'CAcert_Class_3_Root' - set vpn ipsec remote-access connection rw authentication x509 certificate 'vyos' - set vpn ipsec remote-access connection rw esp-group 'ESP-RW' - set vpn ipsec remote-access connection rw ike-group 'IKE-RW' - set vpn ipsec remote-access connection rw local-address '192.0.2.1' - set vpn ipsec remote-access connection rw pool 'ra-rw-ipv4' - set vpn ipsec remote-access connection rw pool 'ra-rw-ipv6' - -VyOS also supports (currently) two different modes of authentication, local and -RADIUS. To create a new local user named ``vyos`` with password ``vyos`` use the -following commands. - -.. code-block:: - - set vpn ipsec remote-access connection rw authentication client-mode 'eap-mschapv2' - set vpn ipsec remote-access connection rw authentication local-users username vyos password 'vyos' - -If you feel better forwarding all authentication requests to your enterprises -RADIUS server, use the commands below. - -.. code-block:: - - set vpn ipsec remote-access connection rw authentication client-mode 'eap-radius' - set vpn ipsec remote-access radius server 192.0.2.2 key 'secret' - -Client Configuration -==================== - -Configuring VyOS to act as your IPSec access concentrator is one thing, but -you probably need to setup your client connecting to the server so they can -talk to the IPSec gateway. - -Microsoft Windows (10+) ------------------------ - -Windows 10 does not allow a user to choose the integrity and encryption ciphers -using the GUI and it uses some older proposals by default. A user can only -change the proposals on the client side by configuring the IPSec connection -profile via PowerShell. - -We generate a connection profile used by Windows clients that will connect to -the "rw" connection on our VyOS server on the VPN servers IP address/fqdn -`vpn.vyos.net`. - -.. note:: Microsoft Windows expects the server name to be also used in the - server's certificate common name, so it's best to use this DNS name for - your VPN connection. - -.. code-block:: - - vyos@vyos:~$ generate ipsec profile windows-remote-access rw remote vpn.vyos.net - - ==== <snip> ==== - Add-VpnConnection -Name "VyOS IKEv2 VPN" -ServerAddress "vpn.vyos.net" -TunnelType "Ikev2" - Set-VpnConnectionIPsecConfiguration -ConnectionName "VyOS IKEv2 VPN" -AuthenticationTransformConstants GCMAES128 -CipherTransformConstants GCMAES128 -EncryptionMethod GCMAES128 -IntegrityCheckMethod SHA256128 -PfsGroup None -DHGroup "Group14" -PassThru -Force - ==== </snip> ==== - -As both Microsoft Windows and Apple iOS/iPadOS only support a certain set of -encryption ciphers and integrity algorithms we will validate the configured -IKE/ESP proposals and only list the compatible ones to the user — if multiple -are defined. If there are no matching proposals found — we can not generate a -profile for you. - -When first connecting to the new VPN the user is prompted to enter proper -credentials. - -Apple iOS/iPadOS (14.2+) ------------------------- - -Like on Microsoft Windows, Apple iOS/iPadOS out of the box does not expose -all available VPN options via the device GUI. - -If you want, need, and should use more advanced encryption ciphers (default -is still 3DES) you need to provision your device using a so-called "Device -Profile". A profile is a simple text file containing XML nodes with a -``.mobileconfig`` file extension that can be sent and opened on any device -from an E-Mail. - -Profile generation happens from the operational level and is as simple as -issuing the following command to create a profile to connect to the IKEv2 -access server at ``vpn.vyos.net`` with the configuration for the ``rw`` -remote-access connection group. - -.. note:: Apple iOS/iPadOS expects the server name to be also used in the - server's certificate common name, so it's best to use this DNS name for - your VPN connection. - -.. code-block:: - - vyos@vyos:~$ generate ipsec profile ios-remote-access rw remote vpn.vyos.net - - ==== <snip> ==== - <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> - <plist version="1.0"> - ... - </plist> - ==== </snip> ==== - -In the end, an XML structure is generated which can be saved as -``vyos.mobileconfig`` and sent to the device by E-Mail where it later can -be imported. - -During profile import, the user is asked to enter its IPSec credentials -(username and password) which is stored on the mobile. - -Operation Mode -============== - -.. opcmd:: show vpn ike sa - - Show all currently active IKE Security Associations. - -.. opcmd:: show vpn ike sa nat-traversal - - Show all currently active IKE Security Associations (SA) that are using - NAT Traversal. - -.. opcmd:: show vpn ike sa peer <peer_name> - - Show all currently active IKE Security Associations (SA) for a specific - peer. - -.. opcmd:: show vpn ike secrets - - Show all the configured pre-shared secret keys. - -.. opcmd:: show vpn ike status - - Show the detailed status information of IKE charon process. - -.. opcmd:: show vpn ipsec connections - - Show details of all available VPN connections - -.. opcmd:: show vpn ipsec policy - - Print out the list of existing crypto policies - -.. opcmd:: show vpn ipsec sa - - Show all active IPsec Security Associations (SA) - -.. opcmd:: show vpn ipsec sa detail - - Show a detailed information of all active IPsec Security Associations (SA) - in verbose format. - -.. opcmd:: show vpn ipsec state - - Print out the list of existing in-kernel crypto state - -.. opcmd:: show vpn ipsec status - - Show the status of running IPsec process and process ID. - -.. opcmd:: restart ipsec - - Restart the IPsec VPN process and re-establishes the connection. - -.. opcmd:: reset vpn ipsec site-to-site all - - Reset all site-to-site IPSec VPN sessions. It terminates all active - child_sa and reinitiates the connection. - -.. opcmd:: reset vpn ipsec site-to-site peer <name> - - Reset all tunnels for a given peer, can specify tunnel or vti interface. - It terminates a specific child_sa and reinitiates the connection. - -.. opcmd:: show log ipsec - - Show logs for IPsec diff --git a/docs/configuration/vpn/ipsec/index.rst b/docs/configuration/vpn/ipsec/index.rst new file mode 100644 index 00000000..e454e2f6 --- /dev/null +++ b/docs/configuration/vpn/ipsec/index.rst @@ -0,0 +1,21 @@ +##### +IPsec +##### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + ipsec_general + site2site_ipsec + remoteaccess_ipsec + troubleshooting_ipsec + +pages to sort + +.. toctree:: + :maxdepth: 1 + :includehidden: + + diff --git a/docs/configuration/vpn/ipsec/ipsec_general.rst b/docs/configuration/vpn/ipsec/ipsec_general.rst new file mode 100644 index 00000000..18d974c9 --- /dev/null +++ b/docs/configuration/vpn/ipsec/ipsec_general.rst @@ -0,0 +1,308 @@ +.. _ipsec_general: + +######################### +IPsec General Information +######################### + +*********************** +Information about IPsec +*********************** + +IPsec is the framework used to secure data. +IPsec accomplishes these goals by providing authentication, +encryption of IP network packets, key exchange, and key management. +VyOS uses Strongswan package to implement IPsec. + +**Authentication Header (AH)** is defined in :rfc:`4302`. It creates +a hash using the IP header and data payload, and prepends it to the +packet. This hash is used to validate that the data has not been +changed during transfer over the network. + +**Encapsulating Security Payload (ESP)** is defined in :rfc:`4303`. +It provides encryption and authentication of the data. + + +There are two IPsec modes: + **IPsec Transport Mode**: + In transport mode, an IPSec header (AH or ESP) is inserted + between the IP header and the upper layer protocol header. + + **IPsec Tunnel Mode:** + In tunnel mode, the original IP packet is encapsulated in + another IP datagram, and an IPsec header (AH or ESP) is + inserted between the outer and inner headers. + +.. figure:: /_static/images/ESP_AH.png + :scale: 80 % + :alt: AH and ESP in Transport Mode and Tunnel Mode + +*************************** +IKE (Internet Key Exchange) +*************************** +The default IPsec method for secure key negotiation is the Internet Key +Exchange (IKE) protocol. IKE is designed to provide mutual authentication +of systems, as well as to establish a shared secret key to create IPsec +security associations. A security association (SA) includes all relevant +attributes of the connection, including the cryptographic algorithm used, +the IPsec mode, the encryption key, and other parameters related to the +transmission of data over the VPN connection. + +IKEv1 +===== + +IKEv1 is the older version and is still used today. Nowadays, most +manufacturers recommend using IKEv2 protocol. + +IKEv1 is described in the next RFCs: :rfc:`2409` (IKE), :rfc:`3407` +(IPsec DOI), :rfc:`3947` (NAT-T), :rfc:`3948` (UDP Encapsulation +of ESP Packets), :rfc:`3706` (DPD) + +IKEv1 operates in two phases to establish these IKE and IPsec SAs: + * **Phase 1** provides mutual authentication of the IKE peers and + establishment of the session key. This phase creates an IKE SA (a + security association for IKE) using a DH exchange, cookies, and an + ID exchange. Once an IKE SA is established, all IKE communication + between the initiator and responder is protected with encryption + and an integrity check that is authenticated. The purpose of IKE + phase 1 is to facilitate a secure channel between the peers so that + phase 2 negotiations can occur securely. IKE phase 1 offers two modes: + Main and Aggressive. + + * **Main Mode** is used for site-to-site VPN connections. + + * **Aggressive Mode** is used for remote access VPN connections. + + * **Phase 2** provides for the negotiation and establishment of the + IPsec SAs using ESP or AH to protect IP data traffic. + +IKEv2 +===== + +IKEv2 is described in :rfc:`7296`. The biggest difference between IKEv1 and +IKEv2 is that IKEv2 is much simpler and more reliable than IKEv1 because +fewer messages are exchanged during the establishment of the VPN and +additional security capabilities are available. + + +IKE Authentication +================== + +VyOS supports 3 authentication methods. + * **Pre-shared keys**: In this method, both peers of the IPsec + tunnel must have the same preshared keys. + * **Digital certificates**: PKI is used in this method. + * **RSA-keys**: If the RSA-keys method is used in your IKE policy, + you need to make sure each peer has the other peer’s public keys. + +************************* +DPD (Dead Peer Detection) +************************* + +This is a mechanism used to detect when a VPN peer is no longer active. +This mechanism has different algorithms in IKEv1 and IKEv2 in VyOS. +DPD Requests are sent as ISAKMP R-U-THERE messages and DPD Responses +are sent as ISAKMP R-U-THERE-ACK messages. In IKEv1, DPD sends messages +every configured interval. The remote peer is considered unreachable +if no response to these packets is received within the DPD timeout. +In IKEv2, DPD sends messages every configured interval. If one request +is not responded, Strongswan execute its retransmission algorithm with +its timers. https://docs.strongswan.org/docs/5.9/config/retransmission.html + +***************** +Configuration IKE +***************** + +IKE (Internet Key Exchange) Attributes +====================================== + +VyOS IKE group has the next options: + +.. cfgcmd:: set vpn ipsec ike-group <name> close-action <action> + + Defines the action to take if the remote peer unexpectedly + closes a CHILD_SA: + + * **none** - Set action to none (default), + * **trap** - Installs a trap policy (IPsec policy without Security + Association) for the CHILD_SA and traffic matching these policies + will trigger acquire events that cause the daemon to establish the + required IKE/IPsec SAs. + * **start** - Tries to immediately re-create the CHILD_SA. + +.. cfgcmd:: set vpn ipsec ike-group <name> ikev2-reauth + + Whether rekeying of an IKE_SA should also reauthenticate + the peer. In IKEv1, reauthentication is always done. + Setting this parameter enables remote host re-authentication + during an IKE rekey. + +.. cfgcmd:: set vpn ipsec ike-group <name> key-exchange + + Which protocol should be used to initialize the connection + If not set both protocols are handled and connections will + use IKEv2 when initiating, but accept any protocol version + when responding: + + * **ikev1** - Use IKEv1 for Key Exchange. + * **ikev2** - Use IKEv2 for Key Exchange. + +.. cfgcmd:: set vpn ipsec ike-group <name> lifetime + + IKE lifetime in seconds <0-86400> (default 28800). + +.. cfgcmd:: set vpn ipsec ike-group <name> mode + + IKEv1 Phase 1 Mode Selection: + + * **main** - Use Main mode for Key Exchanges in the IKEv1 Protocol + (Recommended Default). + * **aggressive** - Use Aggressive mode for Key Exchanges in the IKEv1 + protocol aggressive mode is much more insecure compared to Main mode. + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> dh-group <dh-group number> + + Dh-group. Default value is **2**. + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> encryption <encryption> + + Encryption algorithm. Default value is **aes128**. + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> hash <hash> + + Hash algorithm. Default value is **sha1**. + +.. cfgcmd:: set vpn ipsec ike-group <name> proposal <number> prf <prf> + + Pseudo-random function. + + +DPD (Dead Peer Detection) Configuration +======================================= + +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection action <action> + + Action to perform for this CHILD_SA on DPD timeout. + + * **trap** - Installs a trap policy (IPsec policy without Security + Association), which will catch matching traffic and tries to + re-negotiate the tunnel on-demand. + * **clear** - Closes the CHILD_SA and does not take further action + (default). + * **restart** - Immediately tries to re-negotiate the CHILD_SA + under a fresh IKE_SA. + +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection interval <interval> + + Keep-alive interval in seconds <2-86400> (default 30). + +.. cfgcmd:: set vpn ipsec ike-group <name> dead-peer-detection timeout <timeout> + + Keep-alive timeout in seconds <2-86400> (default 120) **IKEv1 only** + +ESP (Encapsulating Security Payload) Attributes +=============================================== + +In VyOS, ESP attributes are specified through ESP groups. +Multiple proposals can be specified in a single group. + +VyOS ESP group has the next options: + +.. cfgcmd:: set vpn ipsec esp-group <name> compression + + Enables the IPComp(IP Payload Compression) protocol which allows + compressing the content of IP packets. + +.. cfgcmd:: set vpn ipsec esp-group <name> disable-rekey + + Do not locally initiate a re-key of the SA, remote peer must + re-key before expiration. + +.. cfgcmd:: set vpn ipsec esp-group <name> life-bytes <bytes> + + ESP life in bytes <1024-26843545600000>. Number of bytes + transmitted over an IPsec SA before it expires. + +.. cfgcmd:: set vpn ipsec esp-group <name> life-packets <packets> + + ESP life in packets <1000-26843545600000>. + Number of packets transmitted over an IPsec SA before it expires. + +.. cfgcmd:: set vpn ipsec esp-group <name> lifetime <timeout> + + ESP lifetime in seconds <30-86400> (default 3600). + How long a particular instance of a connection (a set of + encryption/authentication keys for user packets) should last, + from successful negotiation to expiry. + +.. cfgcmd:: set vpn ipsec esp-group <name> mode <mode> + + The type of the connection: + + * **tunnel** - Tunnel mode (default). + * **transport** - Transport mode. + +.. cfgcmd:: set vpn ipsec esp-group <name> pfs < dh-group> + + Whether Perfect Forward Secrecy of keys is desired on the + connection's keying channel and defines a Diffie-Hellman group for + PFS: + + * **enable** - Inherit Diffie-Hellman group from IKE group (default). + * **disable** - Disable PFS. + * **<dh-group>** - Defines a Diffie-Hellman group for PFS. + +.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> encryption <encryption> + + Encryption algorithm. Default value is **aes128**. + +.. cfgcmd:: set vpn ipsec esp-group <name> proposal <number> hash <hash> + + Hash algorithm. Default value is **sha1**. + +Global IPsec Settings +===================== + +.. cfgcmd:: set vpn ipsec interface <name> + + Interface name to restrict outbound IPsec policies. There is a possibility + to specify multiple interfaces. If an interfaces are not specified, IPsec + policies apply to all interfaces. + + +.. cfgcmd:: set vpn ipsec log level <number> + + Level of logging. Default value is **0**. + +.. cfgcmd:: set vpn ipsec log subsystem <name> + + Subsystem of the daemon. + +Options +======= + +.. cfgcmd:: set vpn ipsec options disable-route-autoinstall + + Do not automatically install routes to remote + networks. + +.. cfgcmd:: set vpn ipsec options flexvpn + + Allows FlexVPN vendor ID payload (IKEv2 only). Send the Cisco + FlexVPN vendor ID payload (IKEv2 only), which is required in order to make + Cisco brand devices allow negotiating a local traffic selector (from + strongSwan's point of view) that is not the assigned virtual IP address if + such an address is requested by strongSwan. Sending the Cisco FlexVPN + vendor ID prevents the peer from narrowing the initiator's local traffic + selector and allows it to e.g. negotiate a TS of 0.0.0.0/0 == 0.0.0.0/0 + instead. This has been tested with a "tunnel mode ipsec ipv4" Cisco + template but should also work for GRE encapsulation. + +.. cfgcmd:: set vpn ipsec options interface <name> + + Interface Name to use. The name of the interface on which + virtual IP addresses should be installed. If not specified the addresses + will be installed on the outbound interface. + +.. cfgcmd:: set vpn ipsec options virtual-ip + + Allows the installation of virtual-ip addresses. diff --git a/docs/configuration/vpn/remoteaccess_ipsec.rst b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst index 9bc49979..9bc49979 100644 --- a/docs/configuration/vpn/remoteaccess_ipsec.rst +++ b/docs/configuration/vpn/ipsec/remoteaccess_ipsec.rst diff --git a/docs/configuration/vpn/ipsec/site2site_ipsec.rst b/docs/configuration/vpn/ipsec/site2site_ipsec.rst new file mode 100644 index 00000000..80dfa423 --- /dev/null +++ b/docs/configuration/vpn/ipsec/site2site_ipsec.rst @@ -0,0 +1,729 @@ +.. _size2site_ipsec: + +###################### +IPsec Site-to-Site VPN +###################### + +**************************** +IPsec Site-to-Site VPN Types +**************************** + +VyOS supports two types of IPsec VPN: Policy-based IPsec VPN and Route-based +IPsec VPN. + +Policy-based VPN +================ + +Policy-based VPN is based on static configured policies. Each policy creates +individual IPSec SA. Traffic matches these SAs encrypted and directed to the +remote peer. + +Route-Based VPN +=============== + +Route-based VPN is based on secure traffic passing over Virtual Tunnel +Interfaces (VTIs). This type of IPsec VPNs allows using routing protocols. + +****************************** +Configuration Site-to-Site VPN +****************************** + +Requirements and Prerequisites for Site-to-Site VPN +=================================================== + +**Negotiated parameters that need to match** + +Phase 1 + * IKE version + * Authentication + * Encryption + * Hashing + * PRF + * Lifetime + + .. note:: Strongswan recommends to use the same lifetime value on both peers + +Phase 2 + * Encryption + * Hashing + * PFS + * Mode (tunnel or transport) + * Lifetime + + .. note:: Strongswan recommends to use the same lifetime value on both peers + + * Remote and Local networks in SA must be compatible on both peers + +Configuration Steps for Site-to-Site VPN +======================================== + +The next example shows the configuration one of the router participating in +IPsec VPN. + +Tunnel information: + * Phase 1: + * encryption: AES256 + * hash: SHA256 + * PRF: SHA256 + * DH: 14 + * lifetime: 28800 + * Phase 2: + * IPsec mode: tunnel + * encryption: AES256 + * hash: SHA256 + * PFS: inherited from DH Phase 1 + * lifetime: 3600 + * If Policy based VPN is used + * Remote network is 192.168.50.0/24. Local network is 192.168.10.0/24 + * If Route based VPN is used + * IP of the VTI interface is 10.0.0.1/30 + +.. note:: We do not recommend using policy-based vpn and route-based vpn configurations to the same peer. + +**1. Configure ike-group (IKE Phase 1)** + +.. code-block:: none + + set vpn ipsec ike-group IKE close-action 'start' + set vpn ipsec ike-group IKE key-exchange 'ikev1' + set vpn ipsec ike-group IKE lifetime '28800' + set vpn ipsec ike-group IKE proposal 10 dh-group '14' + set vpn ipsec ike-group IKE proposal 10 encryption 'aes256' + set vpn ipsec ike-group IKE proposal 10 hash 'sha256' + set vpn ipsec ike-group IKE proposal 10 prf 'prfsha256' + +**2. Configure ESP-group (IKE Phase 2)** + +.. code-block:: none + + set vpn ipsec esp-group ESP lifetime '3600' + set vpn ipsec esp-group ESP mode 'tunnel' + set vpn ipsec esp-group ESP pfs 'enable' + set vpn ipsec esp-group ESP proposal 10 encryption 'aes256' + set vpn ipsec esp-group ESP proposal 10 hash 'sha256' + +**3. Specify interface facing to the protected destination.** + +.. code-block:: none + + set vpn ipsec interface eth0 + +**4. Configure PSK keys and authentication ids for this key if authentication type is PSK** + +.. code-block:: none + + set vpn ipsec authentication psk PSK-KEY id '192.168.0.2' + set vpn ipsec authentication psk PSK-KEY id '192.168.5.2' + set vpn ipsec authentication psk PSK-KEY secret 'vyos' + +To set base64 secret encode plaintext password to base64 and set secret-type + +.. code-block:: none + + echo -n "vyos" | base64 + dnlvcw== + +.. code-block:: none + + set vpn ipsec authentication psk PSK-KEY secret 'dnlvcw==' + set vpn ipsec authentication psk PSK-KEY secret-type base64 + + +**5. Configure peer and apply IKE-group and esp-group to peer.** + +.. code-block:: none + + set vpn ipsec site-to-site peer PEER1 authentication local-id '192.168.0.2' + set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer PEER1 authentication remote-id '192.168.5.2' + set vpn ipsec site-to-site peer PEER1 connection-type 'initiate' + set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP' + set vpn ipsec site-to-site peer PEER1 ike-group 'IKE' + set vpn ipsec site-to-site peer PEER1 local-address '192.168.0.2' + set vpn ipsec site-to-site peer PEER1 remote-address '192.168.5.2' + + Peer selects the key from step 4 according to local-id/remote-id pair. + +**6. Depends to vpn type (route-based vpn or policy-based vpn).** + + **6.1 For Policy-based VPN configure SAs using tunnel command specifying remote and local networks.** + + .. code-block:: none + + set vpn ipsec site-to-site peer PEER1 tunnel 1 local prefix '192.168.10.0/24' + set vpn ipsec site-to-site peer PEER1 tunnel 1 remote prefix '192.168.50.0/24' + + **6.2 For Route-based VPN create VTI interface, set IP address to this interface and bind this interface to the vpn peer.** + + .. code-block:: none + + set interfaces vti vti1 address 10.0.0.1/30 + set vpn ipsec site-to-site peer PEER1 vti bind vti1 + set vpn ipsec options disable-route-autoinstall + + Create routing between local networks via VTI interface using dynamic or + static routing. + + .. code-block:: none + + set protocol static route 192.168.50.0/24 next-hop 10.0.0.2 + +Initiator and Responder Connection Types +======================================== + +In Site-to-Site IPsec VPN it is recommended that one peer should be an +initiator and the other - the responder. The initiator actively establishes +the VPN tunnel. The responder passively waits for the remote peer to +establish the VPN tunnel. Depends on selected role it is recommended +select proper values for close-action and DPD action. + +The result of wrong value selection can be unstable work of the VPN. + * Duplicate CHILD SA creation. + * None of the VPN sides initiates the tunnel establishment. + +Below flow-chart could be a quick reference for the close-action +combination depending on how the peer is configured. + +.. figure:: /_static/images/IPSec_close_action_settings.png + +Similar combinations are applicable for the dead-peer-detection. + +Detailed Configuration Commands +=============================== + +PSK Key Authentication +---------------------- + +.. cfgcmd:: set vpn ipsec authentication psk <name> dhcp-interface + + ID for authentication generated from DHCP address + dynamically. + +.. cfgcmd:: set vpn ipsec authentication psk id <id> + + static ID's for authentication. In general local and remote + address ``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``. + +.. cfgcmd:: set vpn ipsec authentication psk secret <secret> + + A predefined shared secret used in configured mode + ``pre-shared-secret``. Base64-encoded secrets are allowed if + `secret-type base64` is configured. + +.. cfgcmd:: set vpn ipsec authentication psk secret-type <type> + + Specifies the secret type: + + * **plaintext** - Plain text type (default value). + * **base64** - Base64 type. + +Peer Configuration +------------------ + +Peer Authentication Commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication mode <mode> + + Mode for authentication between VyOS and remote peer: + + * **pre-shared-secret** - Use predefined shared secret phrase. + * **rsa** - Use simple shared RSA key. + * **x509** - Use certificates infrastructure for authentication. + + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication local-id <id> + + ID for the local VyOS router. If defined, during the authentication + it will be send to remote peer. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication remote-id <id> + + ID for remote peer, instead of using peer name or + address. Useful in case if the remote peer is behind NAT + or if ``mode x509`` is used. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa local-key <key> + + Name of PKI key-pair with local private key. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa remote-key <key> + + Name of PKI key-pair with remote public key. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication rsa passphrase <passphrase> + + Local private key passphrase. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication use-x509-id <id> + + Use local ID from x509 certificate. Cannot be used when + ``id`` is defined. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication x509 ca-certificate <name> + + Name of CA certificate in PKI configuration. Using for authenticating + remote peer in x509 mode. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> authentication x509 certificate <name> + + Name of certificate in PKI configuration, which will be used + for authenticating local router on remote peer. + +.. cfgcmd:: set vpn ipsec authentication x509 passphrase <passphrase> + + Private key passphrase, if needed. + +Global Peer Configuration Commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> connection-type <type> + + Operational mode defines how to handle this connection process. + + * **initiate** - does initial connection to remote peer immediately + after configuring and after boot. In this mode the connection will + not be restarted in case of disconnection, therefore should be used + only together with DPD or another session tracking methods. + * **respond** - does not try to initiate a connection to a remote + peer. In this mode, the IPsec session will be established only + after initiation from a remote peer. Could be useful when there + is no direct connectivity to the peer due to firewall or NAT in + the middle of the local and remote side. + * **none** - loads the connection only, which then can be manually + initiated or used as a responder configuration. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> default-esp-group <name> + + Name of ESP group to use by default for traffic encryption. + Might be overwritten by individual settings for tunnel or VTI + interface binding. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> description <description> + + Description for this peer. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> dhcp-interface <interface> + + Specify the interface which IP address, received from DHCP for IPSec + connection with this peer, will be used as ``local-address``. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> force-udp-encapsulation + + Force encapsulation of ESP into UDP datagrams. Useful in case if + between local and remote side is firewall or NAT, which not + allows passing plain ESP packets between them. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> ike-group <name> + + Name of IKE group to use for key exchanges. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> local-address <address> + + Local IP address for IPsec connection with this peer. + If defined ``any``, then an IP address which configured on interface with + default route will be used. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> remote-address <address> + + Remote IP address or hostname for IPsec connection. IPv4 or IPv6 + address is used when a peer has a public static IP address. Hostname + is a DNS name which could be used when a peer has a public IP + address and DNS name, but an IP address could be changed from time + to time. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> replay-window <size> + + IPsec replay window to configure for CHILD_SAs + (default: 32), a value of 0 disables IPsec replay protection. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> virtual-address <address> + + Defines a virtual IP address which is requested by the initiator and + one or several IPv4 and/or IPv6 addresses are assigned from multiple + pools by the responder. The wildcard addresses 0.0.0.0 and :: + request an arbitrary address, specific addresses may be defined. + +CHILD SAs Configuration Commands +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Policy-Based CHILD SAs Configuration Commands +""""""""""""""""""""""""""""""""""""""""""""" + +Every configured tunnel under peer configuration is a new CHILD SA. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> disable + + Disable this tunnel. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> esp-group <name> + + Specify ESP group for this CHILD SA. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> priority <number> + + Priority for policy-based IPsec VPN tunnels (lowest value more + preferable). + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> protocol <name> + + Define the protocol for match traffic, which should be encrypted and + send to this peer. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> local prefix <network> + + IP network at the local side. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> local port <number> + + Local port number. Have effect only when used together with + ``prefix``. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> remote prefix <network> + + IP network at the remote side. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> tunnel <number> remote port <number> + + Remote port number. Have effect only when used together with + ``prefix``. + +Route-Based CHILD SAs Configuration Commands +""""""""""""""""""""""""""""""""""""""""""""" + +To configure route-based VPN it is enough to create vti interface and +bind it to the peer. Any traffic, which will be send to VTI interface +will be encrypted and send to this peer. Using VTI makes IPsec +configuration much flexible and easier in complex situation, and +allows to dynamically add/delete remote networks, reachable via a +peer, as in this mode router don't need to create additional SA/policy +for each remote network. + +.. warning:: When using site-to-site IPsec with VTI interfaces, + be sure to disable route autoinstall. + +.. code-block:: none + + set vpn ipsec options disable-route-autoinstall + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti bind <interface> + + VTI interface to bind to this peer. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti esp-group <name> + + ESP group for encrypt traffic, passed this VTI interface. + +Traffic-selectors parameters for traffic that should pass via vti +interface. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector local prefix <network> + + Local prefix for interesting traffic. + +.. cfgcmd:: set vpn ipsec site-to-site peer <name> vti traffic-selector remote prefix <network> + + Remote prefix for interesting traffic. + +IPsec Op-mode Commands +====================== + +.. opcmd:: show vpn ike sa + + Shows active IKE SAs information. + +.. opcmd:: show vpn ike secrets + + Shows configured authentication keys. + +.. opcmd:: show vpn ike status + + Shows Strongswan daemon status. + +.. opcmd:: show vpn ipsec connections + + Shows summary status of all configured IKE and IPsec SAs. + +.. opcmd:: show vpn ipsec sa [detail] + + Shows active IPsec SAs information. + +.. opcmd:: show vpn ipsec status + + Shows status of IPsec process. + +.. opcmd:: show vpn ipsec policy + + Shows the in-kernel crypto policies. + +.. opcmd:: show vpn ipsec state + + Shows the in-kernel crypto state. + +.. opcmd:: show log ipsec + + Shows IPsec logs. + +.. opcmd:: reset vpn ipsec site-to-site all + + Clear all ipsec connection and reinitiate them if VyOS is configured + as initiator. + +.. opcmd:: reset vpn ipsec site-to-site peer <name> + + Clear all peer IKE SAs with IPsec SAs and reinitiate them if VyOS is + configured as initiator. + +.. opcmd:: reset vpn ipsec site-to-site peer <name> tunnel <number> + + Clear scpecific IPsec SA and reinitiate it if VyOS is configured as + initiator. + +.. opcmd:: reset vpn ipsec site-to-site peer <name> vti <number> + + Clear IPsec SA which is map to vti interface of this peer and + reinitiate it if VyOS is configured as initiator. + +.. opcmd:: restart ipsec + + Restart Strongswan daemon. + +********* +Examples: +********* + +Policy-Based VPN Example +======================== + +**PEER1:** + +* WAN interface on `eth0` +* `eth0` interface IP: `10.0.1.2/30` +* `dum0` interface IP: `192.168.0.1/24` (for testing purposes) +* Initiator + +**PEER2:** + +* WAN interface on `eth0` +* `eth0` interface IP: `10.0.2.2/30` +* `dum0` interface IP: `192.168.1.0/24` (for testing purposes) +* Responder + +.. code-block:: none + + # PEER1 + set interfaces dummy dum0 address '192.168.0.1/32' + set interfaces ethernet eth0 address '10.0.1.2/30' + set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 + set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' + set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' + set vpn ipsec authentication psk AUTH-PSK secret 'test' + set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' + set vpn ipsec ike-group IKE-GROUP close-action 'start' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' + set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' + set vpn ipsec ike-group IKE-GROUP lifetime '28800' + set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' + set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' + set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' + set vpn ipsec interface 'eth0' + set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' + set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' + set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' + set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' + set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' + set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' + set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' + set vpn ipsec site-to-site peer PEER2 tunnel 0 local prefix '192.168.0.0/24' + set vpn ipsec site-to-site peer PEER2 tunnel 0 remote prefix '192.168.1.0/24' + + + # PEER2 + set interfaces dummy dum0 address '192.168.1.1/32' + set interfaces ethernet eth0 address '10.0.2.2/30' + set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 + set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' + set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' + set vpn ipsec authentication psk AUTH-PSK secret 'test' + set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' + set vpn ipsec ike-group IKE-GROUP close-action 'none' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection timeout '120' + set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev1' + set vpn ipsec ike-group IKE-GROUP lifetime '28800' + set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' + set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' + set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' + set vpn ipsec interface 'eth0' + set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' + set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' + set vpn ipsec site-to-site peer PEER1 connection-type 'respond' + set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' + set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' + set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' + set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' + set vpn ipsec site-to-site peer PEER1 tunnel 0 local prefix '192.168.1.0/24' + set vpn ipsec site-to-site peer PEER1 tunnel 0 remote prefix '192.168.0.0/24' + + +Show status of policy-based IPsec VPN setup: + +.. code-block:: none + + vyos@PEER2:~$ show vpn ike sa + Peer ID / IP Local ID / IP + ------------ ------------- + 10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv1 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 1254 25633 + + + vyos@srv-gw0:~$ show vpn ipsec sa + Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal + -------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- + PEER1-tunnel-0 up 20m42s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + + vyos@PEER2:~$ show vpn ipsec connections + Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal + -------------- ------- ------ ---------------- -------------- -------------- ---------- ----------- ---------------------------------- + PEER1 up IKEv1 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 + PEER1-tunnel-0 up IPsec 10.0.1.2 192.168.1.0/24 192.168.0.0/24 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 + +If there is SNAT rules on eth0, need to add exclude rule + +.. code-block:: none + + # PEER1 side + set nat source rule 10 destination address '192.168.1.0/24' + set nat source rule 10 'exclude' + set nat source rule 10 outbound-interface name 'eth0' + set nat source rule 10 source address '192.168.0.0/24' + + # PEER2 side + set nat source rule 10 destination address '192.168.0.0/24' + set nat source rule 10 'exclude' + set nat source rule 10 outbound-interface name 'eth0' + set nat source rule 10 source address '192.168.1.0/24' + + +Route-Based VPN Example +======================= + +**PEER1:** + +* WAN interface on `eth0` +* `eth0` interface IP: `10.0.1.2/30` +* 'vti0' interface IP: `10.100.100.1/30` +* `dum0` interface IP: `192.168.0.1/24` (for testing purposes) +* Role: Initiator + +**PEER2:** + +* WAN interface on `eth0` +* `eth0` interface IP: `10.0.2.2/30` +* 'vti0' interface IP: `10.100.100.2/30` +* `dum0` interface IP: `192.168.1.0/24` (for testing purposes) +* Role: Responder + +.. code-block:: none + + # PEER1 + set interfaces dummy dum0 address '192.168.0.1/32' + set interfaces ethernet eth0 address '10.0.1.2/30' + set interfaces vti vti0 address '10.100.100.1/30' + set protocols static route 0.0.0.0/0 next-hop 10.0.1.1 + set protocols static route 192.168.1.0/24 next-hop 10.100.100.2 + set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' + set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' + set vpn ipsec authentication psk AUTH-PSK secret 'test' + set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' + set vpn ipsec ike-group IKE-GROUP close-action 'start' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'restart' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' + set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' + set vpn ipsec ike-group IKE-GROUP lifetime '28800' + set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' + set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' + set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' + set vpn ipsec interface 'eth0' + set vpn ipsec options disable-route-autoinstall + set vpn ipsec site-to-site peer PEER2 authentication local-id '10.0.1.2' + set vpn ipsec site-to-site peer PEER2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer PEER2 authentication remote-id '10.0.2.2' + set vpn ipsec site-to-site peer PEER2 connection-type 'initiate' + set vpn ipsec site-to-site peer PEER2 default-esp-group 'ESP-GRPOUP' + set vpn ipsec site-to-site peer PEER2 ike-group 'IKE-GROUP' + set vpn ipsec site-to-site peer PEER2 local-address '10.0.1.2' + set vpn ipsec site-to-site peer PEER2 remote-address '10.0.2.2' + set vpn ipsec site-to-site peer PEER2 vti bind 'vti0' + + + # PEER2 + set interfaces dummy dum0 address '192.168.1.1/32' + set interfaces ethernet eth0 address '10.0.2.2/30' + set interfaces vti vti0 address '10.100.100.2/30' + set protocols static route 0.0.0.0/0 next-hop 10.0.2.1 + set protocols static route 192.168.0.0/24 next-hop 10.100.100.1 + set vpn ipsec authentication psk AUTH-PSK id '10.0.1.2' + set vpn ipsec authentication psk AUTH-PSK id '10.0.2.2' + set vpn ipsec authentication psk AUTH-PSK secret 'test' + set vpn ipsec esp-group ESP-GRPOUP lifetime '3600' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 encryption 'aes256' + set vpn ipsec esp-group ESP-GRPOUP proposal 10 hash 'sha1' + set vpn ipsec ike-group IKE-GROUP close-action 'none' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection action 'clear' + set vpn ipsec ike-group IKE-GROUP dead-peer-detection interval '30' + set vpn ipsec ike-group IKE-GROUP key-exchange 'ikev2' + set vpn ipsec ike-group IKE-GROUP lifetime '28800' + set vpn ipsec ike-group IKE-GROUP proposal 10 dh-group '14' + set vpn ipsec ike-group IKE-GROUP proposal 10 encryption 'aes256' + set vpn ipsec ike-group IKE-GROUP proposal 10 hash 'sha1' + set vpn ipsec interface 'eth0' + set vpn ipsec options disable-route-autoinstall + set vpn ipsec site-to-site peer PEER1 authentication local-id '10.0.2.2' + set vpn ipsec site-to-site peer PEER1 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer PEER1 authentication remote-id '10.0.1.2' + set vpn ipsec site-to-site peer PEER1 connection-type 'respond' + set vpn ipsec site-to-site peer PEER1 default-esp-group 'ESP-GRPOUP' + set vpn ipsec site-to-site peer PEER1 ike-group 'IKE-GROUP' + set vpn ipsec site-to-site peer PEER1 local-address '10.0.2.2' + set vpn ipsec site-to-site peer PEER1 remote-address '10.0.1.2' + set vpn ipsec site-to-site peer PEER1 vti bind 'vti0' + +Show status of route-based IPsec VPN setup: + +.. code-block:: none + + vyos@PEER2:~$ show vpn ike sa + Peer ID / IP Local ID / IP + ------------ ------------- + 10.0.1.2 10.0.1.2 10.0.2.2 10.0.2.2 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_256 HMAC_SHA1_96 MODP_2048 no 404 27650 + + vyos@PEER2:~$ show vpn ipsec sa + Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal + ------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- + PEER1-vti up 3m28s 0B/0B 0/0 10.0.1.2 10.0.1.2 AES_CBC_256/HMAC_SHA1_96/MODP_2048 + + vyos@PEER2:~$ show vpn ipsec connections + Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal + ------------ ------- ------ ---------------- ---------- ----------- ---------- ----------- ---------------------------------- + PEER1 up IKEv2 10.0.1.2 - - 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 + PEER1-vti up IPsec 10.0.1.2 0.0.0.0/0 0.0.0.0/0 10.0.2.2 10.0.1.2 AES_CBC/256/HMAC_SHA1_96/MODP_2048 + ::/0 ::/0 diff --git a/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst new file mode 100644 index 00000000..fdeb347d --- /dev/null +++ b/docs/configuration/vpn/ipsec/troubleshooting_ipsec.rst @@ -0,0 +1,323 @@ +.. _troubleshooting_ipsec: + +###################################### +Troubleshooting Site-to-Site VPN IPsec +###################################### + +************ +Introduction +************ + +This document describes the methodology to monitor and troubleshoot +Site-to-Site VPN IPsec. + +Steps for troubleshooting problems with Site-to-Site VPN IPsec: + 1. Ping the remote site through the tunnel using the source and + destination IPs included in the policy. + 2. Check connectivity between the routers using the ping command + (if ICMP traffic is allowed). + 3. Check the IKE SAs' statuses. + 4. Check the IPsec SAs' statuses. + 5. Check logs to view debug messages. + +********************** +Checking IKE SA Status +********************** + +The next command shows IKE SAs' statuses. + +.. code-block:: none + + vyos@vyos:~$ show vpn ike sa + + Peer ID / IP Local ID / IP + ------------ ------------- + 192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 162 27023 + +This command shows the next information: + - IKE SA status. + - Selected IKE version. + - Selected Encryption, Hash and Diffie-Hellman Group. + - NAT-T. + - ID and IP of both peers. + - A-Time: established time, L-Time: time for next rekeying. + +************************** +IPsec SA (CHILD SA) Status +************************** + +The next commands show IPsec SAs' statuses. + +.. code-block:: none + + vyos@vyos:~$ show vpn ipsec sa + Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal + ------------- ------- -------- -------------- ---------------- ---------------- ----------- ---------------------------------- + PEER-tunnel-1 up 16m30s 168B/168B 2/2 192.168.1.2 192.168.1.2 AES_CBC_128/HMAC_SHA1_96/MODP_2048 + +.. code-block:: none + + vyos@vyos:~$ show vpn ipsec sa detail + PEER: #1, ESTABLISHED, IKEv2, 101275ac719d5a1b_i* 68ea4ec3bed3bf0c_r + local '192.168.0.1' @ 192.168.0.1[4500] + remote '192.168.1.2' @ 192.168.1.2[4500] + AES_CBC-128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + established 4054s ago, rekeying in 23131s + PEER-tunnel-1: #2, reqid 1, INSTALLED, TUNNEL, ESP:AES_CBC-128/HMAC_SHA1_96/MODP_2048 + installed 1065s ago, rekeying in 1998s, expires in 2535s + in c5821882, 168 bytes, 2 packets, 81s ago + out c433406a, 168 bytes, 2 packets, 81s ago + local 10.0.0.0/24 + remote 10.0.1.0/24 + +These commands show the next information: + - IPsec SA status. + - Uptime and time for the next rekeing. + - Amount of transferred data. + - Remote and local ID and IP. + - Selected Encryption, Hash and Diffie-Hellman Group. + - Mode (tunnel or transport). + - Remote and local prefixes which are use for policy. + +There is a possibility to view the summarized information of SAs' status + +.. code-block:: none + + vyos@vyos:~$ show vpn ipsec connections + Connection State Type Remote address Local TS Remote TS Local id Remote id Proposal + ------------- ------- ------ ---------------- ----------- ----------- ----------- ----------- ---------------------------------- + PEER up IKEv2 192.168.1.2 - - 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 + PEER-tunnel-1 up IPsec 192.168.1.2 10.0.0.0/24 10.0.1.0/24 192.168.0.1 192.168.1.2 AES_CBC/128/HMAC_SHA1_96/MODP_2048 + +************************** +Viewing Logs for Debugging +************************** + +If IKE SAs or IPsec SAs are down, need to debug IPsec connectivity +using logs ``show log ipsec`` + +The next example of the successful IPsec connection initialization. + +.. code-block:: none + + vyos@vyos:~$ show log ipsec + Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) + Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] + Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) + Jun 20 14:29:47 charon[2428]: 02[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] + Jun 20 14:29:47 charon-systemd[2428]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key + Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.0.1' (myself) with pre-shared key + Jun 20 14:29:47 charon[2428]: 02[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} + Jun 20 14:29:47 charon-systemd[2428]: establishing CHILD_SA PEER-tunnel-1{1} + Jun 20 14:29:47 charon[2428]: 02[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] + Jun 20 14:29:47 charon-systemd[2428]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] + Jun 20 14:29:47 charon[2428]: 02[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) + Jun 20 14:29:47 charon-systemd[2428]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) + Jun 20 14:29:47 charon[2428]: 13[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) + Jun 20 14:29:47 charon[2428]: 13[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] + Jun 20 14:29:47 charon-systemd[2428]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (220 bytes) + Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful + Jun 20 14:29:47 charon-systemd[2428]: parsed IKE_AUTH response 1 [ IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) ] + Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> peer supports MOBIKE + Jun 20 14:29:47 charon-systemd[2428]: authentication of '192.168.1.2' with pre-shared key successful + Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] + Jun 20 14:29:47 charon-systemd[2428]: peer supports MOBIKE + Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> scheduling rekeying in 27703s + Jun 20 14:29:47 charon-systemd[2428]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] + Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> maximum IKE_SA lifetime 30583s + Jun 20 14:29:47 charon-systemd[2428]: scheduling rekeying in 27703s + Jun 20 14:29:47 charon[2428]: 13[CFG] <PEER|1> selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ + Jun 20 14:29:47 charon-systemd[2428]: maximum IKE_SA lifetime 30583s + Jun 20 14:29:47 charon-systemd[2428]: selected proposal: ESP:AES_CBC_128/HMAC_SHA1_96/NO_EXT_SEQ + Jun 20 14:29:47 charon[2428]: 13[IKE] <PEER|1> CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 + Jun 20 14:29:47 charon-systemd[2428]: CHILD_SA PEER-tunnel-1{1} established with SPIs cb94fb3f_i ca99c8a9_o and TS 10.0.0.0/24 === 10.0.1.0/24 + +************************ +Troubleshooting Examples +************************ + +IKE PROPOSAL are Different +========================== + +In this situation, IKE SAs can be down or not active. + +.. code-block:: none + + vyos@vyos:~$ show vpn ike sa + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder Side: + +.. code-block:: none + + Jun 23 07:36:33 charon[2440]: 01[CFG] <1> received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 23 07:36:33 charon-systemd[2440]: received proposals: IKE:AES_CBC_256/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 23 07:36:33 charon[2440]: 01[CFG] <1> configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 23 07:36:33 charon-systemd[2440]: configured proposals: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 23 07:36:33 charon[2440]: 01[IKE] <1> received proposals unacceptable + Jun 23 07:36:33 charon-systemd[2440]: received proposals unacceptable + Jun 23 07:36:33 charon[2440]: 01[ENC] <1> generating IKE_SA_INIT response 0 [ N(NO_PROP) ] + +Initiator side: + +.. code-block:: none + + Jun 23 07:36:32 charon-systemd[2444]: parsed IKE_SA_INIT response 0 [ N(NO_PROP) ] + Jun 23 07:36:32 charon[2444]: 14[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify error + Jun 23 07:36:32 charon-systemd[2444]: received NO_PROPOSAL_CHOSEN notify error + +The notification **NO_PROPOSAL_CHOSEN** means that the proposal mismatch. +On the Responder side there is concrete information where is mismatch. +Encryption **AES_CBC_128** is configured in IKE policy on the responder +but **AES_CBC_256** is configured on the initiator side. + +PSK Secret Mismatch +=================== + +In this situation, IKE SAs can be down or not active. + +.. code-block:: none + + vyos@vyos:~$ show vpn ike sa + +The problem is in IKE phase (Phase 1). The next step is checking debug logs. + +Responder: + +.. code-block:: none + + Jun 23 08:07:26 charon-systemd[2440]: tried 1 shared key for '192.168.1.2' - '192.168.0.1', but MAC mismatched + Jun 23 08:07:26 charon[2440]: 13[ENC] <PEER|3> generating IKE_AUTH response 1 [ N(AUTH_FAILED) ] + +Initiator side: + +.. code-block:: none + + Jun 23 08:07:24 charon[2436]: 12[ENC] <PEER|1> parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] + Jun 23 08:07:24 charon-systemd[2436]: parsed IKE_AUTH response 1 [ N(AUTH_FAILED) ] + Jun 23 08:07:24 charon[2436]: 12[IKE] <PEER|1> received AUTHENTICATION_FAILED notify error + Jun 23 08:07:24 charon-systemd[2436]: received AUTHENTICATION_FAILED notify error + +The notification **AUTHENTICATION_FAILED** means that the authentication +is failed. There is a reason to check PSK on both side. + +ESP Proposal Mismatch +===================== + +The output of **show** commands shows us that IKE SA is established but +IPSec SA is not. + +.. code-block:: none + + vyos@vyos:~$ show vpn ike sa + Peer ID / IP Local ID / IP + ------------ ------------- + 192.168.1.2 192.168.1.2 192.168.0.1 192.168.0.1 + + State IKEVer Encrypt Hash D-H Group NAT-T A-Time L-Time + ----- ------ ------- ---- --------- ----- ------ ------ + up IKEv2 AES_CBC_128 HMAC_SHA1_96 MODP_2048 no 158 26817 + +.. code-block:: none + + vyos@vyos:~$ show vpn ipsec sa + Connection State Uptime Bytes In/Out Packets In/Out Remote address Remote ID Proposal + ------------ ------- -------- -------------- ---------------- ---------------- ----------- ---------- + +The next step is checking debug logs. + +Initiator side: + +.. code-block:: none + + Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) + Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] + Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[500] to 192.168.0.1[500] (472 bytes) + Jun 23 08:16:10 charon[3789]: 13[CFG] <PEER|1> selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_SA_INIT response 0 [ SA KE No N(NATD_S_IP) N(NATD_D_IP) N(FRAG_SUP) N(HASH_ALG) N(CHDLESS_SUP) N(MULT_AUTH) ] + Jun 23 08:16:10 charon-systemd[3789]: selected proposal: IKE:AES_CBC_128/HMAC_SHA1_96/PRF_HMAC_SHA1/MODP_2048 + Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> authentication of '192.168.0.1' (myself) with pre-shared key + Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.0.1' (myself) with pre-shared key + Jun 23 08:16:10 charon[3789]: 13[IKE] <PEER|1> establishing CHILD_SA PEER-tunnel-1{1} + Jun 23 08:16:10 charon-systemd[3789]: establishing CHILD_SA PEER-tunnel-1{1} + Jun 23 08:16:10 charon[3789]: 13[ENC] <PEER|1> generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] + Jun 23 08:16:10 charon-systemd[3789]: generating IKE_AUTH request 1 [ IDi N(INIT_CONTACT) IDr AUTH SA TSi TSr N(MOBIKE_SUP) N(NO_ADD_ADDR) N(MULT_AUTH) N(EAP_ONLY) N(MSG_ID_SYN_SUP) ] + Jun 23 08:16:10 charon[3789]: 13[NET] <PEER|1> sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) + Jun 23 08:16:10 charon-systemd[3789]: sending packet: from 192.168.0.1[4500] to 192.168.1.2[4500] (268 bytes) + Jun 23 08:16:10 charon[3789]: 09[NET] <PEER|1> received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) + Jun 23 08:16:10 charon-systemd[3789]: received packet: from 192.168.1.2[4500] to 192.168.0.1[4500] (140 bytes) + Jun 23 08:16:10 charon[3789]: 09[ENC] <PEER|1> parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] + Jun 23 08:16:10 charon-systemd[3789]: parsed IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(NO_PROP) ] + Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> authentication of '192.168.1.2' with pre-shared key successful + Jun 23 08:16:10 charon-systemd[3789]: authentication of '192.168.1.2' with pre-shared key successful + Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> peer supports MOBIKE + Jun 23 08:16:10 charon-systemd[3789]: peer supports MOBIKE + Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] + Jun 23 08:16:10 charon-systemd[3789]: IKE_SA PEER[1] established between 192.168.0.1[192.168.0.1]...192.168.1.2[192.168.1.2] + Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> scheduling rekeying in 26975s + Jun 23 08:16:10 charon-systemd[3789]: scheduling rekeying in 26975s + Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> maximum IKE_SA lifetime 29855s + Jun 23 08:16:10 charon-systemd[3789]: maximum IKE_SA lifetime 29855s + Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built + Jun 23 08:16:10 charon-systemd[3789]: received NO_PROPOSAL_CHOSEN notify, no CHILD_SA built + Jun 23 08:16:10 charon[3789]: 09[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA + Jun 23 08:16:10 charon-systemd[3789]: failed to establish CHILD_SA, keeping IKE_SA + +There are messages: **NO_PROPOSAL_CHOSEN** and +**failed to establish CHILD_SA** which refers that the problem is in +the IPsec(ESP) proposal mismatch. + +The reason of this problem is showed on the responder side. + +.. code-block:: none + + Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ + Jun 23 08:16:12 charon-systemd[2440]: received proposals: ESP:AES_CBC_256/HMAC_SHA1_96/NO_EXT_SEQ + Jun 23 08:16:12 charon[2440]: 01[CFG] <PEER|5> configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ + Jun 23 08:16:12 charon-systemd[2440]: configured proposals: ESP:AES_CBC_128/HMAC_SHA1_96/MODP_2048/NO_EXT_SEQ + Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> no acceptable proposal found + Jun 23 08:16:12 charon-systemd[2440]: no acceptable proposal found + Jun 23 08:16:12 charon[2440]: 01[IKE] <PEER|5> failed to establish CHILD_SA, keeping IKE_SA + +Encryption **AES_CBC_128** is configured in IKE policy on the responder but **AES_CBC_256** +is configured on the initiator side. + +Prefixes in Policies Mismatch +============================= + +As in previous situation, IKE SA is in up state but IPsec SA is not up. +According to logs we can see **TS_UNACCEPTABLE** notification. It means +that prefixes (traffic selectors) mismatch on both sides + +Initiator: + +.. code-block:: none + + Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> received TS_UNACCEPTABLE notify, no CHILD_SA built + Jun 23 14:13:17 charon-systemd[4996]: maximum IKE_SA lifetime 29437s + Jun 23 14:13:17 charon[4996]: 11[IKE] <PEER|1> failed to establish CHILD_SA, keeping IKE_SA + Jun 23 14:13:17 charon-systemd[4996]: received TS_UNACCEPTABLE notify, no CHILD_SA built + Jun 23 14:13:17 charon-systemd[4996]: failed to establish CHILD_SA, keeping IKE_SA + +The reason of this problem is showed on the responder side. + +.. code-block:: none + + Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable + Jun 23 14:13:19 charon-systemd[2440]: traffic selectors 10.0.2.0/24 === 10.0.0.0/24 unacceptable + Jun 23 14:13:19 charon[2440]: 01[IKE] <PEER|7> failed to establish CHILD_SA, keeping IKE_SA + Jun 23 14:13:19 charon-systemd[2440]: failed to establish CHILD_SA, keeping IKE_SA + Jun 23 14:13:19 charon[2440]: 01[ENC] <PEER|7> generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] + Jun 23 14:13:19 charon-systemd[2440]: generating IKE_AUTH response 1 [ IDr AUTH N(MOBIKE_SUP) N(NO_ADD_ADDR) N(TS_UNACCEPT) ] + +Traffic selectors **10.0.2.0/24 === 10.0.0.0/24** are unacceptable on the +responder side. + + diff --git a/docs/configuration/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index d2215c1c..7fdf8599 100644 --- a/docs/configuration/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst @@ -92,18 +92,18 @@ Example: .. code-block:: none - set firewall name OUTSIDE-LOCAL rule 40 action 'accept' - set firewall name OUTSIDE-LOCAL rule 40 protocol 'esp' - set firewall name OUTSIDE-LOCAL rule 41 action 'accept' - set firewall name OUTSIDE-LOCAL rule 41 destination port '500' - set firewall name OUTSIDE-LOCAL rule 41 protocol 'udp' - set firewall name OUTSIDE-LOCAL rule 42 action 'accept' - set firewall name OUTSIDE-LOCAL rule 42 destination port '4500' - set firewall name OUTSIDE-LOCAL rule 42 protocol 'udp' - set firewall name OUTSIDE-LOCAL rule 43 action 'accept' - set firewall name OUTSIDE-LOCAL rule 43 destination port '1701' - set firewall name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' - set firewall name OUTSIDE-LOCAL rule 43 protocol 'udp' + set firewall ipv4 name OUTSIDE-LOCAL rule 40 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 40 protocol 'esp' + set firewall ipv4 name OUTSIDE-LOCAL rule 41 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 41 destination port '500' + set firewall ipv4 name OUTSIDE-LOCAL rule 41 protocol 'udp' + set firewall ipv4 name OUTSIDE-LOCAL rule 42 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 42 destination port '4500' + set firewall ipv4 name OUTSIDE-LOCAL rule 42 protocol 'udp' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 action 'accept' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 destination port '1701' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 ipsec 'match-ipsec' + set firewall ipv4 name OUTSIDE-LOCAL rule 43 protocol 'udp' To allow VPN-clients access via your external address, a NAT rule is required: @@ -180,11 +180,12 @@ RADIUS advanced options .. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author server <address> - Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + Specifies IP address for Dynamic Authorization Extension server (DM/CoA). + This IP must exist on any VyOS interface or it can be ``0.0.0.0``. .. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author port <port> - Port for Dynamic Authorization Extension server (DM/CoA) + UDP port for Dynamic Authorization Extension server (DM/CoA) .. cfgcmd:: set vpn l2tp remote-access authentication radius dynamic-author key <secret> diff --git a/docs/configuration/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst index 5220929f..194ec771 100644 --- a/docs/configuration/vpn/pptp.rst +++ b/docs/configuration/vpn/pptp.rst @@ -120,11 +120,12 @@ RADIUS advanced options .. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author server <address> - Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + Specifies IP address for Dynamic Authorization Extension server (DM/CoA). + This IP must exist on any VyOS interface or it can be ``0.0.0.0``. .. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author port <port> - Port for Dynamic Authorization Extension server (DM/CoA) + UDP port for Dynamic Authorization Extension server (DM/CoA) .. cfgcmd:: set vpn pptp remote-access authentication radius dynamic-author key <secret> diff --git a/docs/configuration/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst deleted file mode 100644 index 400aff29..00000000 --- a/docs/configuration/vpn/site2site_ipsec.rst +++ /dev/null @@ -1,433 +0,0 @@ -.. _size2site_ipsec: - -Site-to-Site -============ - -Site-to-site mode provides a way to add remote peers, which could be configured -to exchange encrypted information between them and VyOS itself or -connected/routed networks. - -To configure site-to-site connection you need to add peers with the -``set vpn ipsec site-to-site peer <name>`` command. - -The peer name must be an alphanumeric and can have hypen or underscore as -special characters. It is purely informational. - -Each site-to-site peer has the next options: - -* ``authentication`` - configure authentication between VyOS and a remote peer. - If pre-shared-secret mode is used, the secret key must be defined in - ``set vpn ipsec authentication`` and suboptions: - - * ``psk`` - Preshared secret key name: - - * ``dhcp-interface`` - ID for authentication generated from DHCP address - dynamically; - * ``id`` - static ID's for authentication. In general local and remote - address ``<x.x.x.x>``, ``<h:h:h:h:h:h:h:h>`` or ``%any``; - * ``secret`` - a predefined shared secret used in configured mode - ``pre-shared-secret``. Base64-encoded secrets are allowed if - `secret-type base64` is configured; - * ``secret-type`` - specifies the secret type, either ``plaintext`` or - ``base64``. Default to ``plaintext``; - - - * ``local-id`` - ID for the local VyOS router. If defined, during the - authentication - it will be send to remote peer; - - * ``mode`` - mode for authentication between VyOS and remote peer: - - * ``pre-shared-secret`` - use predefined shared secret phrase; - - * ``rsa`` - use simple shared RSA key. - - * ``x509`` - use certificates infrastructure for authentication. - - * ``remote-id`` - define an ID for remote peer, instead of using peer name or - address. Useful in case if the remote peer is behind NAT or if ``mode x509`` - is used; - - * ``rsa`` - options for RSA authentication mode: - - * ``local-key`` - name of PKI key-pair with local private key - - * ``remote-key`` - name of PKI key-pair with remote public key - - * ``passphrase`` - local private key passphrase - - * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when - ``id`` is defined; - - * ``x509`` - options for x509 authentication mode: - - * ``ca-certificate`` - CA certificate in PKI configuration. Using for - authenticating remote peer; - - * ``certificate`` - certificate file in PKI configuration, which will be used - for authenticating local router on remote peer; - - * ``passphrase`` - private key passphrase, if needed. - -* ``connection-type`` - how to handle this connection process. Possible - variants: - - * ``initiate`` - does initial connection to remote peer immediately after - configuring and after boot. In this mode the connection will not be restarted - in case of disconnection, therefore should be used only together with DPD or - another session tracking methods; - - * ``respond`` - does not try to initiate a connection to a remote peer. In this - mode, the IPSec session will be established only after initiation from a - remote peer. Could be useful when there is no direct connectivity to the - peer due to firewall or NAT in the middle of the local and remote side. - - * ``none`` - loads the connection only, which then can be manually initiated or - used as a responder configuration. - -* ``default-esp-group`` - ESP group to use by default for traffic encryption. - Might be overwritten by individual settings for tunnel or VTI interface - binding; - -* ``description`` - description for this peer; - -* ``dhcp-interface`` - use an IP address, received from DHCP for IPSec - connection with this peer, instead of ``local-address``; - -* ``force-udp-encapsulation`` - force encapsulation of ESP into UDP datagrams. - Useful in case if between local and remote side is firewall or NAT, which not - allows passing plain ESP packets between them; - -* ``ike-group`` - IKE group to use for key exchanges; - -* ``ikev2-reauth`` - reauthenticate remote peer during the rekeying process. - Can be used only with IKEv2. - Create a new IKE_SA from the scratch and try to recreate all IPsec SAs; - -* ``local-address`` - local IP address for IPSec connection with this peer. - If defined ``any``, then an IP address which configured on interface with - default route will be used; - -* ``remote-address`` - remote IP address or hostname for IPSec connection. - IPv4 or IPv6 address is used when a peer has a public static IP address. - Hostname is a DNS name which could be used when a peer has a public IP - address and DNS name, but an IP address could be changed from time to time. - -* ``replay-window`` - IPsec replay window to configure for this CHILD_SA - (default: 32), a value of 0 disables IPsec replay protection - -* ``tunnel`` - define criteria for traffic to be matched for encrypting and send - it to a peer: - - * ``disable`` - disable this tunnel; - - * ``esp-group`` - define ESP group for encrypt traffic, defined by this tunnel; - - * ``local`` - define a local source for match traffic, which should be - encrypted and send to this peer: - - * ``port`` - define port. Have effect only when used together with ``prefix``; - - * ``prefix`` - IP network at local side. - - * ``priority`` - Add priority for policy-based IPSec VPN tunnels(lowest value - more preferable) - - * ``protocol`` - define the protocol for match traffic, which should be - encrypted and send to this peer; - - * ``remote`` - define the remote destination for match traffic, which should be - encrypted and send to this peer: - - * ``port`` - define port. Have effect only when used together with ``prefix``; - - * ``prefix`` - IP network at remote side. - -* ``vti`` - use a VTI interface for traffic encryption. Any traffic, which will - be send to VTI interface will be encrypted and send to this peer. Using VTI - makes IPSec configuration much flexible and easier in complex situation, and - allows to dynamically add/delete remote networks, reachable via a peer, as in - this mode router don't need to create additional SA/policy for each remote - network: - - * ``bind`` - select a VTI interface to bind to this peer; - - * ``esp-group`` - define ESP group for encrypt traffic, passed this VTI - interface. - -* ``virtual-address`` - Defines a virtual IP address which is requested by the - initiator and one or several IPv4 and/or IPv6 addresses are assigned from - multiple pools by the responder. - -Examples: ------------------- - -IKEv1 -^^^^^ - -Example: - -* WAN interface on `eth1` -* left subnet: `192.168.0.0/24` site1, server side (i.e. locality, actually - there is no client or server roles) -* left local_ip: `198.51.100.3` # server side WAN IP -* right subnet: `10.0.0.0/24` site2,remote office side -* right local_ip: `203.0.113.2` # remote office side WAN IP - -.. code-block:: none - - # server config - set vpn ipsec authentication psk OFFICE-B id '198.51.100.3' - set vpn ipsec authentication psk OFFICE-B id '203.0.113.2' - set vpn ipsec authentication psk OFFICE-B secret 'SomePreSharedKey' - set vpn ipsec esp-group office-srv-esp lifetime '1800' - set vpn ipsec esp-group office-srv-esp mode 'tunnel' - set vpn ipsec esp-group office-srv-esp pfs 'enable' - set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' - set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' - set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' - set vpn ipsec ike-group office-srv-ike lifetime '3600' - set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' - set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' - set vpn ipsec interface 'eth1' - set vpn ipsec site-to-site peer OFFICE-B authentication local-id '198.51.100.3' - set vpn ipsec site-to-site peer OFFICE-B authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer OFFICE-B authentication remote-id '203.0.113.2' - set vpn ipsec site-to-site peer OFFICE-B ike-group 'office-srv-ike' - set vpn ipsec site-to-site peer OFFICE-B local-address '198.51.100.3' - set vpn ipsec site-to-site peer OFFICE-B remote-address '203.0.113.2' - set vpn ipsec site-to-site peer OFFICE-B tunnel 0 esp-group 'office-srv-esp' - set vpn ipsec site-to-site peer OFFICE-B tunnel 0 local prefix '192.168.0.0/24' - set vpn ipsec site-to-site peer OFFICE-B tunnel 0 remote prefix '10.0.0.0/21' - - # remote office config - set vpn ipsec authentication psk OFFICE-A id '198.51.100.3' - set vpn ipsec authentication psk OFFICE-A id '203.0.113.2' - set vpn ipsec authentication psk OFFICE-A secret 'SomePreSharedKey' - set vpn ipsec esp-group office-srv-esp lifetime '1800' - set vpn ipsec esp-group office-srv-esp mode 'tunnel' - set vpn ipsec esp-group office-srv-esp pfs 'enable' - set vpn ipsec esp-group office-srv-esp proposal 1 encryption 'aes256' - set vpn ipsec esp-group office-srv-esp proposal 1 hash 'sha1' - set vpn ipsec ike-group office-srv-ike key-exchange 'ikev1' - set vpn ipsec ike-group office-srv-ike lifetime '3600' - set vpn ipsec ike-group office-srv-ike proposal 1 encryption 'aes256' - set vpn ipsec ike-group office-srv-ike proposal 1 hash 'sha1' - set vpn ipsec interface 'eth1' - set vpn ipsec site-to-site peer OFFICE-A authentication local-id '203.0.113.2' - set vpn ipsec site-to-site peer OFFICE-A authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer OFFICE-A authentication remote-id '198.51.100.3' - set vpn ipsec site-to-site peer OFFICE-A ike-group 'office-srv-ike' - set vpn ipsec site-to-site peer OFFICE-A local-address '203.0.113.2' - set vpn ipsec site-to-site peer OFFICE-A remote-address '198.51.100.3' - set vpn ipsec site-to-site peer OFFICE-A tunnel 0 esp-group 'office-srv-esp' - set vpn ipsec site-to-site peer OFFICE-A tunnel 0 local prefix '10.0.0.0/21' - set vpn ipsec site-to-site peer OFFICE-A tunnel 0 remote prefix '192.168.0.0/24' - -Show status of new setup: - -.. code-block:: none - - vyos@srv-gw0:~$ show vpn ike sa - Peer ID / IP Local ID / IP - ------------ ------------- - 203.0.113.2 198.51.100.3 - State Encrypt Hash D-H Grp NAT-T A-Time L-Time - ----- ------- ---- ------- ----- ------ ------ - up aes256 sha1 5 no 734 3600 - - vyos@srv-gw0:~$ show vpn ipsec sa - Peer ID / IP Local ID / IP - ------------ ------------- - 203.0.113.2 198.51.100.3 - Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto - ------ ----- ------------- ------- ---- ----- ------ ------ ----- - 0 up 7.5M/230.6K aes256 sha1 no 567 1800 all - -If there is SNAT rules on eth1, need to add exclude rule - -.. code-block:: none - - # server side - set nat source rule 10 destination address '10.0.0.0/24' - set nat source rule 10 'exclude' - set nat source rule 10 outbound-interface name 'eth1' - set nat source rule 10 source address '192.168.0.0/24' - - # remote office side - set nat source rule 10 destination address '192.168.0.0/24' - set nat source rule 10 'exclude' - set nat source rule 10 outbound-interface name 'eth1' - set nat source rule 10 source address '10.0.0.0/24' - -To allow traffic to pass through to clients, you need to add the following -rules. (if you used the default configuration at the top of this page) - -.. code-block:: none - - # server side - set firewall name OUTSIDE-LOCAL rule 32 action 'accept' - set firewall name OUTSIDE-LOCAL rule 32 source address '10.0.0.0/24' - - # remote office side - set firewall name OUTSIDE-LOCAL rule 32 action 'accept' - set firewall name OUTSIDE-LOCAL rule 32 source address '192.168.0.0/24' - -IKEv2 -^^^^^ - -Example: - -* left local_ip: 192.168.0.10 # VPN Gateway, behind NAT device -* left public_ip:172.18.201.10 -* right local_ip: 172.18.202.10 # right side WAN IP - -Imagine the following topology - -.. figure:: /_static/images/vpn_s2s_ikev2_c.png - :scale: 50 % - :alt: IPSec IKEv2 site2site VPN - - IPSec IKEv2 site2site VPN (source ./draw.io/vpn_s2s_ikev2.drawio) - -**LEFT:** -* WAN interface on `eth0.201` -* `eth0.201` interface IP: `172.18.201.10/24` -* `vti10` interface IP: `10.0.0.2/31` -* `dum0` interface IP: `10.0.11.1/24` (for testing purposes) - -**RIGHT:** -* WAN interface on `eth0.202` -* `eth0.201` interface IP: `172.18.202.10/24` -* `vti10` interface IP: `10.0.0.3/31` -* `dum0` interface IP: `10.0.12.1/24` (for testing purposes) - -.. note:: Don't get confused about the used /31 tunnel subnet. :rfc:`3021` - gives you additional information for using /31 subnets on point-to-point - links. - -**LEFT** - -.. code-block:: none - - set interfaces ethernet eth0 vif 201 address '172.18.201.10/24' - set interfaces dummy dum0 address '10.0.11.1/24' - set interfaces vti vti10 address '10.0.0.2/31' - - set vpn ipsec authentication psk peer_172-18-202-10 id '172.18.201.10' - set vpn ipsec authentication psk peer_172-18-202-10 id '172.18.202.10' - set vpn ipsec authentication psk peer_172-18-202-10 secret 'secretkey' - set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' - set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' - set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' - set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' - set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec ike-group IKEv2_DEFAULT close-action 'none' - set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'trap' - set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' - set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' - set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike - set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' - set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' - set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' - set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' - set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec interface 'eth0.201' - set vpn ipsec site-to-site peer peer_172-18-202-10 authentication local-id '172.18.201.10' - set vpn ipsec site-to-site peer peer_172-18-202-10 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer peer_172-18-202-10 authentication remote-id '172.18.202.10' - set vpn ipsec site-to-site peer peer_172-18-202-10 connection-type 'initiate' - set vpn ipsec site-to-site peer peer_172-18-202-10 ike-group 'IKEv2_DEFAULT' - set vpn ipsec site-to-site peer peer_172-18-202-10 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer peer_172-18-202-10 local-address '172.18.201.10' - set vpn ipsec site-to-site peer peer_172-18-202-10 remote-address '172.18.202.10' - set vpn ipsec site-to-site peer peer_172-18-202-10 vti bind 'vti10' - set vpn ipsec site-to-site peer peer_172-18-202-10 vti esp-group 'ESP_DEFAULT' - - set protocols static interface-route 10.0.12.0/24 next-hop-interface vti10 - -**RIGHT** - -.. code-block:: none - - set interfaces ethernet eth0 vif 202 address '172.18.202.10/24' - set interfaces dummy dum0 address '10.0.12.1/24' - set interfaces vti vti10 address '10.0.0.3/31' - - set vpn ipsec authentication psk peer_172-18-201-10 id '172.18.202.10' - set vpn ipsec authentication psk peer_172-18-201-10 id '172.18.201.10' - set vpn ipsec authentication psk peer_172-18-201-10 secret 'secretkey' - set vpn ipsec esp-group ESP_DEFAULT lifetime '3600' - set vpn ipsec esp-group ESP_DEFAULT mode 'tunnel' - set vpn ipsec esp-group ESP_DEFAULT pfs 'dh-group19' - set vpn ipsec esp-group ESP_DEFAULT proposal 10 encryption 'aes256gcm128' - set vpn ipsec esp-group ESP_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec ike-group IKEv2_DEFAULT close-action 'none' - set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection action 'trap' - set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection interval '30' - set vpn ipsec ike-group IKEv2_DEFAULT dead-peer-detection timeout '120' - set vpn ipsec ike-group IKEv2_DEFAULT disable-mobike - set vpn ipsec ike-group IKEv2_DEFAULT key-exchange 'ikev2' - set vpn ipsec ike-group IKEv2_DEFAULT lifetime '10800' - set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 dh-group '19' - set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 encryption 'aes256gcm128' - set vpn ipsec ike-group IKEv2_DEFAULT proposal 10 hash 'sha256' - set vpn ipsec interface 'eth0.202' - set vpn ipsec site-to-site peer peer_172-18-201-10 authentication local-id '172.18.202.10' - set vpn ipsec site-to-site peer peer_172-18-201-10 authentication mode 'pre-shared-secret' - set vpn ipsec site-to-site peer peer_172-18-201-10 authentication remote-id '172.18.201.10' - set vpn ipsec site-to-site peer peer_172-18-201-10 connection-type 'initiate' - set vpn ipsec site-to-site peer peer_172-18-201-10 ike-group 'IKEv2_DEFAULT' - set vpn ipsec site-to-site peer peer_172-18-201-10 ikev2-reauth 'inherit' - set vpn ipsec site-to-site peer peer_172-18-201-10 local-address '172.18.202.10' - set vpn ipsec site-to-site peer peer_172-18-201-10 remote-address '172.18.201.10' - set vpn ipsec site-to-site peer peer_172-18-201-10 vti bind 'vti10' - set vpn ipsec site-to-site peer peer_172-18-201-10 vti esp-group 'ESP_DEFAULT' - - set protocols static interface-route 10.0.11.0/24 next-hop-interface vti10 - -Key Parameters: - -* ``authentication local-id/remote-id`` - IKE identification is used for - validation of VPN peer devices during IKE negotiation. If you do not configure - local/remote-identity, the device uses the IPv4 or IPv6 address that - corresponds to the local/remote peer by default. - In certain network setups (like ipsec interface with dynamic address, or - behind the NAT ), the IKE ID received from the peer does not match the IKE - gateway configured on the device. This can lead to a Phase 1 validation - failure. - So, make sure to configure the local/remote id explicitly and ensure that the - IKE ID is the same as the remote-identity configured on the peer device. - -* ``disable-route-autoinstall`` - This option when configured disables the - routes installed in the default table 220 for site-to-site ipsec. - It is mostly used with VTI configuration. - -* ``dead-peer-detection action = clear | trap | restart`` - R_U_THERE - notification messages(IKEv1) or empty INFORMATIONAL messages (IKEv2) - are periodically sent in order to check the liveliness of the IPsec peer. The - values clear, trap, and restart all activate DPD and determine the action to - perform on a timeout. - With ``clear`` the connection is closed with no further actions taken. - ``trap`` installs a trap policy, which will catch matching traffic and tries - to re-negotiate the connection on demand. - ``restart`` will immediately trigger an attempt to re-negotiate the - connection. - -* ``close-action = none | clear | trap | start`` - defines the action to take - if the remote peer unexpectedly closes a CHILD_SA (see above for meaning of - values). A closeaction should not be used if the peer uses reauthentication or - uniqueids. - - When the close-action option is set on the peers, the connection-type - of each peer has to considered carefully. For example, if the option is set - on both peers, then both would attempt to initiate and hold open multiple - copies of each child SA. This might lead to instability of the device or - cpu/memory utilization. - - Below flow-chart could be a quick reference for the close-action - combination depending on how the peer is configured. - -.. figure:: /_static/images/IPSec_close_action_settings.jpg - - Similar combinations are applicable for the dead-peer-detection. diff --git a/docs/configuration/vpn/sstp.rst b/docs/configuration/vpn/sstp.rst index e750cdcf..b65aecca 100644 --- a/docs/configuration/vpn/sstp.rst +++ b/docs/configuration/vpn/sstp.rst @@ -153,11 +153,12 @@ RADIUS advanced options .. cfgcmd:: set vpn sstp authentication radius dynamic-author server <address> - Specifies IP address for Dynamic Authorization Extension server (DM/CoA) + Specifies IP address for Dynamic Authorization Extension server (DM/CoA). + This IP must exist on any VyOS interface or it can be ``0.0.0.0``. .. cfgcmd:: set vpn sstp authentication radius dynamic-author port <port> - Port for Dynamic Authorization Extension server (DM/CoA) + UDP port for Dynamic Authorization Extension server (DM/CoA) .. cfgcmd:: set vpn sstp authentication radius dynamic-author key <secret> |