diff options
| -rw-r--r-- | docs/firewall.rst | 4 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/install.rst | 95 | ||||
| -rw-r--r-- | docs/nat.rst | 154 | ||||
| -rw-r--r-- | docs/system/system-users.rst | 15 |
5 files changed, 259 insertions, 10 deletions
diff --git a/docs/firewall.rst b/docs/firewall.rst index 118d70db..a56e56a8 100644 --- a/docs/firewall.rst +++ b/docs/firewall.rst @@ -3,7 +3,7 @@ Firewall ======== -VyOS makes use of Linux [http://netfilter.org/ netfilter] for packet filtering. +VyOS makes use of Linux [netfilter](http://netfilter.org/) for packet filtering. The firewall supports the creation of groups for ports, addresses, and networks (implemented using netfilter ipset) and the option of interface or zone based @@ -211,5 +211,5 @@ To achieve the same for IPv6 please use: set firewall options interface pppoe0 adjust-mss6 '1280' set firewall options interface wg02 adjust-mss6 '1280' -[https://www.xfinity.com/support/internet/list-of-blocked-ports/ XFinity Blocked Port List] +[XFinity Blocked Port List](https://www.xfinity.com/support/internet/list-of-blocked-ports/) diff --git a/docs/index.rst b/docs/index.rst index fb7cdc4e..46f554ab 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -41,6 +41,7 @@ as a router and firewall platform for cloud deployments. :caption: Contributing: :includehidden: + build-vyos.rst contributing/index.rst diff --git a/docs/install.rst b/docs/install.rst index 4714e87c..d63365ec 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -30,8 +30,8 @@ version if something breaks after upgrade. Every version is contained in its own squashfs image that is mounted in a union filesystem together with a directory for mutable data (configs etc.). -.. note:: Older versions used to support non-image installation (`install - system` command). It's been deprecated since the time image installation +.. note:: Older versions used to support non-image installation (`install system` command). + It's been deprecated since the time image installation was introduced (long before the fork), and does not provide any version management capabilities. You **should not** use it for new installations even if it's still available in new versions. You should not worry about @@ -99,3 +99,94 @@ After the installation is complete, remove the Live CD and reboot the system: vyos@vyos:~$ reboot Proceed with reboot? (Yes/No) [No] Yes + + +Verify digital signatures +------------------------- + +First you need to install GPG or another PGP implementation. +On most Linux distributions it's installed by default because package managers use it to verify package signatures. +On other systems you may need to find and install the package. + +You nee to import the key. + +``gpg --import maintainers.key`` + +| get the key from here: https://pgp.mit.edu/pks/lookup?op=vindex&search=0xFD220285A0FE6D7E +| or alternatively, you can import it by hand: + +.. code-block:: sh + + -----BEGIN PGP PUBLIC KEY BLOCK----- + Version: GnuPG v1.4.12 (GNU/Linux) + + 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 + 8vzPzaWHhkOkU8/J/Ci7+vNtUOZb + =Ld8S + -----END PGP PUBLIC KEY BLOCK----- + + + +.. code-block:: sh + + $ gpg --list-keys + ... + pub rsa4096 2015-08-12 [SC] + 0694A9230F5139BF834BA458FD220285A0FE6D7E + uid [ unknown] VyOS Maintainers (VyOS Release) <maintainers@vyos.net> + sub rsa4096 2015-08-12 [E] + +Now you can verify signatures: + +.. code-block:: sh + + $ gpg2 --verify vyos-1.2.1-amd64.iso.asc vyos-1.2.1-amd64.iso + gpg: Signature made So 14 Apr 12:58:07 2019 CEST + gpg: using RSA key FD220285A0FE6D7E + gpg: Good signature from "VyOS Maintainers (VyOS Release) <maintainers@vyos.net>" [unknown] + Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E
\ No newline at end of file diff --git a/docs/nat.rst b/docs/nat.rst index 6951a6b1..33e1efc4 100644 --- a/docs/nat.rst +++ b/docs/nat.rst @@ -55,8 +55,8 @@ reserving an average of 200-300 sessions per host system. Example: For an ~8,000 host network a source NAT pool of 32 IP addresses is recommended. -A pool of addresses can be defined by using a **-** in the `set nat source -rule [n] translation address` statement. +A pool of addresses can be defined by using a **-** in the +`set nat source rule [n] translation address` statement. .. code-block:: sh @@ -182,8 +182,8 @@ Which would generate the following NAT destination configuration: } .. note:: If forwarding traffic to a different port than it is arriving on, - you may also configure the translation port using `set nat destination rule - [n] translation port`. + you may also configure the translation port using + `set nat destination rule [n] translation port`. This establishes our Port Forward rule, but if we created a firewall policy it will likely block the traffic. @@ -270,7 +270,7 @@ NPTv6 stands for Network Prefix Translation. It's a form of NAT for IPv6. It's described in RFC6296_. NPTv6 is supported in linux kernel since version 3.13. Usage ------ +^^^^^ NPTv6 is very useful for IPv6 multihoming. Let's assume the following network configuration: @@ -295,7 +295,7 @@ their address to the right subnet when going through your router. * eth2 addr : 2001:db8:e2::1/48 VyOS Support ------------- +^^^^^^^^^^^^ NPTv6 support has been added in VyOS 1.2 (Crux) and is available through `nat nptv6` configuration nodes. @@ -324,5 +324,147 @@ Resulting in the following ip6tables rules: 0 0 SNPT all any eth2 fc00:dead:beef::/48 anywhere src-pfx fc00:dead:beef::/48 dst-pfx 2001:db8:e2::/48 0 0 RETURN all any any anywhere anywhere + +NAT before VPN +-------------- + +Some application service providers (ASPs) operate a VPN gateway to provide access to their internal resources, +and require that a connecting organisation translate all traffic to the service provider network to a source address provided by the ASP. + +Example Network +^^^^^^^^^^^^^^^ + +Here's one example of a network environment for an ASP. +The ASP requests that all connections from this company should come from 172.29.41.89 - an address that is assigned by the ASP and not in use at the customer site. + +.. figure:: _static/images/nat_befor_vpn_topology.png + :scale: 100 % + :alt: NAT before VPN Topology + + NAT before VPN Topology + + +Configuration +^^^^^^^^^^^^^ + +The required configuration can be broken down into 4 major pieces: + +* A dummy interface for the provider-assigned IP; +* NAT (specifically, Source NAT); +* IPSec IKE and ESP Groups; +* IPSec VPN tunnels. + + +Dummy interface +*************** + +The dummy interface allows us to have an equivalent of the Cisco IOS Loopback interface - a router-internal interface we can use for IP addresses the router must know about, +but which are not actually assigned to a real network. + +We only need a single step for this interface: + +.. code-block:: sh + + set interfaces dummy dum0 address '172.29.41.89/32' + +NAT Configuration +***************** + +.. code-block:: sh + + set nat source rule 110 description 'Internal to ASP' + set nat source rule 110 destination address '172.27.1.0/24' + set nat source rule 110 outbound-interface 'any' + set nat source rule 110 source address '192.168.43.0/24' + set nat source rule 110 translation address '172.29.41.89' + set nat source rule 120 description 'Internal to ASP' + set nat source rule 120 destination address '10.125.0.0/16' + set nat source rule 120 outbound-interface 'any' + set nat source rule 120 source address '192.168.43.0/24' + set nat source rule 120 translation address '172.29.41.89' + +IPSec IKE and ESP +***************** + + +The ASP has documented their IPSec requirements: + +* IKE Phase: + + * aes256 Encryption + * sha256 Hashes + +* ESP Phase: + + * aes256 Encryption + * sha256 Hashes + * DH Group 14 + + +Additionally, we want to use VPNs only on our eth1 interface (the external interface in the image above) + +.. code-block:: sh + + set vpn ipsec ike-group my-ike ikev2-reauth 'no' + set vpn ipsec ike-group my-ike key-exchange 'ikev1' + set vpn ipsec ike-group my-ike lifetime '7800' + set vpn ipsec ike-group my-ike proposal 1 dh-group '14' + set vpn ipsec ike-group my-ike proposal 1 encryption 'aes256' + set vpn ipsec ike-group my-ike proposal 1 hash 'sha256' + + set vpn ipsec esp-group my-esp compression 'disable' + set vpn ipsec esp-group my-esp lifetime '3600' + set vpn ipsec esp-group my-esp mode 'tunnel' + set vpn ipsec esp-group my-esp pfs 'disable' + set vpn ipsec esp-group my-esp proposal 1 encryption 'aes256' + set vpn ipsec esp-group my-esp proposal 1 hash 'sha256' + + set vpn ipsec ipsec-interfaces interface 'eth1' + +IPSec VPN Tunnels +***************** + +We'll use the IKE and ESP groups created above for this VPN. +Because we need access to 2 different subnets on the far side, we will need two different tunnels. +If you changed the names of the ESP group and IKE group in the previous step, make sure you use the correct names here too. + +.. code-block:: sh + + set vpn ipsec site-to-site peer 198.51.100.243 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 198.51.100.243 authentication pre-shared-secret 'PASSWORD IS HERE' + set vpn ipsec site-to-site peer 198.51.100.243 connection-type 'initiate' + set vpn ipsec site-to-site peer 198.51.100.243 default-esp-group 'my-esp' + set vpn ipsec site-to-site peer 198.51.100.243 ike-group 'my-ike' + set vpn ipsec site-to-site peer 198.51.100.243 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 198.51.100.243 local-address '203.0.113.46' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 0 remote prefix '172.27.1.0/24' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 local prefix '172.29.41.89/32' + set vpn ipsec site-to-site peer 198.51.100.243 tunnel 1 remote prefix '10.125.0.0/16' + +Testing and Validation +^^^^^^^^^^^^^^^^^^^^^^ + +If you've completed all the above steps you no doubt want to see if it's all working. + +Start by checking for IPSec SAs (Security Associations) with: + +.. code-block:: sh + + $ show vpn ipsec sa + + Peer ID / IP Local ID / IP + ------------ ------------- + 198.51.100.243 203.0.113.46 + + Tunnel State Bytes Out/In Encrypt Hash NAT-T A-Time L-Time Proto + ------ ----- ------------- ------- ---- ----- ------ ------ ----- + 0 up 0.0/0.0 aes256 sha256 no 1647 3600 all + 1 up 0.0/0.0 aes256 sha256 no 865 3600 all + +That looks good - we defined 2 tunnels and they're both up and running. + + + .. _RFC6296: https://tools.ietf.org/html/rfc6296 .. _ULAs: http://en.wikipedia.org/wiki/Unique_local_address diff --git a/docs/system/system-users.rst b/docs/system/system-users.rst index acffb974..a2e62024 100644 --- a/docs/system/system-users.rst +++ b/docs/system/system-users.rst @@ -108,3 +108,18 @@ networks when a link fails. .. code-block:: sh set system login radius-source-address 192.168.1.254 + +Login Banner +^^^^^^^^^^^^ + +You are able to set post-login or pre-login messages with the following lines: + +.. code-block:: sh + + set system login banner pre-login "UNAUTHORIZED USE OF THIS SYSTEM IS PROHIBITED\n" + set system login banner post-login "Welcome to VyOS" + +the **\\n** create a newline. + + + |