diff options
Diffstat (limited to 'docs/vpn')
| -rw-r--r-- | docs/vpn/openvpn.rst | 90 | ||||
| -rw-r--r-- | docs/vpn/site2site_ipsec.rst | 103 | ||||
| -rw-r--r-- | docs/vpn/wireguard.rst | 76 |
3 files changed, 256 insertions, 13 deletions
diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 29104199..e252d016 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -227,8 +227,12 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: set protocols static interface-route 10.23.0.0/20 next-hop-interface vtun10 -LDAP Authentication -******************* + +Client Authentication +********************* + +OpenLDAP +======== Enterprise installations usually ship a kind of directory service which is used to have a single password store for all employes. VyOS and OpenVPN support using @@ -267,7 +271,7 @@ The required config file may look like: </Authorization> Active Directory -**************** +================ Despite the fact that AD is a superset of LDAP @@ -308,16 +312,16 @@ If you only wan't to check if the user account is enabled and can authenticate .. code-block:: sh <LDAP> - URL ldap://ds0001.gefoekom.de - BindDN CN=SA_OPENVPN,OU=ServiceAccounts,OU=GS,OU=GeFoekoM,DC=gefoekom,DC=de - Password g7LjfjmlPhhHnvmal75hbfdknms-44 + 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 "OU=GeFoekoM,DC=gefoekom,DC=de" + BaseDN "DC=example,DC=com" SearchFilter "sAMAccountName=%u" RequireGroup false </Authorization> @@ -351,3 +355,75 @@ A complete LDAP auth OpenVPN configuration could look like the following example key-file /config/auth/server.key } } + +OpenVPN Client +^^^^^^^^^^^^^^ + +VyOS can not only act as an OpenVPN site-to-site or Server for multiple clients. +You can indeed also configure any VyOS OpenVPN interface as an OpenVPN client +connecting to a VyOS OpenVPN server or any other OpenVPN server. + +Given the following example we have one VyOS router acting as OpenVPN server +and another VyOS router acting as 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. + + +Server +****** + +.. code-block:: sh + + set interfaces openvpn vtun10 encryption '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-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/server.crt' + set interfaces openvpn vtun10 tls dh-file '/config/auth/dh.pem' + set interfaces openvpn vtun10 tls key-file '/config/auth/server.key' + set interfaces openvpn vtun10 use-lzo-compression + +Client +****** + +.. code-block:: sh + + set interfaces openvpn vtun10 encryption '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-file '/config/auth/ca.crt' + set interfaces openvpn vtun10 tls cert-file '/config/auth/client1.crt' + set interfaces openvpn vtun10 tls key-file '/config/auth/client1.key' + set interfaces openvpn vtun10 use-lzo-compression + +Options +^^^^^^^ + +We do not have CLI nodes for every single OpenVPN options. If an option is +missing, a feature request should be opened at https://phabricator.vyos.net so +all users can benefit from it. + +If you are a hacker or want to try on your own we support passing raw OpenVPN +options to OpenVPN. + +.. code-block:: sh + + set interfaces openvpn vtun10 openvpn-option 'persistent-key' + +Will add `persistent-key` at the end of 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. diff --git a/docs/vpn/site2site_ipsec.rst b/docs/vpn/site2site_ipsec.rst index ff398dab..41115f8c 100644 --- a/docs/vpn/site2site_ipsec.rst +++ b/docs/vpn/site2site_ipsec.rst @@ -1,7 +1,108 @@ .. _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`` command. + +You can identify a remote peer with: + +* IPv4 or IPv6 address. This mode is easiest for configuration and mostly used when a peer has a public static IP address; +* Hostname. This mode is similar to IP address, only you define DNS name instead of an IP. 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; +* Remote ID of the peer. In this mode, there is no predefined remote address nor DNS name of the peer. This mode is useful when a peer doesn't have a publicly available IP address (NAT between it and VyOS), or IP address could be changed. + +Each site-to-site peer has the next options: + +* ``authentication`` - configure authentication between VyOS and a remote peer. Suboptions: + + * ``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, must be the same for local and remote side; + + * ``rsa`` - use simple shared RSA key. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``x509`` - use certificates infrastructure for authentication. + + * ``pre-shared-secret`` - predefined shared secret. Used if configured ``mode pre-shared-secret``; + + * ``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-key-name`` - shared RSA key for authentication. The key must be defined in the ``set vpn rsa-keys`` section; + + * ``use-x509-id`` - use local ID from x509 certificate. Cannot be used when ``id`` is defined; + + * ``x509`` - options for x509 authentication mode: + + * ``ca-cert-file`` - CA certificate file. Using for authenticating remote peer; + + * ``cert-file`` - certificate file, which will be used for authenticating local router on remote peer; + + * ``crl-file`` - file with the Certificate Revocation List. Using to check if a certificate for the remote peer is valid or revocated; + + * ``key`` - a private key, which will be used for authenticating local router on remote peer: + + * ``file`` - path to the key file; + + * ``password`` - passphrase private key, if needed. + +* ``connection-type`` - how to handle this connection process. Possible variants: + + * ``initiate`` - do 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`` - do 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. + +* ``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-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: + + * ``yes`` - create a new IKE_SA from the scratch and try to recreate all IPsec SAs; + + * ``no`` - rekey without uninstalling the IPsec SAs; + + * ``inherit`` - use default behavior for the used IKE group. + +* ``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; + +* ``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. + + * ``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. + +Examples: +------------------ IKEv1 ^^^^^ diff --git a/docs/vpn/wireguard.rst b/docs/vpn/wireguard.rst index 141e843c..a2f45913 100644 --- a/docs/vpn/wireguard.rst +++ b/docs/vpn/wireguard.rst @@ -10,8 +10,16 @@ information. Configuration ^^^^^^^^^^^^^ +Wireguard requires the generation of a keypair, a private key which will decrypt +incoming traffic and a public key, which the peer(s) will use to encrypt traffic. + +Generate a keypair +~~~~~~~~~~~~~~~~~~ + Generate the keypair, which creates a public and private part and stores it within VyOS. +It will be used per default on any configured wireguard interface, even if +multiple interfaces are being configured. .. code-block:: sh @@ -26,6 +34,27 @@ traffic to your system using this public key. wg01# run show wireguard pubkey u41jO3OF73Gq1WARMMFG7tOfk7+r8o8AzPxJ1FZRhzk= + +Generate named keypairs +~~~~~~~~~~~~~~~~~~~~~~~ + +Named keypairs can be used on a interface basis, if configured. +If multiple wireguard interfaces are being configured, each can have +their own keypairs. + +The commands below will generate 2 keypairs, which are not releated +to each other. + +.. code-block:: sh + + wg01:~$ configure + wg01# run generate wireguard named-keypairs KP01 + wg01# run generate wireguard named-keypairs KP02 + + +Wireguard Interface configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The next step is to configure your local side as well as the policy based trusted destination addresses. If you only initiate a connection, the listen port and endpoint is optional, if you however act as a server and endpoints @@ -55,6 +84,18 @@ the wireguard interface `wg01`. Multiple IPs or networks can be defined and routed, the last check is allowed-ips which either prevents or allows the traffic. + +To use a named key on an interface, the option private-key needs to be set. + +.. code-block:: sh + + set interfaces wireguard wg01 private-key KP01 + set interfaces wireguard wg02 private-key KP02 + +The command ``run show wireguard named-keypairs pubkey KP01`` will then show the public key, +which needs to be shared with the peer. + + **remote side** .. code-block:: sh @@ -90,20 +131,23 @@ asymmetric crypto, which is optional. wg01# run generate wireguard preshared-key rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc= -Copy the key, it is not stored on the local file system. Make sure you -distribute that key in a safe manner, it's a symmatric key, so only you and -your peer should have knowledge if its content. +Copy the key, as it is not stored on the local file system. Make sure you +distribute that key in a safe manner, it's a symmetric key, so only you and +your peer should have knowledge of its content. .. code-block:: sh wg01# set interfaces wireguard wg01 peer to-wg02 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' wg02# set interfaces wireguard wg01 peer to-wg01 preshared-key 'rvVDOoc2IYEnV+k5p7TNAmHBMEGTHbPU8Qqg8c/sUqc=' -**operational commands** +Operational commands +^^^^^^^^^^^^^^^^^^^^ + +**Show interface status** .. code-block:: sh - vyos@wg01# show interfaces wireguard wg01 + vyos@wg01# run show interfaces wireguard wg01 interface: wg01 public key: xHvgSJC8RTClfvjc0oX6OALxU6GGLapjthjw7x82CSw= @@ -115,3 +159,25 @@ your peer should have knowledge if its content. allowed ips: 10.2.0.0/24 latest handshake: 4 minutes, 22 seconds ago transfer: 860 B received, 948 B sent + +**Show public key of the default key** + +.. code-block:: sh + + vyos@wg01# run show wireguard keypair pubkey default + FAXCPb6EbTlSH5200J5zTopt9AYXneBthAySPBLbZwM= + +**Show public key of a named key** + +.. code-block:: sh + + vyos@wg01# run show wireguard keypair pubkey KP01 + HUtsu198toEnm1poGoRTyqkUKfKUdyh54f45dtcahDM= + + +**Delete wireguard keypairs** + +.. code-block:: sh + + vyos@wg01# wireguard keypair default + |