summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/firewall.rst4
-rw-r--r--docs/index.rst1
-rw-r--r--docs/install.rst95
-rw-r--r--docs/nat.rst154
-rw-r--r--docs/system/system-users.rst15
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.
+
+
+
generated by cgit v1.2.3 (git 2.39.1) at 2025-10-31 06:24:23 +0000