diff options
47 files changed, 3056 insertions, 2263 deletions
diff --git a/.github/workflows/check-open-prs-conflict.yml b/.github/workflows/check-open-prs-conflict.yml new file mode 100644 index 00000000..52b11938 --- /dev/null +++ b/.github/workflows/check-open-prs-conflict.yml @@ -0,0 +1,17 @@ +name: "Open PRs Conflicts checker" +on: + push: + branches: + - current + - sagitta + - circinus + workflow_dispatch: + +permissions: + contents: read + pull-requests: write + +jobs: + check-pr-conflict-call: + uses: vyos/.github/.github/workflows/check-open-prs-conflict.yml@current + secrets: inherit diff --git a/.github/workflows/check-pr-conflicts.yml b/.github/workflows/check-pr-conflicts.yml index 0c659e6e..f09e6641 100644 --- a/.github/workflows/check-pr-conflicts.yml +++ b/.github/workflows/check-pr-conflicts.yml @@ -10,5 +10,5 @@ permissions: jobs: check-pr-conflict-call: - uses: vyos/.github/.github/workflows/check-pr-merge-conflict.yml@feature/T6349-reusable-workflows + uses: vyos/.github/.github/workflows/check-pr-merge-conflict.yml@current secrets: inherit diff --git a/.github/workflows/cla-check.yml b/.github/workflows/cla-check.yml new file mode 100644 index 00000000..3c1aeee6 --- /dev/null +++ b/.github/workflows/cla-check.yml @@ -0,0 +1,19 @@ +name: "CLA Check" + +permissions: + actions: write + contents: read + pull-requests: write + statuses: write + +on: + pull_request: + types: [opened, synchronize, closed] + issue_comment: + types: [created] + +jobs: + call-cla-assistant: + uses: vyos/vyos-cla-signatures/.github/workflows/cla-reusable.yml@current + secrets: + CLA_PAT: ${{ secrets.CLA_PAT }} @@ -1,2 +1,2 @@ -* @vyos/reviewers +# * @vyos/reviewers * @rebortg
\ No newline at end of file diff --git a/docs/_static/images/ESP_AH.png b/docs/_static/images/ESP_AH.png Binary files differnew file mode 100644 index 00000000..6075c3f4 --- /dev/null +++ b/docs/_static/images/ESP_AH.png diff --git a/docs/_static/images/IPSec_close_action_settings.jpg b/docs/_static/images/IPSec_close_action_settings.jpg Binary files differdeleted file mode 100644 index 6996f857..00000000 --- a/docs/_static/images/IPSec_close_action_settings.jpg +++ /dev/null diff --git a/docs/_static/images/IPSec_close_action_settings.png b/docs/_static/images/IPSec_close_action_settings.png Binary files differnew file mode 100644 index 00000000..531643f7 --- /dev/null +++ b/docs/_static/images/IPSec_close_action_settings.png diff --git a/docs/automation/vyos-api.rst b/docs/automation/vyos-api.rst index a9518a00..7b4a24df 100644 --- a/docs/automation/vyos-api.rst +++ b/docs/automation/vyos-api.rst @@ -517,3 +517,80 @@ To Load a configuration file. "data": null, "error": null } + +To Merge a configuration file. + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/config-file' \ + --form data='{"op": "merge", "file": "/config/test.config"}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": null, + "error": null + } + +In either of the last two cases, one can pass a string in the body of the +request, for example: + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/config-file' \ + --form data='{"op": "merge", "string": "interfaces {\nethernet eth1 {\naddress "192.168.2.137/24"\ndescription "test"\n}\n}\n"}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": null, + "error": null + } + +************** +Commit-confirm +************** + +For the previous two endpoints discussed, a ``commit`` command is implicit +following a succesful request operation (``set | delete | load | merge``, or +a list of ``set`` and ``delete`` operations). One can instead request a +``commit-confirm`` command by including the field ``confirm_time`` of type +int > 0. An example follows, in the alternative JSON format, for brevity, +although the standard form-data format is fine: + +.. code-block:: none + + curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "merge", "string": "interfaces {\nethernet eth1 {\naddress '192.168.137.1/24'\ndescription 'internal'\n}\n}\n", "confirm_time": 1}' https://vyos/config-file + + response: + { + "success": true, + "data": "Initialized commit-confirm; 1 minutes to confirm before reload\n", + "error": null + } + +The committed changes will be reverted at the timeout unless confirmed. +To confirm and keep the changes: + +.. code-block:: none + + curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "confirm"}' https://vyos/config-file + + response: + { + "success": true, + "data": "Reload timer stopped\n", + "error": null + } + +If allowed to revert to the previous configuration, the manner in which +changes are reverted is governed by: + +.. code-block:: none + + vyos@vyos# set system config-management commit-confirm action + Possible completions: + reload Reload previous configuration if not confirmed + reboot Reboot to saved configuration if not confirmed (default) diff --git a/docs/cli.rst b/docs/cli.rst index 74e803dc..550494fa 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -116,6 +116,7 @@ impact on a particular users in the network. 192.0.2.54. - ``reset vpn ipsec site-to-site peer vpn.example.com`` — terminates IPsec tunnels to ``vpn.example.com``. +- ``reset session tty1`` — terminates the TTY user session ``tty1`` restart ''''''' diff --git a/docs/configexamples/autotest/tunnelbroker/tunnelbroker.rst b/docs/configexamples/autotest/tunnelbroker/tunnelbroker.rst index 0f7c9daf..370cf9d6 100644 --- a/docs/configexamples/autotest/tunnelbroker/tunnelbroker.rst +++ b/docs/configexamples/autotest/tunnelbroker/tunnelbroker.rst @@ -208,9 +208,8 @@ Firewall ======== Finally, don't forget the :ref:`Firewall<configuration/firewall/index:Firewall>`. The usage is identical, except for -instead of `set firewall name NAME`, you would use `set firewall ipv6-name +instead of `set firewall ipv4 name NAME`, you would use `set firewall ipv6 name NAME`. -Similarly, to attach the firewall, you would use `set interfaces ethernet eth0 -firewall in ipv6-name` or `set firewall zone LOCAL from WAN firewall +Similarly, to attach the firewall, you would use `set firewall ipv6 name NAME rule N inbound-interface name eth0` or `set firewall zone LOCAL from WAN firewall ipv6-name`. 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 64221413..b1accca5 100644 --- a/docs/configuration/firewall/groups.rst +++ b/docs/configuration/firewall/groups.rst @@ -41,28 +41,33 @@ Remote Groups ============== A **remote-group** takes an argument of a URL hosting a linebreak-deliminated -list of IPv4s addresses, CIDRs and ranges. VyOS will pull this list periodicity +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 addresses/ranges/CIDRs to fetch + 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 + 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. Below is a list of acceptable matches that would be parsed correctly: +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 ============== @@ -258,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 @@ -272,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 @@ -290,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 @@ -453,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/protocols/ospf.rst b/docs/configuration/protocols/ospf.rst index 9891c77d..ac0ed160 100644 --- a/docs/configuration/protocols/ospf.rst +++ b/docs/configuration/protocols/ospf.rst @@ -1341,9 +1341,8 @@ A typical configuration using 2 nodes. show ipv6 ospfv3 redistribute -.. note:: You cannot easily redistribute IPv6 routes via OSPFv3 on a - WireGuard interface link. This requires you to configure link-local - addresses manually on the WireGuard interfaces, see :vytask:`T1483`. +Cost calculation wireguard interfaces is unreliable as ospfv3 uses the link speed to calculate the link cost. +You might therefore want to set the link cost to a fixed value on WireGuard tunnels. Example configuration for WireGuard interfaces: @@ -1351,30 +1350,26 @@ Example configuration for WireGuard interfaces: .. code-block:: none - set interfaces wireguard wg01 address 'fe80::216:3eff:fe51:fd8c/64' - set interfaces wireguard wg01 address '192.168.0.1/24' set interfaces wireguard wg01 peer ospf02 allowed-ips '::/0' - set interfaces wireguard wg01 peer ospf02 allowed-ips '0.0.0.0/0' set interfaces wireguard wg01 peer ospf02 endpoint '10.1.1.101:12345' set interfaces wireguard wg01 peer ospf02 pubkey 'ie3...=' set interfaces wireguard wg01 port '12345' set protocols ospfv3 parameters router-id 192.168.1.1 set protocols ospfv3 interface 'wg01' area 0.0.0.0 + set protocols ospfv3 interface 'wg01' cost 10 set protocols ospfv3 interface 'lo' area 0.0.0.0 **Node 2** .. code-block:: none - set interfaces wireguard wg01 address 'fe80::216:3eff:fe0a:7ada/64' - set interfaces wireguard wg01 address '192.168.0.2/24' set interfaces wireguard wg01 peer ospf01 allowed-ips '::/0' - set interfaces wireguard wg01 peer ospf01 allowed-ips '0.0.0.0/0' set interfaces wireguard wg01 peer ospf01 endpoint '10.1.1.100:12345' set interfaces wireguard wg01 peer ospf01 pubkey 'NHI...=' set interfaces wireguard wg01 port '12345' set protocols ospfv3 parameters router-id 192.168.1.2 set protocols ospfv3 interface 'wg01' area 0.0.0.0 + set protocols ospfv3 interface 'wg01' cost 10 set protocols ospfv3 interface 'lo' area 0.0.0.0 **Status** 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> diff --git a/docs/contributing/build-vyos.rst b/docs/contributing/build-vyos.rst index 623cba78..3226def6 100644 --- a/docs/contributing/build-vyos.rst +++ b/docs/contributing/build-vyos.rst @@ -702,7 +702,7 @@ needs. We first need to clone the repository from GitHub. .. code-block:: none - $ git clone https://github.com/vyos/vyos-1x + $ git clone --recurse-submodules https://github.com/vyos/vyos-1x Build ===== diff --git a/docs/installation/index.rst b/docs/installation/index.rst index 7cdd9c29..c1e50a1f 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -24,4 +24,3 @@ Installation and Image Management update image secure-boot - migrate-from-vyatta diff --git a/docs/installation/migrate-from-vyatta.rst b/docs/installation/migrate-from-vyatta.rst deleted file mode 100644 index f15c3d5a..00000000 --- a/docs/installation/migrate-from-vyatta.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. _migrate_from_vyatta: - -Migrate from Vyatta Core -======================== - -VyOS 1.x line aims to preserve backward compatibility and provide a safe -upgrade path for existing Vyatta Core users. You may think of VyOS 1.0.0 as -VC7.0. - -Vyatta release compatibility ----------------------------- - -Vyatta Core releases from 6.5 to 6.6 should be 100% compatible. - -Vyatta Core 6.4 and earlier may have incompatibilities. In Vyatta 6.5 the -"modify" firewall was removed and replaced with the ``set policy route`` -command family, old configs can not be automatically converted. You will have -to adapt it to post-6.5 Vyatta syntax manually. - -.. note:: Also, in Vyatta Core 6.5 remote access VPN interfaces have been - renamed from ``pppX`` to ``l2tpX`` and ``pptpX``. If you are using - zone based firewalling in Vyatta Core pre-6.5 versions, make sure to change - interface names in rules for remote access VPN. - -Upgrade procedure ------------------ - -You just use ``add system image``, as if it was a new VC release (see -:ref:`update_vyos` for additional information). The only thing you want to do -is to verify the new images digital signature. You will have to add the public -key manually once as it is not shipped the first time. - -.. code-block:: none - - vyatta@vyatta:~$ wget http://wiki.vyos.net/so3group_maintainers.key - Connecting to vyos.net (x.x.x.x:80) - so3group_maintainers 100% |*************************| 3125 --:--:-- ETA - vyatta@vyatta:~$ sudo apt-key add so3group_maintainers.key - OK - vyatta@vyatta:~$ - -For completion the key below corresponds to the key listed in the URL above. - -.. code-block:: none - - -----BEGIN PGP PUBLIC KEY BLOCK----- - Version: GnuPG v1.4.12 (GNU/Linux) - - mQINBFIIUZwBEADGl+wkZpYytQxd6LnjDZZScziBKYJbjInetYeS0SUrgpqnPkzL - 2CiGfPczLwpYY0zWxpUhTvqjFsE5yDpgs0sPXIgUTFE1qfZQE+WD1I1EUM6sp/38 - 2xKQ9QaNc8oHuYINLYYmNYra6ZjIGtQP9WOX//IDYB3fhdwlmiW2z0hux2OnPWdh - hPZAmSrx5AiXFEEREJ1cAQyvYk7hgIRvM/rdQMUm+u4/z+S4mxCHE10KzlqOGhRv - hA8WQxHCVusMFGwXoKHxYf9OQpV7lsfOCODfXOMP/L9kHQ5/gBsLL5hHst+o/3VG - ec0QuVrVkBBehgrqhfJW2noq+9gTooURGImQHEOyE0xpJdFrrgk5Ii9RqQwdVRzI - ZPbqbo8uuldZIRJRGnfx+vAR9812yo38NVZ/X0P/hkkrx+UeGVgpC/ao5XLRiOzL - 7ZBMWLA6FVmZ7mkpqdzuMXX5548ApACm6EKErULIhTYDGDzFxA3cf6gr5VVi4usD - wglVs+FHuiLehmuuPTMoVcT2R6+Ht44hG3BmQmKzh/SSEa1g9gKgrhZrMdIyK4hu - GvMqLw9z9BgJbWB3BgXOUdlkXLDwBvVpEcWsPJgxSjAvjAbLLE4YkKAdYU8bQ0Pd - JuN485tcXxgQCadFZB0gcipQAvVf4b810HrY88g6FldfauHxiACOlXscZwARAQAB - tDBTTzMgR3JvdXAgTWFpbnRhaW5lcnMgPG1haW50YWluZXJzQHNvM2dyb3VwLm5l - dD6JAjgEEwECACIFAlIIUZwCGwMGCwkIBwMCBhUIAgkKCwQWAgMBAh4BAheAAAoJ - ELdE4lqkQubp8GsQAKntoRFG6bWX/4WPw7Vo7kIF5kWcmv3lVb0AQkacscWope7T - Iq0VcgpAycJue2bSS9LAsvNtpVkQmFawbwFjqB3CC5NbPNQ4Kf+gswKa+yaHwejo - 7dkslAwxgXHe5g76DG7CVLMsMg6zVDFYuzeksPywls/OJBIpkuGqeXy9tAHjQzjA - SlZV3Gsx7azESjiVQ73EUBt2OXkwN4TN9TEHAnVsrNIXHwFl1VfFsSG1Q6uZDtkk - CB4DZJKN4RzCY2QSwMAqRRC2OXdwk5IAk8wwCGoFpp0UV6CO9YCeOaqJderEcBA4 - MGHqdiPDIbH5wvckjZzFznU/Paz3MwPwBdtN+WSKvwf+JItSiUqm8Dy2Pl/1cnux - 1g1I4WQlXUVaS/MDusqL7tbS8k5A5a2+YVMxShWH9BhXZwNXzEihl4sm8Hrg5SvZ - givJj2y93WoL69Wq0/86wkkH2xcrz4gsiUcQf5YXU/RHXOLnPR29/pg8TS0L7sST - dv0X23C2IpfqYoqN7YZ3K0Wczhi0yLPCrc27IczuHgjt/8ICda11xhB1t/pUbvnX - oksehaLp8O3uU8GyAsTfUgpijZFc/3jIadOl0L9NGUbYYgPzFeaZTa/njeEbz3wX - PZMn278sbL9UhupI5Hx7eREbKzV4VPVKz81ndKNMXyuJHXv2R0xou3nvuo1WuQIN - BFIIUZwBEADAhoYPDCSogG41Naq+wFkG+IPszqe0dW/UWg0xrZDT0UblwDSd4OGY - 7FATMIhjOUyFxk6+XKA5CDCWP8Npkl0modTL59uVWNxU1vUKincc/j4ipHQeAhE6 - fvZkrprvADD8TYIGesl/3EGNc7bzc5ZqX71hKPHG+autRtgFSOR2PSXD9MlJXIBb - RzHAXxlh72zvsGadcxLJm4pSWXitkR/5Wc3e0IippKdzGwZnCDpNmcBGtSTFgixP - JqyRZFVCPWs7jr/oQeZnq65wJp1KD2HvhhKHJfsPrnNjLSm1SQVh8hXzE9odcv6N - mJB7tNXywuROBt6a01ojBa9J3zuMYQj3iQl2MhxtHylKVBjr7NjZ4evZbLsRMxY1 - hYk7sl+ZxCPFeOZ9D2ppU/CUDXCS095I1x+s+VuiUNf/3yd8ahCWDXVp9nsXyYjm - 2pHIxb2F6r8Vd4AjlD2MQwszECS88INF3l/9ksIHEMKuuW+JAC9FiZ7k4IGcIltv - If/V2TgE6t6qoWIlmLhMTjOyJpwnokY1nIuXHH7yp+HsuqnYnf/dgLnt4czPLeHO - +TdIDHhUym0AKlCcbdgn0C6EJVTnA8BFgFjiIOMAeT0rhATg0W/cND8KQcX4V9wM - nHSEsgSEuP9H+67xuRx5Imuh5ntecrcuCYSNuOneUXWPThDKQPO9lQARAQABiQIf - BBgBAgAJBQJSCFGcAhsMAAoJELdE4lqkQubpc+0P/0IzUx8nTpF0/ii2TA0YCOgj - tviM6PRTVPrFcxijNeXiIMHZYrALYUvXxXGp1IZBP3IcOyuZNp2WLqF/f9a3cIr1 - 9b/LJPrwopGqV3K30lormk7hH0s3IXbhd0ZYWvRj+5kQ8TFRAFfPwjlItzjYJmYX - AGJmM9PxJID/4LgWSfQ/ZfNu7MJ7+2goQLu9b6x7UC1FlE4q1lcjBvHjVPM//S9G - lGAHaysyTjVu88W2wwBpBrO1MQnDvqFRddXPOIWp0jecBMUd4E0fB36yuStsXZT3 - RN4V8vKRBYXuqHhiTwZeh153cHZk2EZBwz5A6DJubMaGdJTesHW5Qf2goph0pmjC - +XuXn8J6tc5nFDf8DP4AFVMtqa3Brj2fodWd0Zzxq3AVsbX144c1oqJUhO4t3+ie - 8fD/6/jx4iuPCQTfyhHG+zGfyUb2LQ+OVLW1WYTxH5tzHaZUmZFdV2I1kuhuvZ1t - WRlmTnHZOnEb3+t8KCRWzRMfweTzXfRRKBC0/QpeX1r5pbaMHH8zF/J5PKmL0+jg - +DS8JSbSfv7Ke6rplf7lHYaDumAFZfxXuQkajzLZbX0E5Xu5BNz4Vq6LGBj7LDXL - gswIK8FFgZB+W8zwOqUV1vjIr9wkdLifXXezKpTeYpFDGLdfsK+uNAtGyvI61TDi - Pr6fWpIruuc7Gg9rUF0L - =VQTr - -----END PGP PUBLIC KEY BLOCK----- - -Next add the VyOS image. - -This example uses VyOS 1.0.0, however, it's better to install the latest -release. - -.. code-block:: none - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - 1: VC6.6R1 (default boot) (running image) - - vyatta@vyatta:~$ add system image https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - Trying to fetch ISO file from https://downloads.vyos.io/release/legacy/1.0.0/vyos-1.0.0-amd64.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 223M 100 223M 0 0 960k 0 0:03:57 0:03:57 --:--:-- 657k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 836 100 836 0 0 4197 0 --:--:-- --:--:-- --:--:-- 4287 - Found it. Checking digital signature... - gpg: directory `/root/.gnupg' created - gpg: new configuration file `/root/.gnupg/gpg.conf' created - gpg: WARNING: options in `/root/.gnupg/gpg.conf' are not yet active during this run - gpg: keyring `/root/.gnupg/pubring.gpg' created - gpg: Signature made Sun Dec 22 16:51:42 2013 GMT using RSA key ID A442E6E9 - gpg: /root/.gnupg/trustdb.gpg: trustdb created - gpg: Good signature from "SO3 Group Maintainers <maintainers@so3group.net>" - gpg: WARNING: This key is not certified with a trusted signature! - gpg: There is no indication that the signature belongs to the owner. - Primary key fingerprint: DD5B B405 35E7 F6E3 4278 1ABF B744 E25A A442 E6E9 - Digital signature is valid. - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [1.0.0]: [return] - OK. This image will be named: 1.0.0 - Installing "1.0.0" image. - Copying new release files... - - Would you like to save the current configuration - directory and config file? (Yes/No) [Yes]: [return] - Copying current configuration... - - Would you like to save the SSH host keys from your - current configuration? (Yes/No) [Yes]: [return] - Copying SSH keys... - Setting up grub configuration... - Done. - - vyatta@vyatta:~$ show system image - The system currently has the following image(s) installed: - - 1: 1.0.0 (default boot) - 2: VC6.6R1 (running image) - -Upon reboot, you should have a working installation of VyOS. - -You can go back to your Vyatta install using the ``set system image -default-boot`` command and selecting the your previous Vyatta Core image. - -.. note:: Future releases of VyOS will break the direct upgrade path from - Vyatta core. Please upgrade through an intermediate VyOS version e.g. VyOS - 1.2. After this you can continue upgrading to newer releases once you bootet - into VyOS 1.2 once. diff --git a/requirements.txt b/requirements.txt index d604873c..aa559bf7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -urllib3==2.2.2 +urllib3==2.5.0 Sphinx==7.2.6 sphinx-rtd-theme==2.0.0 sphinx-autobuild==2021.3.14 |
