diff options
| -rw-r--r-- | CONTRIBUTING.md | 65 | ||||
| -rw-r--r-- | docs/_static/images/apu4c4_rack_5.jpg | bin | 0 -> 2957985 bytes | |||
| -rw-r--r-- | docs/appendix/examples/azure-vpn-bgp.rst | 128 | ||||
| -rw-r--r-- | docs/appendix/examples/azure-vpn-dual-bgp.rst | 155 | ||||
| -rw-r--r-- | docs/appendix/examples/index.rst | 2 | ||||
| -rw-r--r-- | docs/appendix/vyos-on-baremetal.rst | 5 | ||||
| -rw-r--r-- | docs/configuration-overview.rst | 3 | ||||
| -rw-r--r-- | docs/contributing/vyos-api/index.rst | 7 | ||||
| -rw-r--r-- | docs/contributing/vyos-api/interface-config.rst | 263 | ||||
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/install.rst | 2 | ||||
| -rw-r--r-- | docs/routing/routing-policy.rst | 4 | ||||
| -rw-r--r-- | docs/vpn/openvpn.rst | 64 |
13 files changed, 677 insertions, 22 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 496659bb..7390c11f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,17 @@ # Contributor's Guide 1. fork the project on GitHub https://github.com/vyos/vyos-documentation -2. clone the fork -3. create a a new branch for your work. You can use a name that describes what you do. +2. clone the fork to your local machine ```shell - git checkout -b fix-vxlan-typo + $ git clone https://github.com/YOUR_USERNAME/vyos-documentation +3. cd to your new local directory vyos-documentation +4. create a a new branch for your work. You can use a name that describes what you do. + ```shell + $ git checkout -b fix-vxlan-typo ``` -4. make your changes. +5. make your changes. - Please check the documation, if you don't familiar with [sphinx-doc](http://http://www.sphinx-doc.org) or [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) + Please check the documentation if you aren't familiar with [sphinx-doc](http://http://www.sphinx-doc.org) or [reStructuredText](http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html) Note the following RFCs, which describe the reserved public IP addresses and autonomous system numbers for the documentation. [RFC5737](https://tools.ietf.org/html/rfc5737), [RFC3849](https://tools.ietf.org/html/rfc3849), [RFC5389](https://tools.ietf.org/html/rfc5398), [RFC7042](https://tools.ietf.org/html/rfc7042) @@ -23,25 +26,59 @@ Please don't use other public address space. +6. Check your changes by locally building the documentation + ```shell + $ cd docs + $ make html + ``` + Sphinx will build the html files in the docs/_build folder -5. add the modified files +7. add the modified files ```shell - git add path/to/filname + $ git add path/to/filname ``` or add all unstaged files ```shell - git add . + $ git add . ```` -6. commit your changes +8. commit your changes ```shell - git commit -m "rename vxlan set syntax" + $ git commit -m "rename vxlan set syntax" ``` -7. push your commits to your GitHub project: +9. push your commits to your GitHub project: ```shell - git push -u origin fix-vxlan-typo + $ git push -u origin fix-vxlan-typo ``` -8. Submit a pull request. +10. submit a pull request. In GitHub, visit the main repository and you should see a banner - suggesting to make a pull request. Fill out the form and describe what you do.
\ No newline at end of file + suggesting to make a pull request. Fill out the form and describe what you do. + +11. once pull resquests have been approved, you may want to locally update your forked repository too. First you'll have to add the remote upstream repository. + ```shell + $ git remote add upstream https://github.com/vyos/vyos-documentation.git + ``` + + Check your configured remote repositories. + ```shell + $ git remote -v + origin https://github.com/YOUR_USERNAME/vyos-documentation.git (fetch) + origin https://github.com/YOUR_USERNAME/vyos.documentation.git (push) + upstream https://github.com/vyos/vyos-documentation.git (fetch) + upstream https://github.com/vyos/vyos-documentation.git (push) + ``` + + Your remote repo on Github is called Origin, while the original repo you have forked is called Upstream. + + Now you can locally update your forked repo. + ```shell + $ git fetch upstream + $ git checkout master + $ git merge upstream/master + ``` + If you want to update your fork on Github too: + ```shell + $ git push origin master + ``` + diff --git a/docs/_static/images/apu4c4_rack_5.jpg b/docs/_static/images/apu4c4_rack_5.jpg Binary files differnew file mode 100644 index 00000000..534bbad6 --- /dev/null +++ b/docs/_static/images/apu4c4_rack_5.jpg diff --git a/docs/appendix/examples/azure-vpn-bgp.rst b/docs/appendix/examples/azure-vpn-bgp.rst new file mode 100644 index 00000000..818817ae --- /dev/null +++ b/docs/appendix/examples/azure-vpn-bgp.rst @@ -0,0 +1,128 @@ +.. _examples-azure-vpn-bgp: + +Route-Based Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) +------------------------------------------------------------ + +This guide shows an example of a route-based IKEv2 site-to-site VPN to +Azure using VTI and BGP for dynamic routing updates. + +Prerequisites +^^^^^^^^^^^^^ + +- A pair of Azure VNet Gateways deployed in active-passive + configuration with BGP enabled. + +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 + +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +Example +^^^^^^^ + ++---------------------------------------+---------------------+ +| WAN Interface | eth0 | ++---------------------------------------+---------------------+ +| On-premises address space | 10.10.0.0/16 | ++---------------------------------------+---------------------+ +| Azure address space | 10.0.0.0/16 | ++---------------------------------------+---------------------+ +| Vyos public IP | 198.51.100.3 | ++---------------------------------------+---------------------+ +| Vyos private IP | 10.10.0.5 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway public IP | 203.0.113.2 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway BGP IP | 10.0.0.4 | ++---------------------------------------+---------------------+ +| Pre-shared key | ch00s3-4-s3cur3-psk | ++---------------------------------------+---------------------+ +| Vyos ASN | 64499 | ++---------------------------------------+---------------------+ +| Azure ASN | 65540 | ++---------------------------------------+---------------------+ + +Vyos configuration +^^^^^^^^^^^^^^^^^^ + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +.. code-block:: sh + + set vpn ipsec esp-group AZURE compression 'disable' + set vpn ipsec esp-group AZURE lifetime '3600' + set vpn ipsec esp-group AZURE mode 'tunnel' + set vpn ipsec esp-group AZURE pfs 'dh-group2' + set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + + set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' + set vpn ipsec ike-group AZURE dead-peer-detection interval '15' + set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' + set vpn ipsec ike-group AZURE ikev2-reauth 'yes' + set vpn ipsec ike-group AZURE key-exchange 'ikev2' + set vpn ipsec ike-group AZURE lifetime '28800' + set vpn ipsec ike-group AZURE proposal 1 dh-group '2' + set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' + +- Enable IPsec on eth0 + +.. code-block:: sh + + set vpn ipsec ipsec-interfaces interface 'eth0' + +- Configure a VTI with a dummy IP address + +.. code-block:: sh + + set interfaces vti vti1 address '10.10.1.5/32' + set interfaces vti vti1 description 'Azure Tunnel' + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +.. code-block:: sh + + set firewall options interface vti1 adjust-mss 1350 + +- Configure the VPN tunnel + +.. code-block:: sh + + set vpn ipsec site-to-site peer 203.0.113.2 authentication id '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' + set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' + set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' + set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' + set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' + set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' + set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' + set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' + +- **Important**: Add an interface route to reach Azure's BGP listener + +.. code-block:: sh + + set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 + +- Configure your BGP settings + +.. code-block:: sh + + set protocols bgp 64499 neighbor 10.0.0.4 remote-as '65540' + set protocols bgp 64499 neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' + set protocols bgp 64499 neighbor 10.0.0.4 timers holdtime '30' + set protocols bgp 64499 neighbor 10.0.0.4 timers keepalive '10' + +- **Important**: Disable connected check \ + +.. code-block:: sh + + set protocols bgp 64499 neighbor 10.0.0.4 disable-connected-check diff --git a/docs/appendix/examples/azure-vpn-dual-bgp.rst b/docs/appendix/examples/azure-vpn-dual-bgp.rst new file mode 100644 index 00000000..4cbcde3b --- /dev/null +++ b/docs/appendix/examples/azure-vpn-dual-bgp.rst @@ -0,0 +1,155 @@ +.. _examples-azure-vpn-dual-bgp: + +Route-Based Redundant Site-to-Site VPN to Azure (BGP over IKEv2/IPsec) +---------------------------------------------------------------------- + +This guide shows an example of a redundant (active-active) route-based IKEv2 +site-to-site VPN to Azure using VTI +and BGP for dynamic routing updates. + +Prerequisites +^^^^^^^^^^^^^ + +- A pair of Azure VNet Gateways deployed in active-passive + configuration with BGP enabled. + +- A local network gateway deployed in Azure representing + the Vyos device, matching the below Vyos settings except for + address space, which only requires the Vyos private IP, in + this example 10.10.0.5/32 + +- A connection resource deployed in Azure linking the + Azure VNet gateway and the local network gateway representing + the Vyos device. + +Example +^^^^^^^ + ++---------------------------------------+---------------------+ +| WAN Interface | eth0 | ++---------------------------------------+---------------------+ +| On-premises address space | 10.10.0.0/16 | ++---------------------------------------+---------------------+ +| Azure address space | 10.0.0.0/16 | ++---------------------------------------+---------------------+ +| Vyos public IP | 198.51.100.3 | ++---------------------------------------+---------------------+ +| Vyos private IP | 10.10.0.5 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway 1 public IP | 203.0.113.2 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway 2 public IP | 203.0.113.3 | ++---------------------------------------+---------------------+ +| Azure VNet Gateway BGP IP | 10.0.0.4,10.0.0.5 | ++---------------------------------------+---------------------+ +| Pre-shared key | ch00s3-4-s3cur3-psk | ++---------------------------------------+---------------------+ +| Vyos ASN | 64499 | ++---------------------------------------+---------------------+ +| Azure ASN | 65540 | ++---------------------------------------+---------------------+ + +Vyos configuration +^^^^^^^^^^^^^^^^^^ + +- Configure the IKE and ESP settings to match a subset + of those supported by Azure: + +.. code-block:: sh + + set vpn ipsec esp-group AZURE compression 'disable' + set vpn ipsec esp-group AZURE lifetime '3600' + set vpn ipsec esp-group AZURE mode 'tunnel' + set vpn ipsec esp-group AZURE pfs 'dh-group2' + set vpn ipsec esp-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec esp-group AZURE proposal 1 hash 'sha1' + + set vpn ipsec ike-group AZURE dead-peer-detection action 'restart' + set vpn ipsec ike-group AZURE dead-peer-detection interval '15' + set vpn ipsec ike-group AZURE dead-peer-detection timeout '30' + set vpn ipsec ike-group AZURE ikev2-reauth 'yes' + set vpn ipsec ike-group AZURE key-exchange 'ikev2' + set vpn ipsec ike-group AZURE lifetime '28800' + set vpn ipsec ike-group AZURE proposal 1 dh-group '2' + set vpn ipsec ike-group AZURE proposal 1 encryption 'aes256' + set vpn ipsec ike-group AZURE proposal 1 hash 'sha1' + +- Enable IPsec on eth0 + +.. code-block:: sh + + set vpn ipsec ipsec-interfaces interface 'eth0' + +- Configure two VTIs with a dummy IP address each + +.. code-block:: sh + + set interfaces vti vti1 address '10.10.1.5/32' + set interfaces vti vti1 description 'Azure Primary Tunnel' + + set interfaces vti vti2 address '10.10.1.6/32' + set interfaces vti vti2 description 'Azure Secondary Tunnel' + +- Clamp the VTI's MSS to 1350 to avoid PMTU blackholes. + +.. code-block:: sh + + set firewall options interface vti1 adjust-mss 1350 + set firewall options interface vti2 adjust-mss 1350 + +- Configure the VPN tunnels + +.. code-block:: sh + + set vpn ipsec site-to-site peer 203.0.113.2 authentication id '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.2 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.2 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' + set vpn ipsec site-to-site peer 203.0.113.2 authentication remote-id '203.0.113.2' + set vpn ipsec site-to-site peer 203.0.113.2 connection-type 'respond' + set vpn ipsec site-to-site peer 203.0.113.2 description 'AZURE PRIMARY TUNNEL' + set vpn ipsec site-to-site peer 203.0.113.2 ike-group 'AZURE' + set vpn ipsec site-to-site peer 203.0.113.2 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 203.0.113.2 local-address '10.10.0.5' + set vpn ipsec site-to-site peer 203.0.113.2 vti bind 'vti1' + set vpn ipsec site-to-site peer 203.0.113.2 vti esp-group 'AZURE' + + set vpn ipsec site-to-site peer 203.0.113.3 authentication id '198.51.100.3' + set vpn ipsec site-to-site peer 203.0.113.3 authentication mode 'pre-shared-secret' + set vpn ipsec site-to-site peer 203.0.113.3 authentication pre-shared-secret 'ch00s3-4-s3cur3-psk' + set vpn ipsec site-to-site peer 203.0.113.3 authentication remote-id '203.0.113.3' + set vpn ipsec site-to-site peer 203.0.113.3 connection-type 'respond' + set vpn ipsec site-to-site peer 203.0.113.3 description 'AZURE SECONDARY TUNNEL' + set vpn ipsec site-to-site peer 203.0.113.3 ike-group 'AZURE' + set vpn ipsec site-to-site peer 203.0.113.3 ikev2-reauth 'inherit' + set vpn ipsec site-to-site peer 203.0.113.3 local-address '10.10.0.5' + set vpn ipsec site-to-site peer 203.0.113.3 vti bind 'vti2' + set vpn ipsec site-to-site peer 203.0.113.3 vti esp-group 'AZURE' + +- **Important**: Add an interface route to reach both Azure's BGP listeners + +.. code-block:: sh + + set protocols static interface-route 10.0.0.4/32 next-hop-interface vti1 + set protocols static interface-route 10.0.0.5/32 next-hop-interface vti2 + +- Configure your BGP settings + +.. code-block:: sh + + set protocols bgp 64499 neighbor 10.0.0.4 remote-as '65540' + set protocols bgp 64499 neighbor 10.0.0.4 address-family ipv4-unicast soft-reconfiguration 'inbound' + set protocols bgp 64499 neighbor 10.0.0.4 timers holdtime '30' + set protocols bgp 64499 neighbor 10.0.0.4 timers keepalive '10' + + set protocols bgp 64499 neighbor 10.0.0.5 remote-as '65540' + set protocols bgp 64499 neighbor 10.0.0.5 address-family ipv4-unicast soft-reconfiguration 'inbound' + set protocols bgp 64499 neighbor 10.0.0.5 timers holdtime '30' + set protocols bgp 64499 neighbor 10.0.0.5 timers keepalive '10' + +- **Important**: Disable connected check, otherwise the routes learned + from Azure will not be imported into the routing table. + +.. code-block:: sh + + set protocols bgp 64499 neighbor 10.0.0.4 disable-connected-check + set protocols bgp 64499 neighbor 10.0.0.5 disable-connected-check diff --git a/docs/appendix/examples/index.rst b/docs/appendix/examples/index.rst index a77ee380..f9689851 100644 --- a/docs/appendix/examples/index.rst +++ b/docs/appendix/examples/index.rst @@ -13,3 +13,5 @@ This chapter contains various configuration Examples zone-policy bgp-ipv6-unnumbered ospf-unnumbered + azure-vpn-bgp + azure-vpn-dual-bgp diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/appendix/vyos-on-baremetal.rst index 66b68c09..325c629a 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/appendix/vyos-on-baremetal.rst @@ -215,6 +215,11 @@ Rack Mount :scale: 25 % :alt: APU4C4 rack module #2 +.. figure:: /_static/images/apu4c4_rack_5.jpg + :scale: 25 % + :alt: APU4C4 rack module #3 with PSU + + Desktop ^^^^^^^ diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst index 1ed0938f..bd1ab8d8 100644 --- a/docs/configuration-overview.rst +++ b/docs/configuration-overview.rst @@ -135,8 +135,7 @@ To change the current hierarchy level use the command: `edit` You are now in a sublevel relative to `interfaces ethernet eth0`, all commands executed from this point on are relative to this sublevel. -Use either the `top` or `exit` command to go back to the top of the hierarchy. - +Use either the `top` or `exit` command to go back to the top of the hierarchy. You can also use the `up` command to move only one level up at a time. The `show` command within configuration mode will show the working configuration indicating line changes with `+` for additions, `>` for replacements and `-` for deletions. diff --git a/docs/contributing/vyos-api/index.rst b/docs/contributing/vyos-api/index.rst new file mode 100644 index 00000000..353401b0 --- /dev/null +++ b/docs/contributing/vyos-api/index.rst @@ -0,0 +1,7 @@ +.. _vyos-api_index: + +.. toctree:: + :maxdepth: 2 + :hidden: + + interface-config diff --git a/docs/contributing/vyos-api/interface-config.rst b/docs/contributing/vyos-api/interface-config.rst new file mode 100644 index 00000000..f4e06c14 --- /dev/null +++ b/docs/contributing/vyos-api/interface-config.rst @@ -0,0 +1,263 @@ +.. _vyos_api: + +VyOS API Classes +================ + + +Interface Config +---------------- + +This class contains the code to configure a network interfaces. +Exceptions are being send to stdout if the debug flag is set within the environment, via ``export DEBUG=1``. +It shows exception for executed commands and parses andd displays the exception output in a structured form. +Value errors are always displayed, regardless of the presence of the ``DEBUG`` variable. + + +Example how the ``DEBUG`` variable can be used. + .. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + a = Interface("wg01", "fnord") + print (a.set_link_state("up")) + + + .. code-block:: sh + + root@vyos:/home/vyos# ./example_script.py + RTNETLINK answers: Operation not supported + + export DEBUG=1 + root@vyos:/home/vyos# ./example_script.py + + Exception raised: + command: ['ip link add dev wg01 type fnord'] + error code: 2 + subprocess output: RTNETLINK answers: Operation not supported + + +Interface(interfacename, type=None) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The interfacename is mandatory, if it is a virtual interface such as a wireguard interface or vlan, veth etc., the type can be assigned and the device is being created if it is a valid device. + +existing device: + .. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + interface_instance = Interface("eth2") + +non-existing device which needs to be created: + .. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + interface_instance = Interface("wg01", "wireguard") + +If a device creation has been successful, the return code is ``0`` otherwise ``None``. + +Interface alias +^^^^^^^^^^^^^^^ +An interfaces ifalias variable is empty by default, but the variable is used for example by snmp. The parameter is optional and if not set, the default behavior is to use the interfacename of the instance, if set it uses the name set in the parameter. + +.. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + interface_instance = Interface("eth2") + interface_instance.ifalias = "interface_alias" + print (interface_instance.ifalias) + + +.. code-block:: sh + + 4: eth2: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast state DOWN mode DEFAULT group default qlen 1000 + link/ether 08:00:27:70:9c:a3 brd ff:ff:ff:ff:ff:ff + alias interface_alias + +del_alias() +~~~~~~~~~~~ +Removes any content from the ifalias variable. + +Interface link state +^^^^^^^^^^^^^^^^^^^^ +Sets an interface state either to adminitrativly up or down, regardless of the real connection status. If called without parameter, the default function is up, valid parameters are ``up`` or ``down``. + + +.. code-block:: sh + + ip link show dev eth2 + 4: eth2: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast state DOWN mode DEFAULT group default qlen 1000 + + +.. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + interface_instance = Interface("eth2") + interface_instance.linkstate = 'up' + print (interface_instance.linkstate) + print (interface_instance.linkstate) + + +.. code-block:: sh + + ip link show dev eth2 + 4: eth2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000 + +remove_interface() +^^^^^^^^^^^^^^^^^^ +Removes an interface from the system, given as parameter of the objects instance. + +Interface macaddress +^^^^^^^^^^^^^^^^^^^^ +Sets the mac address on a network interface. + +.. code-block:: sh + + interface_instance.macaddr = '08:00:27:0e:6d:16' + ''' show current mac address set on the interface ''' + print(interface_instance.macaddr) + +Interface MTU +^^^^^^^^^^^^^ +Sets the MTU on a network interface. + +.. code-block:: sh + + interface_instance.mtu = 9000 + ''' read mtu from interface ''' + print(interface_instance.mtu) + + +add_ipv4_addr(ipaddr=[]): +^^^^^^^^^^^^^^^^^^^^^^^^^ +Adds IPv4 addresses given as parameter. + +.. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + ips = ['10.100.100.1/24', '10.100.100.2/24', '10.100.100.3/24'] + interface_instance = Interface("eth2") + interface_instance.add_ipv4_addr(ips) + +.. code-block:: sh + + ip -4 -br addr sh dev eth2 + eth2 UP 10.100.100.1/24 10.100.100.2/24 10.100.100.3/24 + + +del_ipv4_addr(ipaddr=[]) +^^^^^^^^^^^^^^^^^^^^^^^^ +Removes the IPs given in the parameter ``ipaddr``. + +def get_ipv4_addr() +^^^^^^^^^^^^^^^^^^^ +Returns a list of all IPv4 addresses of an interface. + + +.. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + interface_instance = Interface("eth2") + ips = interface_instance.get_ipv4_addr() + print(ips) + +.. code-block:: sh + + ['10.100.100.1', '10.100.100.2', '10.100.100.3'] + + +set_dhcpv4() +^^^^^^^^^^^^ +Starts dhclient and sends DHCPREQUEST messages on the interface. + +del_dhcpv4() +^^^^^^^^^^^^ +Stops dhclient on the interface. + +get_dhcpv4() +^^^^^^^^^^^^ +Returns the pid of the dhclient process, if none is runing `False` is being returned and the message ``no dhcp client running on interface <interface>`` displayed on stdout. + +add_ipv6_addr(ipaddr=[]) +^^^^^^^^^^^^^^^^^^^^^^^^ +Adds IPv6 addresses given as parameter. + +.. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + ips = ['2001:db8:dead::1/64', '2001:db8:beaf::1/64', '2001:db8:cafe::1/64'] + interface_instance = Interface("eth2") + interface_instance.add_ipv6_addr(ips) + +.. code-block:: sh + + ip -6 -br addr sh dev eth2 + eth2 UP 2001:db8:cafe::1/64 2001:db8:beaf::1/64 2001:db8:dead::1/64 fe80::a00:27ff:fe70:9ca3/64 + +del_ipv6_addr(ipaddr=[]) +^^^^^^^^^^^^^^^^^^^^^^^^ +Removes the IPv6 addresses given via the paramater ``ipaddr``. + +get_ipv6_addr() +^^^^^^^^^^^^^^^ +Returns all IPv6 addresse set on the interface. + +.. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + interface_instance = Interface("eth2") + ips = interface_instance.get_ipv6_addr() + print(ips) + +.. code-block:: sh + + ['2001:db8:cafe::1', '2001:db8:beaf::1', '2001:db8:dead::1', 'fe80::a00:27ff:fe70:9ca3'] + + +set_dhcpv6() +^^^^^^^^^^^^ +It enables stateful IPv6 deployments on the given interface. The interface will stop to listen to route annoncements (RA's) and requests that parameter via dhcpv6. +DHCPv4 and DHCPv6 can be configured simultaniously on the interface. + +.. code-block:: sh + + #!/usr/bin/python3 + + from vyos.interfaceconfig import Interface + + interface_instance = Interface("eth2") + interface_instance.set_dhcpv4() + interface_instance.set_dhcpv6() + +del_dhcpv6() +^^^^^^^^^^^^ +Stops dhclient and starts listen and acceptiing RA's again. + +get_dhcpv6() +^^^^^^^^^^^^ +Returns the pid of the running dhclient process or None if it doesn't exist. + diff --git a/docs/index.rst b/docs/index.rst index 58461850..20a7bcbf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -53,5 +53,6 @@ as a router and firewall platform for cloud deployments. build-vyos.rst contributing/index.rst + contributing/vyos-api/index.rst diff --git a/docs/install.rst b/docs/install.rst index 22e5061e..ba311a41 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -123,7 +123,7 @@ GPG verification As you have our public key, you just need the signature of the software you want to verify. -.. note:: **In order to get the signature, go to your web browser and append *.asc* to the URL of your dowloaded VyOS image**. You will download a small *.asc* file, that's the signature of your image. +.. note:: **In order to get the signature, go to your web browser and append .asc to the URL of your dowloaded VyOS image**. You will download a small *.asc* file, that's the signature of your image. So finally you can verify the authenticity of your image. diff --git a/docs/routing/routing-policy.rst b/docs/routing/routing-policy.rst index 253dd980..f1b7d778 100644 --- a/docs/routing/routing-policy.rst +++ b/docs/routing/routing-policy.rst @@ -22,8 +22,8 @@ Routing Policy Example set policy route-map setmet rule 2 set as-path-prepend '2 2 2' #Apply policy to BGP - set protocols bgp 1 neighbor 1.1.1.2 route-map import 'setmet' - set protocols bgp 1 neighbor 1.1.1.2 soft-reconfiguration 'inbound' <<<< *** + set protocols bgp 1 neighbor 1.1.1.2 address-family ipv4-unicast route-map import 'setmet' + set protocols bgp 1 neighbor 1.1.1.2 address-family ipv4-unicast soft-reconfiguration 'inbound' <<<< *** *** get policy update without bouncing the neighbor diff --git a/docs/vpn/openvpn.rst b/docs/vpn/openvpn.rst index 5a269b43..b56d6c68 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/vpn/openvpn.rst @@ -223,8 +223,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 @@ -263,7 +267,7 @@ The required config file may look like: </Authorization> Active Directory -**************** +================ Despite the fact that AD is a superset of LDAP @@ -347,3 +351,57 @@ 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 |
