diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/appendix/migrate-from-vyatta.rst | 94 | ||||
| -rw-r--r-- | docs/configuration-overview.rst | 146 | ||||
| -rw-r--r-- | docs/history.rst | 24 | ||||
| -rw-r--r-- | docs/index.rst | 2 | ||||
| -rw-r--r-- | docs/install.rst | 11 | ||||
| -rw-r--r-- | docs/vpn/gre-ipsec.rst | 165 | ||||
| -rw-r--r-- | docs/vpn/index.rst | 1 |
7 files changed, 421 insertions, 22 deletions
diff --git a/docs/appendix/migrate-from-vyatta.rst b/docs/appendix/migrate-from-vyatta.rst new file mode 100644 index 00000000..e06890ad --- /dev/null +++ b/docs/appendix/migrate-from-vyatta.rst @@ -0,0 +1,94 @@ +.. _migrate_from_vyatta: + +Migrate from vyatta +=================== + +VyOS 1.x.x line aims to preserve backward compatibility and provide a safe upgrade path for existing Vyatta Core users. You may think of 1.0.0 as VC7.0. + +Vyatta release compatiblity +--------------------------- +Vyatta Core releases from **6.5** to **6.6** should be 100% compatible. + +Vyatta Core **6.4** and earlier may have incompatibilities. In **6.5** the "modify" firewall was removed and replaced with "set policy route" command family, and old config cannot be automatically converted. You will have to adapt it to post-6.5 syntax manually. + +.. NOTE:: + Also, in **6.5** remote access VPN interfaces were renamed from pppX to l2tpX and pptpX, so if you are using zone-policy in 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. The only thing is that is you want to verify image digital signature, you will have to add the public key. + +.. code-block:: sh + + vyatta@vyatta:~$ '''wget http://vyos.net/so3group_maintainers.key''' + Connecting to vyos.net (85.159.113.32:80) + so3group_maintainers 100% |*************************************************************************** + ********************************************************************| 3125 --:--:-- ETA + vyatta@vyatta:~$ '''sudo apt-key add so3group_maintainers.key''' + OK + vyatta@vyatta:~$ + +Next, we can add the VyOS image. + +Note that Vyatta doesn't support HTTP redirects for **add system image** and the http://mirror.vyos.net HTTP load-balancer links will not work. Instead, choose one of the `mirrors <https://wiki.vyos.net/wiki/Mirrors>`_ and get a direct link. + +This example uses 1.0.0 image, however, it's better to install the latest release. + +.. code-block:: sh + + 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 http://0.uk.mirrors.vyos.net/iso/release/1.0.0/vyos-1.0.0-amd64.iso + Trying to fetch ISO file from http://0.uk.mirrors.vyos.net/iso/release/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) + + vyatta@vyatta:~$ + +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 image. + +Note that future releases of VyOS may break compatibility with Vyatta. + + diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 3024c277..f7a3b078 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -63,9 +63,12 @@ The current configuration can be viewed using the show configuration command. } vyos@vyos:~$ -Because configuration changes are made using `set` and `delete` commands, the -commands to generate the active configuration can also be displayed using the -`show configuration commands` command. +By default the configuration is display'ed in a hierarchy like the example above, +this is only one of the possible ways to display the configuration. + +When the configuration is generated and the device is configured, these changes are added +with a corresponding set of `set` and `delete` commands, as for this you could also display +the current configuration using these `set` commands using the `show configuration commands` command. .. code-block:: sh @@ -85,28 +88,39 @@ commands to generate the active configuration can also be displayed using the set system syslog global facility protocols level 'debug' vyos@vyos:~$ -Configuration changes made do not take effect until committed using the commit -command in configuration mode. +Both these commands are for beeing executed when in operational mode, these commands does not work within the configuration mode. + +Navigating in Configuration Mode +--------------------------------- +When entering the configuration mode you are navigating inside the tree structure exported in the overview above, +to enter configuration mode enter the command `configure` when in operational mode .. code-block:: sh - vyos@vyos# commit + vyos@vyos$ configure [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - vyos@vyos:~$ + cyos@vyos# -In order to preserve configuration changes upon reboot, the configuration must -also be saved once applied. This is done using the save command in -configuration mode. +.. note:: Prompt changes from `$` to `#`. To exit configuration mode, type `exit`. -.. code-block:: sh +All commands executed here is relative to the configuration level you have entered, everything is possible to do from the top level +but commands will be quite lengthy when manually typing them. - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done +To change the current hierarchy level use the command: `edit` + +.. code-block:: sh + [edit] - vyos@vyos# + vyos@vyos# edit interfaces ethernet eth0 + + [edit interfaces ethernet eth0] + vyos@vyos# + +You are now in a sublevel relative to `interfaces ethernet eth0`, +all commands executed from this point on are relative to this sublevel. +to exit back to the top of the hierarchy use the `top` command or the `exit` command. +This brings you back to the top of the hierarchy. + The show command within configuration mode will show the current configuration indicating line changes with a + for additions and a - for deletions. @@ -136,6 +150,87 @@ indicating line changes with a + for additions and a - for deletions. [edit] vyos@vyos# +it is also possible to display all `set` commands within configuration mode using `show | commands` + +.. code-block:: sh + + vyos@vyos# show interfaces iethernet eth0 | commands + set address dhcp + set hw-id 00:0c:29:44:3b:0f + +these command is also relative to the level you are inside and only relevant configuration blocks will be displayed when entering a sub-level + +.. code-block:: sh + + [edit interfaces ethernet eth0] + vyos@vyos# show + address dhcp + hw-id 00:0c:29:44:3b:0f + +exiting from the configuration mode is done via the `exit` command from the top level, executing `exit` from within a sub-level takes you back to the top level. + +.. code-block:: sh + + [edit interfaces ethernet eth0] + vyos@vyos# exit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + vyos@vyos:~$ + + + + +Managing the configuration +-------------------------- + +The configuration is managed by the use of `set` and `delete` commands from within configuration mode +Configuration commands are flattend from the tree into 'one-liner' commands shown in `show configuration commands` from operation mode + +these commands are also relative to the level where they are executed and all redundant information from the current level is removed from the command entered + +.. code-block:: sh + + [edit] + vyos@vyos# set interface ethernet eth0 address 1.2.3.4/24 + + [edit interfaces ethernet eth0] + vyos@vyos# set address 1.2.3.4/24 + +These two commands are essential the same, just executed from different levels in the hierarchy + +To delete a configuration entry use the `delete` command, this also deletes all sub-levels under the current level you've specified in the `delete` command. +Deleting a entry could also mean to reset it back to its default value if the element is mandatory, in each case it will be removed from the configuration file + +.. code-block:: sh + + [edit interfaces ethernet eth0] + vyos@vyos# delete address 1.2.3.4/24 + +Configuration changes made do not take effect until committed using the commit +command in configuration mode. + +.. code-block:: sh + + vyos@vyos# commit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + vyos@vyos:~$ + +In order to preserve configuration changes upon reboot, the configuration must +also be saved once applied. This is done using the save command in +configuration mode. + +.. code-block:: sh + + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + [edit] + vyos@vyos# + + Configuration mode can not be exited while uncommitted changes exist. To exit configuration mode without applying changes, the exit discard command can be used. @@ -209,3 +304,20 @@ or TFTP. Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... ######################################################################## 100.0% Done + +Operational info from config mode +--------------------------------- + +When inside configuration mode you are not directly able to execute operational commands, +access to these commands are possible trough the use of the `run [command]` command. +from this command you will have access to everything accessable from operational mode, +Command completeion and syntax help with `?` and `[tab]` wil also work. + +.. code-block:: sh + + [edit] + vyos@vyos# run show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 0.0.0.0/0 u/u diff --git a/docs/history.rst b/docs/history.rst new file mode 100644 index 00000000..422d56c7 --- /dev/null +++ b/docs/history.rst @@ -0,0 +1,24 @@ +.. _history: + +VyOS History +================== + +VyOS is a Linux-based network operating system that provides software-based network routing, firewall, and VPN functionality. + +The VyOS project was started in late 2013 as a community fork of the `GPL <http://en.wikipedia.org/wiki/GNU_General_Public_License>`_ portions of Vyatta Core 6.6R1 with the goal of maintaining a free and open source network operating system in response to the decision to discontinue the community edition of Vyatta. Here everyone loves learning, older managers and new users. + +VyOS is primarily based on `Debian GNU/Linux <http://www.debian.org/>`_ and the `Quagga <http://www.nongnu.org/quagga/>`_ routing engine. Its configuration syntax and :ref:`cli` are loosely derived from Juniper JUNOS as modelled by the `XORP project <http://www.xorp.org/>`_ (which was the original routing engine Vyatta was based upon). +Vyatta changed to the Quagga routing engine for release 4.0. + +Vyos changed the routing enging to `FRRoution <https://frrouting.org/>`_ in version 1.2.0 + +**How it's different from other router distros?** + +- Unified command line interface in the style of hardware routers. +- Scriptable CLI +- Stateful configuration system: prepare changes and commit at once or discard, view previous revisions or rollback to them, archive revisions to remote server, execute hooks at commit time... +- Image-based upgrade: keep multiple versions on the same system and revert to previous image if something went wrong. +- Not just firewall and VPN: includes routing protocols such as BGP and OSPF and complex routing policy language. +- Runs on physical and virtual platforms alike: small x86 boards, big servers, KVM, Xen, VMWare, Hyper-V... +- Completely free and open source, with documented internal APIs and build procedures. +- Community driven: patches are welcome, all code, bugs, and nightly builds are public. diff --git a/docs/index.rst b/docs/index.rst index 7e27b0cc..58461850 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,6 +15,7 @@ as a router and firewall platform for cloud deployments. :caption: Contents: :includehidden: + history.rst install.rst cli.rst quick-start.rst @@ -43,6 +44,7 @@ as a router and firewall platform for cloud deployments. appendix/examples/index.rst appendix/commandtree/index.rst appendix/vyos-on-baremetal.rst + appendix/migrate-from-vyatta.rst .. toctree:: :maxdepth: 2 diff --git a/docs/install.rst b/docs/install.rst index d63365ec..7dc5a065 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -30,14 +30,15 @@ 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). + Support for this is removed from VyOS 1.2 (crux) and newer releases + + This installation method has 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 older systems installed that way though, they can be upgraded with ``add - system image``. In addition the ``install system`` command has been - removed in VyOS 1.2 (Crux). + system image``. To install VyOS, run ``install image``. @@ -189,4 +190,4 @@ Now you can verify signatures: 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 + Primary key fingerprint: 0694 A923 0F51 39BF 834B A458 FD22 0285 A0FE 6D7E diff --git a/docs/vpn/gre-ipsec.rst b/docs/vpn/gre-ipsec.rst new file mode 100644 index 00000000..946f7cd1 --- /dev/null +++ b/docs/vpn/gre-ipsec.rst @@ -0,0 +1,165 @@ +.. _gre-ipsec: + +Gre/IPsec +--------- + +**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 typical site-to-site setup and you need to add special configuration for it, or adjust the source address for outgoing traffic of your applications. GRE/IPsec has no such problem and is completely transparent for the 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:: + Note for vmware users! + Ensure that VMXNET3 adapters used, e1000 adapters have known issue with GRE processing + +#1 IPsec policy to match 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:: sh + + # GRE tunnel + set interfaces tunnel tun0 encapsulation gre + set interfaces tunnel tun0 local-ip 192.0.2.10 + set interfaces tunnel tun0 remote-ip 203.0.113.45 + set interfaces tunnel tun0 address 10.10.10.1/30 + + ## IPsec + set vpn ipsec ipsec-interfaces interface eth0 + + # 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 203.0.113.45 authentication mode pre-shared-secret + set vpn ipsec site-to-site peer 203.0.113.45 authentication pre-shared-secret MYSECRETKEY + + set vpn ipsec site-to-site peer 203.0.113.45 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 203.0.113.45 default-esp-group MyESPGroup + + set vpn ipsec site-to-site peer 203.0.113.45 local-address 192.0.2.10 + + # This will match all GRE traffic to the peer + set vpn ipsec site-to-site peer 203.0.113.45 tunnel 1 protocol gre + +On the RIGHT, setup by analogy and swap local and remote addresses. + + +#2 Source tunnel from loopbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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. + +**Setting up the GRE tunnel** + +On the LEFT: + +.. code-block:: sh + + set interfaces loopback lo 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 local-ip 192.168.99.1 + set interfaces tunnel tun0 remote-ip 192.168.99.2 + +On the RIGHT: + +.. code-block:: sh + + set interfaces loopback lo 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 local-ip 192.168.99.2 + set interfaces tunnel tun0 remote-ip 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 vpn rsa-key bits 2048". You may choose different length than 2048 of course. If your machine is a VM, generating it from /dev/random may take ages, so you may opt for "generate vpn rsa-key 2048 random /dev/urandom" instead. + +.. code-block:: sh + + vyos@left# run generate vpn rsa-key bits 2048 random /dev/urandom + Generating rsa-key to /config/ipsec.d/rsa-keys/localhost.key + + Your new local RSA key has been generated + The public portion of the key is: + + 0sAQO2335[long string here] + +Then on the opposite router, add the RSA key to your config. + +.. code-block:: sh + + set vpn rsa-keys rsa-key-name LEFT rsa-key KEYGOESHERE + +Now you are ready to setup IPsec. You'll need to use an ID instead of address for the peer on the dynamic side. + +On the LEFT (static address): + +.. code-block:: sh + + set vpn rsa-keys rsa-key-name RIGHT rsa-key <PUBLIC KEY FROM THE RIGHT> + + set vpn ipsec ipsec-interfaces 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 mode rsa + set vpn ipsec site-to-site peer @RIGHT authentication rsa-key-name 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:: sh + + set vpn rsa-keys rsa-key-name LEFT rsa-key <PUBLIC KEY FROM THE LEFT> + + set vpn ipsec ipsec-interfaces 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 192.0.2.10 authentication id @RIGHT + set vpn ipsec site-to-site peer 192.0.2.10 authentication mode rsa + set vpn ipsec site-to-site peer 192.0.2.10 authentication rsa-key-name LEFT + set vpn ipsec site-to-site peer 192.0.2.10 remote-id @LEFT + set vpn ipsec site-to-site peer 192.0.2.10 connection-type initiate + set vpn ipsec site-to-site peer 192.0.2.10 default-esp-group MyESPGroup + set vpn ipsec site-to-site peer 192.0.2.10 ike-group MyIKEGroup + set vpn ipsec site-to-site peer 192.0.2.10 local-address any + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 local prefix 192.168.99.2/32 # Additional loopback address on the local + set vpn ipsec site-to-site peer 192.0.2.10 tunnel 1 remote prefix 192.168.99.1/32 # Additional loopback address on the remote diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst index 956711ad..ffdf39a0 100644 --- a/docs/vpn/index.rst +++ b/docs/vpn/index.rst @@ -13,6 +13,7 @@ This chapter descriptes the available VPN services provided by VyOS. openvpn l2tp_ipsec site2site_ipsec + gre-ipsec dmvpn pptp wireguard |