diff options
| -rw-r--r-- | .github/styles/Google/AMPM.yml (renamed from ci/vale/Google/AMPM.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Acronyms.yml (renamed from ci/vale/Google/Acronyms.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Colons.yml (renamed from ci/vale/Google/Colons.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Contractions.yml (renamed from ci/vale/Google/Contractions.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/DateFormat.yml (renamed from ci/vale/Google/DateFormat.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Ellipses.yml (renamed from ci/vale/Google/Ellipses.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/EmDash.yml (renamed from ci/vale/Google/EmDash.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/EnDash.yml (renamed from ci/vale/Google/EnDash.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Exclamation.yml (renamed from ci/vale/Google/Exclamation.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/FirstPerson.yml (renamed from ci/vale/Google/FirstPerson.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Gender.yml (renamed from ci/vale/Google/Gender.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/GenderBias.yml (renamed from ci/vale/Google/GenderBias.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/HeadingPunctuation.yml (renamed from ci/vale/Google/HeadingPunctuation.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Headings.yml (renamed from ci/vale/Google/Headings.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Hyphens.yml (renamed from ci/vale/Google/Hyphens.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Latin.yml (renamed from ci/vale/Google/Latin.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/LyHyphens.yml (renamed from ci/vale/Google/LyHyphens.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/OptionalPlurals.yml (renamed from ci/vale/Google/OptionalPlurals.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Ordinal.yml (renamed from ci/vale/Google/Ordinal.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/OxfordComma.yml (renamed from ci/vale/Google/OxfordComma.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Parens.yml (renamed from ci/vale/Google/Parens.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Passive.yml (renamed from ci/vale/Google/Passive.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Periods.yml (renamed from ci/vale/Google/Periods.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Quotes.yml (renamed from ci/vale/Google/Quotes.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Ranges.yml (renamed from ci/vale/Google/Ranges.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Semicolons.yml (renamed from ci/vale/Google/Semicolons.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Slang.yml (renamed from ci/vale/Google/Slang.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Spacing.yml (renamed from ci/vale/Google/Spacing.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Spelling.yml (renamed from ci/vale/Google/Spelling.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Units.yml (renamed from ci/vale/Google/Units.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/Will.yml (renamed from ci/vale/Google/Will.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/WordList.yml (renamed from ci/vale/Google/WordList.yml) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/meta.json (renamed from ci/vale/Google/meta.json) | 0 | ||||
| -rw-r--r-- | .github/styles/Google/vocab.txt (renamed from ci/vale/Google/vocab.txt) | 0 | ||||
| -rw-r--r-- | .github/styles/VyOS/Terminology.yml (renamed from ci/vale/VyOS/Terminology.yml) | 0 | ||||
| -rw-r--r-- | .github/vyos-linter.py | 177 | ||||
| -rw-r--r-- | .github/workflows/main.yml | 32 | ||||
| -rw-r--r-- | .github/workflows/submodules.yml | 32 | ||||
| -rw-r--r-- | .gitignore | 8 | ||||
| -rw-r--r-- | .gitmodules | 4 | ||||
| -rw-r--r-- | .vale | 34 | ||||
| -rw-r--r-- | Pipfile | 14 | ||||
| -rw-r--r-- | docs/.gitignore | 1 | ||||
| -rw-r--r-- | docs/_ext/test-coverage.py | 351 | ||||
| -rw-r--r-- | docs/_include/draw.io/pbr_example_1.drawio (renamed from docs/draw.io/pbr_example_1.drawio) | 0 | ||||
| -rw-r--r-- | docs/_include/draw.io/vpn_s2s_ikev2.drawio (renamed from docs/draw.io/vpn_s2s_ikev2.drawio) | 0 | ||||
| -rw-r--r-- | docs/appendix/releasenotes.rst | 358 | ||||
| -rw-r--r-- | docs/appendix/troubleshooting.rst | 385 | ||||
| -rw-r--r-- | docs/automation/command-scripting.rst (renamed from docs/commandscripting.rst) | 0 | ||||
| -rw-r--r-- | docs/automation/index.rst | 15 | ||||
| -rw-r--r-- | docs/changelog/1.2.1.rst | 52 | ||||
| -rw-r--r-- | docs/changelog/1.2.2.rst | 46 | ||||
| -rw-r--r-- | docs/changelog/1.2.3.rst | 62 | ||||
| -rw-r--r-- | docs/changelog/1.2.4.rst | 77 | ||||
| -rw-r--r-- | docs/changelog/1.2.5.rst | 70 | ||||
| -rw-r--r-- | docs/changelog/1.2.6.rst | 106 | ||||
| -rw-r--r-- | docs/changelog/index.rst | 18 | ||||
| -rw-r--r-- | docs/cli.rst | 743 | ||||
| -rw-r--r-- | docs/commandtree/configmode.rst (renamed from docs/appendix/commandtree/configmode.rst) | 0 | ||||
| -rw-r--r-- | docs/commandtree/index.rst (renamed from docs/appendix/commandtree/index.rst) | 0 | ||||
| -rw-r--r-- | docs/commandtree/operationmode.rst (renamed from docs/appendix/commandtree/operationmode.rst) | 0 | ||||
| -rw-r--r-- | docs/conf.py | 2 | ||||
| -rw-r--r-- | docs/configexamples/azure-vpn-bgp.rst (renamed from docs/appendix/examples/azure-vpn-bgp.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/azure-vpn-dual-bgp.rst (renamed from docs/appendix/examples/azure-vpn-dual-bgp.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/bgp-ipv6-unnumbered.rst (renamed from docs/appendix/examples/bgp-ipv6-unnumbered.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/dhcp-relay-through-gre-bridge.rst (renamed from docs/appendix/examples/dhcp-relay-through-gre-bridge.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/dmvpn.rst (renamed from docs/appendix/examples/dmvpn.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/index.rst (renamed from docs/appendix/examples/index.rst) | 11 | ||||
| -rw-r--r-- | docs/configexamples/ospf-unnumbered.rst (renamed from docs/appendix/examples/ospf-unnumbered.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/tunnelbroker-ipv6.rst (renamed from docs/appendix/examples/tunnelbroker-ipv6.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/wan-load-balancing.rst (renamed from docs/appendix/examples/wan-load-balancing.rst) | 0 | ||||
| -rw-r--r-- | docs/configexamples/zone-policy.rst (renamed from docs/appendix/examples/zone-policy.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration-overview.rst | 730 | ||||
| -rw-r--r-- | docs/configuration/firewall/index.rst (renamed from docs/firewall.rst) | 76 | ||||
| -rw-r--r-- | docs/configuration/highavailability/index.rst (renamed from docs/high-availability.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/index.rst | 22 | ||||
| -rw-r--r-- | docs/configuration/interfaces/bonding.rst (renamed from docs/interfaces/bonding.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/interfaces/bridge.rst (renamed from docs/interfaces/bridging.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/interfaces/dummy.rst (renamed from docs/interfaces/dummy.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/interfaces/ethernet.rst | 263 | ||||
| -rw-r--r-- | docs/configuration/interfaces/index.rst (renamed from docs/interfaces/addresses.rst) | 21 | ||||
| -rw-r--r-- | docs/configuration/interfaces/l2tpv3.rst (renamed from docs/interfaces/l2tpv3.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/interfaces/openvpn.rst (renamed from docs/vpn/openvpn.rst) | 29 | ||||
| -rw-r--r-- | docs/configuration/interfaces/tunnel.rst (renamed from docs/interfaces/tunnel.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/interfaces/vxlan.rst (renamed from docs/interfaces/vxlan.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireguard.rst (renamed from docs/vpn/wireguard.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/interfaces/wireless.rst (renamed from docs/interfaces/wireless.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/loadbalancing/index.rst (renamed from docs/load-balancing.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/nat/index.rst (renamed from docs/nat.rst) | 2 | ||||
| -rw-r--r-- | docs/configuration/policy/index.rst (renamed from docs/routing/pbr.rst) | 64 | ||||
| -rw-r--r-- | docs/configuration/protocols/bgp.rst (renamed from docs/routing/bgp.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/protocols/igmp.rst (renamed from docs/routing/multicast.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/protocols/index.rst (renamed from docs/routing/index.rst) | 12 | ||||
| -rw-r--r-- | docs/configuration/protocols/ospf.rst (renamed from docs/routing/ospf.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/protocols/rip.rst (renamed from docs/routing/rip.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/protocols/static.rst (renamed from docs/routing/arp.rst) | 32 | ||||
| -rw-r--r-- | docs/configuration/service/broadcast-relay.rst (renamed from docs/services/udp-broadcast-relay.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/conntrack-sync.rst (renamed from docs/services/conntrack.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/dhcp-relay.rst (renamed from docs/services/dhcp-relay.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/dhcp-server.rst (renamed from docs/services/dhcpv6.rst) | 139 | ||||
| -rw-r--r-- | docs/configuration/service/dns.rst (renamed from docs/services/dynamic-dns.rst) | 74 | ||||
| -rw-r--r-- | docs/configuration/service/index.rst | 21 | ||||
| -rw-r--r-- | docs/configuration/service/lldp.rst (renamed from docs/services/lldp.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/mdns.rst (renamed from docs/services/mdns-repeater.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/pppoe-server.rst (renamed from docs/services/pppoe-server.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/references.rst (renamed from docs/services/references.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/snmp.rst (renamed from docs/services/snmp.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/ssh.rst (renamed from docs/services/ssh.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/tftp-server.rst (renamed from docs/services/tftp.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/service/webproxy.rst (renamed from docs/services/webproxy.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/console.rst (renamed from docs/system/serialconsole.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/eventhandler.rst (renamed from docs/system/eventhandler.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/flow-accounting.rst (renamed from docs/system/flowaccounting.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/host-information.rst (renamed from docs/system/host-information.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/index.rst (renamed from docs/system/index.rst) | 17 | ||||
| -rw-r--r-- | docs/configuration/system/ip.rst | 75 | ||||
| -rw-r--r-- | docs/configuration/system/ipv6.rst (renamed from docs/routing/ip-commands.rst) | 81 | ||||
| -rw-r--r-- | docs/configuration/system/login.rst (renamed from docs/system/login-users.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/name-server.rst (renamed from docs/system/system-dns.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/ntp.rst (renamed from docs/system/ntp.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/syslog.rst (renamed from docs/system/syslog.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/task-scheduler.rst (renamed from docs/system/task-scheduler.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/system/time-zone.rst (renamed from docs/system/time-zone.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/trafficpolicy/index.rst (renamed from docs/qos.rst) | 6 | ||||
| -rw-r--r-- | docs/configuration/vpn/dmvpn.rst (renamed from docs/vpn/dmvpn.rst) | 2 | ||||
| -rw-r--r-- | docs/configuration/vpn/index.rst (renamed from docs/vpn/index.rst) | 4 | ||||
| -rw-r--r-- | docs/configuration/vpn/ipsec.rst (renamed from docs/vpn/gre-ipsec.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/vpn/l2tp.rst (renamed from docs/vpn/l2tp.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/vpn/pptp.rst (renamed from docs/vpn/pptp.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/vpn/references.rst (renamed from docs/vpn/references.rst) | 0 | ||||
| -rw-r--r-- | docs/configuration/vpn/site2site_ipsec.rst (renamed from docs/vpn/site2site_ipsec.rst) | 2 | ||||
| -rw-r--r-- | docs/configuration/zonepolicy/index.rst | 9 | ||||
| -rw-r--r-- | docs/contributing/index.rst | 13 | ||||
| -rw-r--r-- | docs/contributing/issues-features.rst (renamed from docs/contributing/issues_features.rst) | 0 | ||||
| -rw-r--r-- | docs/copyright.rst | 19 | ||||
| -rw-r--r-- | docs/documentation.rst (renamed from docs/contributing/documentation.rst) | 0 | ||||
| -rw-r--r-- | docs/index.rst | 90 | ||||
| -rw-r--r-- | docs/installation/cloud/index.rst | 9 | ||||
| -rw-r--r-- | docs/installation/image.rst (renamed from docs/image-mgmt.rst) | 78 | ||||
| -rw-r--r-- | docs/installation/index.rst | 17 | ||||
| -rw-r--r-- | docs/installation/install.rst (renamed from docs/install.rst) | 2 | ||||
| -rw-r--r-- | docs/installation/migrate-from-vyatta.rst (renamed from docs/appendix/migrate-from-vyatta.rst) | 0 | ||||
| -rw-r--r-- | docs/installation/update.rst | 79 | ||||
| -rw-r--r-- | docs/installation/virtual/gns3.rst (renamed from docs/appendix/vyos-on-gns3.rst) | 0 | ||||
| -rw-r--r-- | docs/installation/virtual/index.rst | 9 | ||||
| -rw-r--r-- | docs/installation/virtual/vmware.rst (renamed from docs/appendix/vyos-on-vmware.rst) | 0 | ||||
| -rw-r--r-- | docs/installation/vyos-on-baremetal.rst (renamed from docs/appendix/vyos-on-baremetal.rst) | 0 | ||||
| -rw-r--r-- | docs/interfaces/ethernet.rst | 72 | ||||
| -rw-r--r-- | docs/interfaces/index.rst | 63 | ||||
| -rw-r--r-- | docs/interfaces/pppoe.rst | 82 | ||||
| -rw-r--r-- | docs/interfaces/qinq.rst | 58 | ||||
| -rw-r--r-- | docs/interfaces/vlan.rst | 47 | ||||
| -rw-r--r-- | docs/introducing/about.rst (renamed from docs/about.rst) | 4 | ||||
| -rw-r--r-- | docs/introducing/history.rst (renamed from docs/history.rst) | 48 | ||||
| -rw-r--r-- | docs/operation/boot-options.rst (renamed from docs/system/boot-options.rst) | 0 | ||||
| -rw-r--r-- | docs/operation/index.rst | 9 | ||||
| -rw-r--r-- | docs/routing/mss-clamp.rst | 64 | ||||
| -rw-r--r-- | docs/routing/routing-policy.rst | 59 | ||||
| -rw-r--r-- | docs/routing/static.rst | 30 | ||||
| -rw-r--r-- | docs/services/dhcp.rst | 138 | ||||
| -rw-r--r-- | docs/services/dns-forwarding.rst | 72 | ||||
| -rw-r--r-- | docs/services/index.rst | 27 | ||||
| -rw-r--r-- | docs/services/ipoe-server.rst | 129 | ||||
| -rw-r--r-- | docs/system/proxy.rst | 28 | ||||
| -rw-r--r-- | docs/troubleshooting/index.rst | 459 | ||||
| -rw-r--r-- | vale.ini | 16 |
166 files changed, 3310 insertions, 2690 deletions
diff --git a/ci/vale/Google/AMPM.yml b/.github/styles/Google/AMPM.yml index fbdc6e4f..fbdc6e4f 100644 --- a/ci/vale/Google/AMPM.yml +++ b/.github/styles/Google/AMPM.yml diff --git a/ci/vale/Google/Acronyms.yml b/.github/styles/Google/Acronyms.yml index f41af018..f41af018 100644 --- a/ci/vale/Google/Acronyms.yml +++ b/.github/styles/Google/Acronyms.yml diff --git a/ci/vale/Google/Colons.yml b/.github/styles/Google/Colons.yml index 9a4b4b4a..9a4b4b4a 100644 --- a/ci/vale/Google/Colons.yml +++ b/.github/styles/Google/Colons.yml diff --git a/ci/vale/Google/Contractions.yml b/.github/styles/Google/Contractions.yml index 905a39f4..905a39f4 100644 --- a/ci/vale/Google/Contractions.yml +++ b/.github/styles/Google/Contractions.yml diff --git a/ci/vale/Google/DateFormat.yml b/.github/styles/Google/DateFormat.yml index e9d227fa..e9d227fa 100644 --- a/ci/vale/Google/DateFormat.yml +++ b/.github/styles/Google/DateFormat.yml diff --git a/ci/vale/Google/Ellipses.yml b/.github/styles/Google/Ellipses.yml index 436e6177..436e6177 100644 --- a/ci/vale/Google/Ellipses.yml +++ b/.github/styles/Google/Ellipses.yml diff --git a/ci/vale/Google/EmDash.yml b/.github/styles/Google/EmDash.yml index c6018db1..c6018db1 100644 --- a/ci/vale/Google/EmDash.yml +++ b/.github/styles/Google/EmDash.yml diff --git a/ci/vale/Google/EnDash.yml b/.github/styles/Google/EnDash.yml index 194876aa..194876aa 100644 --- a/ci/vale/Google/EnDash.yml +++ b/.github/styles/Google/EnDash.yml diff --git a/ci/vale/Google/Exclamation.yml b/.github/styles/Google/Exclamation.yml index c4db380b..c4db380b 100644 --- a/ci/vale/Google/Exclamation.yml +++ b/.github/styles/Google/Exclamation.yml diff --git a/ci/vale/Google/FirstPerson.yml b/.github/styles/Google/FirstPerson.yml index d2290611..d2290611 100644 --- a/ci/vale/Google/FirstPerson.yml +++ b/.github/styles/Google/FirstPerson.yml diff --git a/ci/vale/Google/Gender.yml b/.github/styles/Google/Gender.yml index c8486181..c8486181 100644 --- a/ci/vale/Google/Gender.yml +++ b/.github/styles/Google/Gender.yml diff --git a/ci/vale/Google/GenderBias.yml b/.github/styles/Google/GenderBias.yml index 261cfb66..261cfb66 100644 --- a/ci/vale/Google/GenderBias.yml +++ b/.github/styles/Google/GenderBias.yml diff --git a/ci/vale/Google/HeadingPunctuation.yml b/.github/styles/Google/HeadingPunctuation.yml index 5c39abbf..5c39abbf 100644 --- a/ci/vale/Google/HeadingPunctuation.yml +++ b/.github/styles/Google/HeadingPunctuation.yml diff --git a/ci/vale/Google/Headings.yml b/.github/styles/Google/Headings.yml index 5afb968d..5afb968d 100644 --- a/ci/vale/Google/Headings.yml +++ b/.github/styles/Google/Headings.yml diff --git a/ci/vale/Google/Hyphens.yml b/.github/styles/Google/Hyphens.yml index f9779637..f9779637 100644 --- a/ci/vale/Google/Hyphens.yml +++ b/.github/styles/Google/Hyphens.yml diff --git a/ci/vale/Google/Latin.yml b/.github/styles/Google/Latin.yml index f032b349..f032b349 100644 --- a/ci/vale/Google/Latin.yml +++ b/.github/styles/Google/Latin.yml diff --git a/ci/vale/Google/LyHyphens.yml b/.github/styles/Google/LyHyphens.yml index d5b6a942..d5b6a942 100644 --- a/ci/vale/Google/LyHyphens.yml +++ b/.github/styles/Google/LyHyphens.yml diff --git a/ci/vale/Google/OptionalPlurals.yml b/.github/styles/Google/OptionalPlurals.yml index 7058932f..7058932f 100644 --- a/ci/vale/Google/OptionalPlurals.yml +++ b/.github/styles/Google/OptionalPlurals.yml diff --git a/ci/vale/Google/Ordinal.yml b/.github/styles/Google/Ordinal.yml index 8c429e0f..8c429e0f 100644 --- a/ci/vale/Google/Ordinal.yml +++ b/.github/styles/Google/Ordinal.yml diff --git a/ci/vale/Google/OxfordComma.yml b/.github/styles/Google/OxfordComma.yml index 98b07113..98b07113 100644 --- a/ci/vale/Google/OxfordComma.yml +++ b/.github/styles/Google/OxfordComma.yml diff --git a/ci/vale/Google/Parens.yml b/.github/styles/Google/Parens.yml index 3b8711d0..3b8711d0 100644 --- a/ci/vale/Google/Parens.yml +++ b/.github/styles/Google/Parens.yml diff --git a/ci/vale/Google/Passive.yml b/.github/styles/Google/Passive.yml index 3265890e..3265890e 100644 --- a/ci/vale/Google/Passive.yml +++ b/.github/styles/Google/Passive.yml diff --git a/ci/vale/Google/Periods.yml b/.github/styles/Google/Periods.yml index d24a6a6c..d24a6a6c 100644 --- a/ci/vale/Google/Periods.yml +++ b/.github/styles/Google/Periods.yml diff --git a/ci/vale/Google/Quotes.yml b/.github/styles/Google/Quotes.yml index 3cb6f1ab..3cb6f1ab 100644 --- a/ci/vale/Google/Quotes.yml +++ b/.github/styles/Google/Quotes.yml diff --git a/ci/vale/Google/Ranges.yml b/.github/styles/Google/Ranges.yml index 3ec045e7..3ec045e7 100644 --- a/ci/vale/Google/Ranges.yml +++ b/.github/styles/Google/Ranges.yml diff --git a/ci/vale/Google/Semicolons.yml b/.github/styles/Google/Semicolons.yml index bb8b85b4..bb8b85b4 100644 --- a/ci/vale/Google/Semicolons.yml +++ b/.github/styles/Google/Semicolons.yml diff --git a/ci/vale/Google/Slang.yml b/.github/styles/Google/Slang.yml index 63f4c248..63f4c248 100644 --- a/ci/vale/Google/Slang.yml +++ b/.github/styles/Google/Slang.yml diff --git a/ci/vale/Google/Spacing.yml b/.github/styles/Google/Spacing.yml index 5f209a9f..5f209a9f 100644 --- a/ci/vale/Google/Spacing.yml +++ b/.github/styles/Google/Spacing.yml diff --git a/ci/vale/Google/Spelling.yml b/.github/styles/Google/Spelling.yml index 57acb884..57acb884 100644 --- a/ci/vale/Google/Spelling.yml +++ b/.github/styles/Google/Spelling.yml diff --git a/ci/vale/Google/Units.yml b/.github/styles/Google/Units.yml index 220de3e9..220de3e9 100644 --- a/ci/vale/Google/Units.yml +++ b/.github/styles/Google/Units.yml diff --git a/ci/vale/Google/Will.yml b/.github/styles/Google/Will.yml index 128a9183..128a9183 100644 --- a/ci/vale/Google/Will.yml +++ b/.github/styles/Google/Will.yml diff --git a/ci/vale/Google/WordList.yml b/.github/styles/Google/WordList.yml index d5d6bea5..d5d6bea5 100644 --- a/ci/vale/Google/WordList.yml +++ b/.github/styles/Google/WordList.yml diff --git a/ci/vale/Google/meta.json b/.github/styles/Google/meta.json index 3ae5fb21..3ae5fb21 100644 --- a/ci/vale/Google/meta.json +++ b/.github/styles/Google/meta.json diff --git a/ci/vale/Google/vocab.txt b/.github/styles/Google/vocab.txt index e69de29b..e69de29b 100644 --- a/ci/vale/Google/vocab.txt +++ b/.github/styles/Google/vocab.txt diff --git a/ci/vale/VyOS/Terminology.yml b/.github/styles/VyOS/Terminology.yml index 57c1e6d6..57c1e6d6 100644 --- a/ci/vale/VyOS/Terminology.yml +++ b/.github/styles/VyOS/Terminology.yml diff --git a/.github/vyos-linter.py b/.github/vyos-linter.py new file mode 100644 index 00000000..502e47ae --- /dev/null +++ b/.github/vyos-linter.py @@ -0,0 +1,177 @@ +import os +import re +import ipaddress +import sys +import ast + +IPV4SEG = r'(?:25[0-5]|(?:2[0-4]|1{0,1}[0-9]){0,1}[0-9])' +IPV4ADDR = r'\b(?:(?:' + IPV4SEG + r'\.){3,3}' + IPV4SEG + r')\b' +IPV6SEG = r'(?:(?:[0-9a-fA-F]){1,4})' +IPV6GROUPS = ( + r'(?:' + IPV6SEG + r':){7,7}' + IPV6SEG, # 1:2:3:4:5:6:7:8 + r'(?:\s' + IPV6SEG + r':){1,7}:', # 1:: 1:2:3:4:5:6:7:: + r'(?:' + IPV6SEG + r':){1,6}:' + IPV6SEG, # 1::8 1:2:3:4:5:6::8 1:2:3:4:5:6::8 + r'(?:' + IPV6SEG + r':){1,5}(?::' + IPV6SEG + r'){1,2}', # 1::7:8 1:2:3:4:5::7:8 1:2:3:4:5::8 + r'(?:' + IPV6SEG + r':){1,4}(?::' + IPV6SEG + r'){1,3}', # 1::6:7:8 1:2:3:4::6:7:8 1:2:3:4::8 + r'(?:' + IPV6SEG + r':){1,3}(?::' + IPV6SEG + r'){1,4}', # 1::5:6:7:8 1:2:3::5:6:7:8 1:2:3::8 + r'(?:' + IPV6SEG + r':){1,2}(?::' + IPV6SEG + r'){1,5}', # 1::4:5:6:7:8 1:2::4:5:6:7:8 1:2::8 + IPV6SEG + r':(?:(?::' + IPV6SEG + r'){1,6})', # 1::3:4:5:6:7:8 1::3:4:5:6:7:8 1::8 + r':(?:(?::' + IPV6SEG + r'){1,7}|:)', # ::2:3:4:5:6:7:8 ::2:3:4:5:6:7:8 ::8 :: + r'fe80:(?::' + IPV6SEG + r'){0,4}%[0-9a-zA-Z]{1,}', # fe80::7:8%eth0 fe80::7:8%1 (link-local IPv6 addresses with zone index) + r'::(?:ffff(?::0{1,4}){0,1}:){0,1}[^\s:]' + IPV4ADDR, # ::255.255.255.255 ::ffff:255.255.255.255 ::ffff:0:255.255.255.255 (IPv4-mapped IPv6 addresses and IPv4-translated addresses) + r'(?:' + IPV6SEG + r':){1,4}:[^\s:]' + IPV4ADDR, # 2001:db8:3:4::192.0.2.33 64:ff9b::192.0.2.33 (IPv4-Embedded IPv6 Address) +) +IPV6ADDR = '|'.join(['(?:{})'.format(g) for g in IPV6GROUPS[::-1]]) # Reverse rows for greedy match + +MAC = r'([0-9A-F]{2}[:-]){5}([0-9A-F]{2})' + +NUMBER = r"([\s']\d+[\s'])" + + +def lint_mac(cnt, line): + mac = re.search(MAC, line, re.I) + if mac is not None: + mac = mac.group() + u_mac = re.search(r'((00)[:-](53)([:-][0-9A-F]{2}){4})', mac, re.I) + m_mac = re.search(r'((90)[:-](10)([:-][0-9A-F]{2}){4})', mac, re.I) + if u_mac is None and m_mac is None: + return (f"Use MAC reserved for Documentation (RFC7042): {mac}", cnt, 'error') + + +def lint_ipv4(cnt, line): + ip = re.search(IPV4ADDR, line, re.I) + if ip is not None: + ip = ipaddress.ip_address(ip.group().strip(' ')) + # https://docs.python.org/3/library/ipaddress.html#ipaddress.IPv4Address.is_private + if ip.is_private: + return None + if ip.is_multicast: + return None + if ip.is_global is False: + return None + return (f"Use IPv4 reserved for Documentation (RFC 5737) or private Space: {ip}", cnt, 'error') + + +def lint_ipv6(cnt, line): + ip = re.search(IPV6ADDR, line, re.I) + if ip is not None: + ip = ipaddress.ip_address(ip.group().strip(' ')) + if ip.is_private: + return None + if ip.is_multicast: + return None + if ip.is_global is False: + return None + return (f"Use IPv6 reserved for Documentation (RFC 3849) or private Space: {ip}", cnt, 'error') + + +def lint_AS(cnt, line): + number = re.search(NUMBER, line, re.I) + if number: + pass + # find a way to detect AS numbers + + +def lint_linelen(cnt, line): + line = line.rstrip() + if len(line) > 80: + return (f"Line too long: len={len(line)}", cnt, 'warning') + +def handle_file_action(filepath): + errors = [] + try: + with open(filepath) as fp: + line = fp.readline() + cnt = 1 + test_line_lenght = True + start_vyoslinter = True + indentation = 0 + while line: + # search for ignore linter comments in lines + if ".. stop_vyoslinter" in line: + start_vyoslinter = False + if ".. start_vyoslinter" in line: + start_vyoslinter = True + if start_vyoslinter: + # ignore every '.. code-block::' for line lenght + # rst code-block have its own style in html the format in rst + # and the build page must be the same + if test_line_lenght is False: + if len(line) > indentation: + #print(f"'{line}'") + #print(indentation) + if line[indentation].isspace() is False: + test_line_lenght = True + + if ".. code-block::" in line: + test_line_lenght = False + indentation = 0 + for i in line: + if i.isspace(): + indentation = indentation + 1 + else: + break + + err_mac = lint_mac(cnt, line.strip()) + # disable mac detection for the moment, too many false positives + err_mac = None + err_ip4 = lint_ipv4(cnt, line.strip()) + err_ip6 = lint_ipv6(cnt, line.strip()) + if test_line_lenght: + err_len = lint_linelen(cnt, line) + else: + err_len = None + if err_mac: + errors.append(err_mac) + if err_ip4: + errors.append(err_ip4) + if err_ip6: + errors.append(err_ip6) + if err_len: + errors.append(err_len) + + line = fp.readline() + cnt += 1 + + # ensure linter was not stop on top and forgot to tun on again + if start_vyoslinter == False: + errors.append((f"Don't forgett to turn linter back on", cnt, 'error')) + finally: + fp.close() + + if len(errors) > 0: + ''' + "::{$type} file={$filename},line={$line},col=$column::{$log}" + ''' + print(f"File: {filepath}") + for error in errors: + print(f"::{error[2]} file={filepath},line={error[1]}::{error[0]}") + print('') + return False + + +def main(): + bool_error = True + print('start') + try: + files = ast.literal_eval(sys.argv[1]) + for file in files: + if file[-4:] in [".rst", ".txt"] and "_build" not in file: + if handle_file_action(file) is False: + bool_error = False + except Exception as e: + for root, dirs, files in os.walk("docs"): + path = root.split(os.sep) + for file in files: + if file[-4:] in [".rst", ".txt"] and "_build" not in path: + fpath = '/'.join(path) + filepath = f"{fpath}/{file}" + if handle_file_action(filepath) is False: + bool_error = False + + return bool_error + + +if __name__ == "__main__": + if main() == False: + exit(1)
\ No newline at end of file diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 00000000..fe87074c --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,32 @@ +name: Linting +on: + pull_request: + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2 + + - name: File Changes + id: file_changes + uses: trilom/file-changes-action@v1.2.3 + + #- name: Vale + # uses: errata-ai/vale-action@v1.3.0 + # with: + # files: '${{ steps.file_changes.outputs.files_modified }}' + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + + - name: run python based linter + run: python .github/vyos-linter.py '${{ steps.file_changes.outputs.files_modified }}' + + env: + GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} + +
\ No newline at end of file diff --git a/.github/workflows/submodules.yml b/.github/workflows/submodules.yml new file mode 100644 index 00000000..d32530ba --- /dev/null +++ b/.github/workflows/submodules.yml @@ -0,0 +1,32 @@ +name: Update submodule vyos-1x +on: + workflow_dispatch: + schedule: + # 06:00 UTC on Monday + - cron: '0 6 * * 1' +jobs: + updatVyOS-1x: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + with: + repository: ${{ github.repository }} + - name: update submodule + run: | + git submodule status + git submodule update --init --force + cd docs/_include/vyos-1x + git checkout crux + git pull + git submodule status + - name: Create Pull Request + uses: peter-evans/create-pull-request@v3 + with: + token: ${{secrets.GITHUB_TOKEN}} + commit-message: Update vyos-1x submodule + committer: GitHub <noreply@github.com> + author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com> + title: Update vyos-1x submodule + body: | + Autoupdate vyos-1x submodule + branch: update-dependencies
\ No newline at end of file @@ -1,4 +1,8 @@ +# Sphinx +_build/ + # python virtualenv +Pipfile.lock venv/ ENV/ .venv @@ -12,11 +16,11 @@ ENV/ # python cache files *.pyc -__pychache__ +__pycache__ # dotenv .env .envrc # os specific -.DS_Store +.DS_Store
\ No newline at end of file diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..16e68e7a --- /dev/null +++ b/.gitmodules @@ -0,0 +1,4 @@ +[submodule "docs/_include/vyos-1x"] + path = docs/_include/vyos-1x + url = https://github.com/vyos/vyos-1x + branch = crux
\ No newline at end of file @@ -1,34 +0,0 @@ -StylesPath = ci/vale -MinAlertLevel = suggestion - -[*.rst] -BasedOnStyles = VyOS - -Google.DateFormat = YES -vale.GenderBias = NO -vale.Hedging = NO -vale.Redundancy = NO -vale.Repetition = YES -vale.Uncomparables = NO -proselint.GenderBias = YES - -# Custom block scoping (see the regex101 links for unit tests): -# -# Rule #1 (https://regex101.com/r/TJQLJ4/2/tests): Ignore `{%comment%}` blocks. This -# keeps Vale from flagging 'endcomment' as a spelling mistake. -# -# Rule #2 (https://regex101.com/r/7VA2lV/2/tests): Ignore `<div>`s and `<section>`s -# that specify `markdown="1"` since it isn't supported by Vale's Markdown -# parser (https://github.com/russross/blackfriday/issues/184). -# -# Rule #3 (https://regex101.com/r/NxFflU/1/tests): Ignore `{% include %}`-codeblock -# pairs. -BlockIgnores = (?s)({%\s?comment\s?%}.+?{%\s?endcomment\s?%}), \ -(?s)(<(?:div|section)[^>]*markdown="1"[^>]*>.*?</(?:div|section)>), \ -(?s)((?: *{% include [^%]+ %}\n)? *~~~.*?~~~~?) - -# Custom inline scoping (see the regex101 links for unit tests): -# -# Rule #1 (https://regex101.com/r/cTiITH/2/tests): Ignore `{% include %}`s, which -# contain file paths. -TokenIgnores = ({%\s?include\s? {{ [^}]+ }}[^%]+\s?%}) diff --git a/Pipfile b/Pipfile new file mode 100644 index 00000000..e0d3438f --- /dev/null +++ b/Pipfile @@ -0,0 +1,14 @@ +[[source]] +url = "https://pypi.org/simple" +verify_ssl = true +name = "pypi" + +[packages] +sphinx-rtd-theme = "*" +docutils = "*" +Sphinx = ">=1.4.3" + +[dev-packages] + +[requires] +python_version = "3.9" diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index 69fa449d..00000000 --- a/docs/.gitignore +++ /dev/null @@ -1 +0,0 @@ -_build/ diff --git a/docs/_ext/test-coverage.py b/docs/_ext/test-coverage.py new file mode 100644 index 00000000..70714d6b --- /dev/null +++ b/docs/_ext/test-coverage.py @@ -0,0 +1,351 @@ +''' +generate json with all commands from xml for vyos documentation coverage + +''' + + +import sys +import os +import json +import re +import logging + +from io import BytesIO +from lxml import etree as ET +import shutil + +default_constraint_err_msg = "Invalid value" +validator_dir = "" + + +input_data = [ + { + "kind": "cfgcmd", + "input_dir": "_include/vyos-1x/interface-definitions/", + "schema_file": "_include/vyos-1x/schema/interface_definition.rng", + "files": [] + }, + { + "kind": "opcmd", + "input_dir": "_include/vyos-1x/op-mode-definitions/", + "schema_file": "_include/vyos-1x/schema/op-mode-definition.rng", + "files": [] + } +] + +node_data = { + 'cfgcmd': {}, + 'opcmd': {}, +} + +def get_properties(p): + props = {} + props['valueless'] = False + + try: + if p.find("valueless") is not None: + props['valueless'] = True + except: + pass + + if p is None: + return props + + # Get the help string + try: + props["help"] = p.find("help").text + except: + pass + + # Get value help strings + try: + vhe = p.findall("valueHelp") + vh = [] + for v in vhe: + vh.append( (v.find("format").text, v.find("description").text) ) + props["val_help"] = vh + except: + props["val_help"] = [] + + # Get the constraint statements + error_msg = default_constraint_err_msg + # Get the error message if it's there + try: + error_msg = p.find("constraintErrorMessage").text + except: + pass + + + vce = p.find("constraint") + vc = [] + if vce is not None: + # The old backend doesn't support multiple validators in OR mode + # so we emulate it + + regexes = [] + regex_elements = vce.findall("regex") + if regex_elements is not None: + regexes = list(map(lambda e: e.text.strip(), regex_elements)) + if "" in regexes: + print("Warning: empty regex, node will be accepting any value") + + validator_elements = vce.findall("validator") + validators = [] + if validator_elements is not None: + for v in validator_elements: + v_name = os.path.join(validator_dir, v.get("name")) + + # XXX: lxml returns None for empty arguments + v_argument = None + try: + v_argument = v.get("argument") + except: + pass + if v_argument is None: + v_argument = "" + + validators.append("{0} {1}".format(v_name, v_argument)) + + + regex_args = " ".join(map(lambda s: "--regex \\\'{0}\\\'".format(s), regexes)) + validator_args = " ".join(map(lambda s: "--exec \\\"{0}\\\"".format(s), validators)) + validator_script = '${vyos_libexec_dir}/validate-value.py' + validator_string = "exec \"{0} {1} {2} --value \\\'$VAR(@)\\\'\"; \"{3}\"".format(validator_script, regex_args, validator_args, error_msg) + + props["constraint"] = validator_string + + # Get the completion help strings + try: + che = p.findall("completionHelp") + ch = "" + for c in che: + scripts = c.findall("script") + paths = c.findall("path") + lists = c.findall("list") + + # Current backend doesn't support multiple allowed: tags + # so we get to emulate it + comp_exprs = [] + for i in lists: + comp_exprs.append("echo \"{0}\"".format(i.text)) + for i in paths: + comp_exprs.append("/bin/cli-shell-api listNodes {0}".format(i.text)) + for i in scripts: + comp_exprs.append("sh -c \"{0}\"".format(i.text)) + comp_help = " && ".join(comp_exprs) + props["comp_help"] = comp_help + except: + props["comp_help"] = [] + + # Get priority + try: + props["priority"] = p.find("priority").text + except: + pass + + # Get "multi" + if p.find("multi") is not None: + props["multi"] = True + + # Get "valueless" + if p.find("valueless") is not None: + props["valueless"] = True + + return props + +def process_node(n, f): + + props_elem = n.find("properties") + children = n.find("children") + command = n.find("command") + children_nodes = [] + owner = n.get("owner") + node_type = n.tag + + name = n.get("name") + props = get_properties(props_elem) + + if node_type != "node": + if "valueless" not in props.keys(): + props["type"] = "txt" + if node_type == "tagNode": + props["tag"] = "True" + + if node_type == "node" and children is not None: + inner_nodes = children.iterfind("*") + index_child = 0 + for inner_n in inner_nodes: + children_nodes.append(process_node(inner_n, f)) + index_child = index_child + 1 + + if node_type == "tagNode" and children is not None: + inner_nodes = children.iterfind("*") + index_child = 0 + for inner_n in inner_nodes: + children_nodes.append(process_node(inner_n, f)) + index_child = index_child + 1 + else: + # This is a leaf node + pass + + if command is not None: + test_command = True + else: + test_command = False + node = { + 'name': name, + 'type': node_type, + 'children': children_nodes, + 'props': props, + 'command': test_command, + 'filename': f + } + return node + + + +def create_commands(data, parent_list=[], level=0): + result = [] + command = { + 'name': [], + 'help': None, + 'tag_help': [], + 'level': level, + 'no_childs': False, + 'filename': None + } + command['filename'] = data['filename'] + command['name'].extend(parent_list) + command['name'].append(data['name']) + + if data['type'] == 'tagNode': + command['name'].append("<" + data['name'] + ">") + + if 'val_help' in data['props'].keys(): + for val_help in data['props']['val_help']: + command['tag_help'].append(val_help) + + if len(data['children']) == 0: + command['no_childs'] = True + + if data['command']: + command['no_childs'] = True + + try: + help_text = data['props']['help'] + command['help'] = re.sub(r"[\n\t]*", "", help_text) + + except: + command['help'] = "" + + command['valueless'] = data['props']['valueless'] + + if 'children' in data.keys(): + children_bool = True + for child in data['children']: + result.extend(create_commands(child, command['name'], level + 1)) + + if command['no_childs']: + result.append(command) + + + + return result + + +def include_file(line, input_dir): + string = "" + if "#include <include" in line.strip(): + include_filename = line.strip().split('<')[1][:-1] + with open(input_dir + include_filename) as ifp: + iline = ifp.readline() + while iline: + string = string + include_file(iline.strip(), input_dir) + iline = ifp.readline() + else: + string = line + return string + + +def get_working_commands(): + for entry in input_data: + for (dirpath, dirnames, filenames) in os.walk(entry['input_dir']): + entry['files'].extend(filenames) + break + + for f in entry['files']: + + string = "" + with open(entry['input_dir'] + f) as fp: + line = fp.readline() + while line: + string = string + include_file(line.strip(), entry['input_dir']) + line = fp.readline() + + try: + xml = ET.parse(BytesIO(bytes(string, 'utf-8'))) + except Exception as e: + print("Failed to load interface definition file {0}".format(f)) + print(e) + sys.exit(1) + + try: + relaxng_xml = ET.parse(entry['schema_file']) + validator = ET.RelaxNG(relaxng_xml) + + if not validator.validate(xml): + print(validator.error_log) + print("Interface definition file {0} does not match the schema!".format(f)) + sys.exit(1) + except Exception as e: + print("Failed to load the XML schema {0}".format(entry['schema_file'])) + print(e) + sys.exit(1) + + root = xml.getroot() + nodes = root.iterfind("*") + for n in nodes: + node_data[entry['kind']][f] = process_node(n, f) + + # build config tree and sort + + config_tree_new = { + 'cfgcmd': {}, + 'opcmd': {}, + } + + for kind in node_data: + for entry in node_data[kind]: + node_0 = node_data[kind][entry]['name'] + + if node_0 not in config_tree_new[kind].keys(): + config_tree_new[kind][node_0] = { + 'name': node_0, + 'type': node_data[kind][entry]['type'], + 'props': node_data[kind][entry]['props'], + 'children': [], + 'command': node_data[kind][entry]['command'], + 'filename': node_data[kind][entry]['filename'], + } + config_tree_new[kind][node_0]['children'].extend(node_data[kind][entry]['children']) + + result = { + 'cfgcmd': [], + 'opcmd': [], + } + for kind in config_tree_new: + for e in config_tree_new[kind]: + result[kind].extend(create_commands(config_tree_new[kind][e])) + + for cmd in result['cfgcmd']: + cmd['cmd'] = " ".join(cmd['name']) + for cmd in result['opcmd']: + cmd['cmd'] = " ".join(cmd['name']) + return result + + + +if __name__ == "__main__": + res = get_working_commands() + print(json.dumps(res)) + #print(res['cfgcmd'][0])
\ No newline at end of file diff --git a/docs/draw.io/pbr_example_1.drawio b/docs/_include/draw.io/pbr_example_1.drawio index 0d496572..0d496572 100644 --- a/docs/draw.io/pbr_example_1.drawio +++ b/docs/_include/draw.io/pbr_example_1.drawio diff --git a/docs/draw.io/vpn_s2s_ikev2.drawio b/docs/_include/draw.io/vpn_s2s_ikev2.drawio index b240c191..b240c191 100644 --- a/docs/draw.io/vpn_s2s_ikev2.drawio +++ b/docs/_include/draw.io/vpn_s2s_ikev2.drawio diff --git a/docs/appendix/releasenotes.rst b/docs/appendix/releasenotes.rst deleted file mode 100644 index f08786a0..00000000 --- a/docs/appendix/releasenotes.rst +++ /dev/null @@ -1,358 +0,0 @@ -.. _releasenotes: - -Release notes -############# - -1.2 (Crux) -========== - -1.2.6-S1 --------- - -1.2.6-S1 is a security release release made in September 2020. - -Resolved issues -^^^^^^^^^^^^^^^ - -VyOS 1.2.6 release was found to be suspectible to CVE-2020-10995. It's a low- -impact vulnerability in the PowerDNS recursor that allows an attacker to cause -performance degradation via a specially crafted authoritative DNS server reply. - -* `2899 <https://phabricator.vyos.net/T2899>`_ remote syslog server migration error on update - -1.2.6 ------ - -1.2.6 is a maintenance release made in September 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* `103 <https://phabricator.vyos.net/T103>`_ DHCP server prepends shared network name to hostnames -* `125 <https://phabricator.vyos.net/T125>`_ Missing PPPoE interfaces in l2tp configuration -* `1194 <https://phabricator.vyos.net/T1194>`_ cronjob is being setup even if not saved -* `1205 <https://phabricator.vyos.net/T1205>`_ module pcspkr missing -* `1219 <https://phabricator.vyos.net/T1219>`_ Redundant active-active configuration, asymmetric routing and conntrack-sync cache -* `1220 <https://phabricator.vyos.net/T1220>`_ Show transceiver information from plugin modules, e.g SFP+, QSFP -* `1221 <https://phabricator.vyos.net/T1221>`_ BGP - Default route injection is not processed by the specific route-map -* `1241 <https://phabricator.vyos.net/T1241>`_ Remove of policy route throws CLI error -* `1291 <https://phabricator.vyos.net/T1291>`_ Under certain conditions the VTI will stay forever down -* `1463 <https://phabricator.vyos.net/T1463>`_ Missing command `show ip bgp scan` appears in command completion -* `1575 <https://phabricator.vyos.net/T1575>`_ `show snmp mib ifmib` crashes with IndexError -* `1699 <https://phabricator.vyos.net/T1699>`_ Default net.ipv6.route.max_size 32768 is too low -* `1729 <https://phabricator.vyos.net/T1729>`_ PIM (Protocol Independent Multicast) implementation -* `1901 <https://phabricator.vyos.net/T1901>`_ Semicolon in values is interpreted as a part of the shell command by validators -* `1934 <https://phabricator.vyos.net/T1934>`_ Change default hostname when deploy from OVA without params. -* `1938 <https://phabricator.vyos.net/T1938>`_ syslog doesn't start automatically -* `1949 <https://phabricator.vyos.net/T1949>`_ Multihop IPv6 BFD is unconfigurable -* `1953 <https://phabricator.vyos.net/T1953>`_ DDNS service name validation rejects valid service names -* `1956 <https://phabricator.vyos.net/T1956>`_ PPPoE server: support PADO-delay -* `1973 <https://phabricator.vyos.net/T1973>`_ Allow route-map to match on BGP local preference value -* `1974 <https://phabricator.vyos.net/T1974>`_ Allow route-map to set administrative distance -* `1982 <https://phabricator.vyos.net/T1982>`_ Increase rotation for atop.acct -* `1983 <https://phabricator.vyos.net/T1983>`_ Expose route-map when BGP routes are programmed in to FIB -* `1985 <https://phabricator.vyos.net/T1985>`_ pppoe: Enable ipv6 modules without configured ipv6 pools -* `2000 <https://phabricator.vyos.net/T2000>`_ strongSwan does not install routes to table 220 in certain cases -* `2021 <https://phabricator.vyos.net/T2021>`_ OSPFv3 doesn't support decimal area syntax -* `2062 <https://phabricator.vyos.net/T2062>`_ Wrong dhcp-server static route subnet bytes -* `2091 <https://phabricator.vyos.net/T2091>`_ swanctl.conf file is not generated properly is more than one IPsec profile is used -* `2131 <https://phabricator.vyos.net/T2131>`_ Improve syslog remote host CLI definition -* `2224 <https://phabricator.vyos.net/T2224>`_ Update Linux Kernel to v4.19.114 -* `2286 <https://phabricator.vyos.net/T2286>`_ IPoE server vulnerability -* `2303 <https://phabricator.vyos.net/T2303>`_ Unable to delete the image version that came from OVA -* `2305 <https://phabricator.vyos.net/T2305>`_ Add release name to "show version" command -* `2311 <https://phabricator.vyos.net/T2311>`_ Statically configured name servers may not take precedence over ones from DHCP -* `2327 <https://phabricator.vyos.net/T2327>`_ Unable to create syslog server entry with different port -* `2332 <https://phabricator.vyos.net/T2332>`_ Backport node option for a syslog server -* `2342 <https://phabricator.vyos.net/T2342>`_ Bridge l2tpv3 + ethX errors -* `2344 <https://phabricator.vyos.net/T2344>`_ PPPoE server client static IP assignment silently fails -* `2385 <https://phabricator.vyos.net/T2385>`_ salt-minion: improve completion helpers -* `2389 <https://phabricator.vyos.net/T2389>`_ BGP community-list unknown command -* `2398 <https://phabricator.vyos.net/T2398>`_ op-mode "dhcp client leases interface" completion helper misses interfaces -* `2402 <https://phabricator.vyos.net/T2402>`_ Live ISO should warn when configuring that changes won't persist -* `2443 <https://phabricator.vyos.net/T2443>`_ NHRP: Add debugging information to syslog -* `2448 <https://phabricator.vyos.net/T2448>`_ `monitor protocol bgp` subcommands fail with 'command incomplete' -* `2458 <https://phabricator.vyos.net/T2458>`_ Update FRR to 7.3.1 -* `2476 <https://phabricator.vyos.net/T2476>`_ Bond member description change leads to network outage -* `2478 <https://phabricator.vyos.net/T2478>`_ login radius: use NAS-IP-Address if defined source address -* `2482 <https://phabricator.vyos.net/T2482>`_ Update PowerDNS recursor to 4.3.1 for CVE-2020-10995 -* `2517 <https://phabricator.vyos.net/T2517>`_ vyos-container: link_filter: No such file or directory -* `2526 <https://phabricator.vyos.net/T2526>`_ Wake-On-Lan CLI implementation -* `2528 <https://phabricator.vyos.net/T2528>`_ "update dns dynamic" throws FileNotFoundError excepton -* `2536 <https://phabricator.vyos.net/T2536>`_ "show log dns forwarding" still refers to dnsmasq -* `2538 <https://phabricator.vyos.net/T2538>`_ Update Intel NIC drivers to recent release (preparation for Kernel >=5.4) -* `2545 <https://phabricator.vyos.net/T2545>`_ Show physical device offloading capabilities for specified ethernet interface -* `2563 <https://phabricator.vyos.net/T2563>`_ Wrong interface binding for Dell VEP 1445 -* `2605 <https://phabricator.vyos.net/T2605>`_ SNMP service is not disabled by default -* `2625 <https://phabricator.vyos.net/T2625>`_ Provide generic Library for package builds -* `2686 <https://phabricator.vyos.net/T2686>`_ FRR: BGP: large-community configuration is not applied properly after upgrading FRR to 7.3.x series -* `2701 <https://phabricator.vyos.net/T2701>`_ `vpn ipsec pfs enable` doesn't work with IKE groups -* `2728 <https://phabricator.vyos.net/T2728>`_ Protocol option ignored for IPSec peers in transport mode -* `2734 <https://phabricator.vyos.net/T2734>`_ WireGuard: fwmark CLI definition is inconsistent -* `2757 <https://phabricator.vyos.net/T2757>`_ "show system image version" contains additional new-line character breaking output -* `2797 <https://phabricator.vyos.net/T2797>`_ Update Linux Kernel to v4.19.139 -* `2822 <https://phabricator.vyos.net/T2822>`_ Update Linux Kernel to v4.19.141 -* `2829 <https://phabricator.vyos.net/T2829>`_ PPPoE server: mppe setting is implemented as node instead of leafNode -* `2831 <https://phabricator.vyos.net/T2831>`_ Update Linux Kernel to v4.19.142 -* `2852 <https://phabricator.vyos.net/T2852>`_ rename dynamic dns interface breaks ddclient.cache permissions -* `2853 <https://phabricator.vyos.net/T2853>`_ Intel QAT acceleration does not work - - -1.2.5 ------ - -1.2.5 is a maintenance release made in April 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* `1020 <https://phabricator.vyos.net/T1020>`_ OSPF Stops distributing default route after a while -* `1228 <https://phabricator.vyos.net/T1228>`_ pppoe default-route force option not working (Rel 1.2.0-rc11) -* `1301 <https://phabricator.vyos.net/T1301>`_ bgp peer-groups don't work when "no-ipv4-unicast" is enabled. -* `1341 <https://phabricator.vyos.net/T1341>`_ Adding rate-limiter for pppoe server users -* `1376 <https://phabricator.vyos.net/T1376>`_ Incorrect DHCP lease counting -* `1392 <https://phabricator.vyos.net/T1392>`_ Large firewall rulesets cause the system to lose configuration and crash at startup -* `1416 <https://phabricator.vyos.net/T1416>`_ 2 dhcp server run in failover mode can't sync hostname with each other -* `1452 <https://phabricator.vyos.net/T1452>`_ accel-pppoe - add vendor option to shaper -* `1490 <https://phabricator.vyos.net/T1490>`_ BGP configuration (is lost|not applied) when updating 1.1.8 -> 1.2.1 -* `1780 <https://phabricator.vyos.net/T1780>`_ Adding ipsec ike closeaction -* `1803 <https://phabricator.vyos.net/T1803>`_ Unbind NTP while it's not requested... -* `1821 <https://phabricator.vyos.net/T1821>`_ "authentication mode radius" has no effect for PPPoE server -* `1827 <https://phabricator.vyos.net/T1827>`_ Increase default gc_thresh -* `1828 <https://phabricator.vyos.net/T1828>`_ Missing completion helper for "set system syslog host 192.0.2.1 facility all protocol" -* `1832 <https://phabricator.vyos.net/T1832>`_ radvd adding feature DNSSL branch.example.com example.com to existing package -* `1837 <https://phabricator.vyos.net/T1837>`_ PPPoE unrecognized option 'replacedefaultroute' -* `1851 <https://phabricator.vyos.net/T1851>`_ wireguard - changing the pubkey on an existing peer seems to destroy the running config. -* `1858 <https://phabricator.vyos.net/T1858>`_ l2tp: Delete depricated outside-nexthop and add gateway-address -* `1864 <https://phabricator.vyos.net/T1864>`_ Lower IPSec DPD timeout lower limit from 10s -> 2s -* `1879 <https://phabricator.vyos.net/T1879>`_ Extend Dynamic DNS XML definition value help strings and validators -* `1881 <https://phabricator.vyos.net/T1881>`_ Execute permissions are removed from custom SNMP scripts at commit time -* `1884 <https://phabricator.vyos.net/T1884>`_ Keeping VRRP transition-script native behaviour and adding stop-script -* `1891 <https://phabricator.vyos.net/T1891>`_ Router announcements broken on boot -* `1900 <https://phabricator.vyos.net/T1900>`_ Enable SNMP for VRRP. -* `1902 <https://phabricator.vyos.net/T1902>`_ Add redistribute non main table in bgp -* `1909 <https://phabricator.vyos.net/T1909>`_ Incorrect behaviour of static routes with overlapping networks -* `1913 <https://phabricator.vyos.net/T1913>`_ "system ipv6 blacklist" command has no effect -* `1914 <https://phabricator.vyos.net/T1914>`_ IPv6 multipath hash policy does not apply -* `1917 <https://phabricator.vyos.net/T1917>`_ Update WireGuard to Debian release 0.0.20191219-1 -* `1934 <https://phabricator.vyos.net/T1934>`_ Change default hostname when deploy from OVA without params. -* `1935 <https://phabricator.vyos.net/T1935>`_ NIC identification and usage problem in Hyper-V environments -* `1936 <https://phabricator.vyos.net/T1936>`_ pppoe-server CLI control features -* `1964 <https://phabricator.vyos.net/T1964>`_ SNMP Script-extensions allows names with spaces, but commit fails -* `1967 <https://phabricator.vyos.net/T1967>`_ BGP parameter "enforce-first-as" does not work anymore -* `1970 <https://phabricator.vyos.net/T1970>`_ Correct adding interfaces on boot -* `1971 <https://phabricator.vyos.net/T1971>`_ Missing modules in initrd.img for PXE boot -* `1998 <https://phabricator.vyos.net/T1998>`_ Update FRR to 7.3 -* `2001 <https://phabricator.vyos.net/T2001>`_ Error when router reboot -* `2032 <https://phabricator.vyos.net/T2032>`_ Monitor bandwidth bits -* `2059 <https://phabricator.vyos.net/T2059>`_ Set source-validation on bond vif don't work -* `2066 <https://phabricator.vyos.net/T2066>`_ PPPoE interface can be created multiple times - last wins -* `2069 <https://phabricator.vyos.net/T2069>`_ PPPoE-client does not works with service-name option -* `2077 <https://phabricator.vyos.net/T2077>`_ ISO build from crux branch is failing -* `2079 <https://phabricator.vyos.net/T2079>`_ Update Linux Kernel to v4.19.106 -* `2087 <https://phabricator.vyos.net/T2087>`_ Add maxfail 0 option to pppoe configuration. -* `2100 <https://phabricator.vyos.net/T2100>`_ BGP route adverisement wih checks rib -* `2120 <https://phabricator.vyos.net/T2120>`_ "reset vpn ipsec-peer" doesn't work with named peers -* `2197 <https://phabricator.vyos.net/T2197>`_ Cant add vif-s interface into a bridge -* `2228 <https://phabricator.vyos.net/T2228>`_ WireGuard does not allow ports < 1024 to be used -* `2252 <https://phabricator.vyos.net/T2252>`_ HTTP API add system image can return '504 Gateway Time-out' -* `2272 <https://phabricator.vyos.net/T2272>`_ Set system flow-accounting disable-imt has syntax error -* `2276 <https://phabricator.vyos.net/T2276>`_ PPPoE server vulnerability - - -1.2.4 ------ - -1.2.4 is a maintenance release made in December 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* `T258 <https://phabricator.vyos.net/T258>`_ Can not configure wan load-balancing on vyos-1.2 -* `T818 <https://phabricator.vyos.net/T818>`_ SNMP v3 - remove required engineid from user node -* `T1030 <https://phabricator.vyos.net/T1030>`_ Upgrade ddclient from 3.8.2 to 3.9.0 (support Cloudflare API v4) -* `T1183 <https://phabricator.vyos.net/T1183>`_ BFD Support via FRR -* `T1299 <https://phabricator.vyos.net/T1299>`_ Allow SNMPd to be extended with custom scripts -* `T1351 <https://phabricator.vyos.net/T1351>`_ accel-pppoe adding CIDR based IP pool option -* `T1391 <https://phabricator.vyos.net/T1391>`_ In route-map set community additive -* `T1394 <https://phabricator.vyos.net/T1394>`_ syslog systemd and host_name.py race condition -* `T1401 <https://phabricator.vyos.net/T1401>`_ Copying files with the FTP protocol fails if the password contains special characters -* `T1421 <https://phabricator.vyos.net/T1421>`_ OpenVPN client push-route stopped working, needs added quotes to fix -* `T1447 <https://phabricator.vyos.net/T1447>`_ Python subprocess called without import in host_name.py -* `T1470 <https://phabricator.vyos.net/T1470>`_ improve output of "show dhcpv6 server leases" -* `T1485 <https://phabricator.vyos.net/T1485>`_ Enable 'AdvIntervalOpt' option in for radvd.conf -* `T1496 <https://phabricator.vyos.net/T1496>`_ Separate rolling release and LTS kernel builds -* `T1560 <https://phabricator.vyos.net/T1560>`_ "set load-balancing wan rule 0" causes segfault and prevents load balancing from starting -* `T1568 <https://phabricator.vyos.net/T1568>`_ strip-private command improvement for additional masking of IPv6 and MAC address -* `T1578 <https://phabricator.vyos.net/T1578>`_ completion offers "show table", but show table does not exist -* `T1593 <https://phabricator.vyos.net/T1593>`_ Support ip6gre -* `T1597 <https://phabricator.vyos.net/T1597>`_ /usr/sbin/rsyslogd after deleting "system syslog" -* `T1638 <https://phabricator.vyos.net/T1638>`_ vyos-hostsd not setting system domain name -* `T1678 <https://phabricator.vyos.net/T1678>`_ hostfile-update missing line feed -* `T1694 <https://phabricator.vyos.net/T1694>`_ NTPd: Do not listen on all interfaces by default -* `T1701 <https://phabricator.vyos.net/T1701>`_ Delete domain-name and domain-search won't work -* `T1705 <https://phabricator.vyos.net/T1705>`_ High CPU usage by bgpd when snmp is active -* `T1707 <https://phabricator.vyos.net/T1707>`_ DHCP static mapping and exclude address not working -* `T1708 <https://phabricator.vyos.net/T1708>`_ Update Rolling Release Kernel to 4.19.76 -* `T1709 <https://phabricator.vyos.net/T1709>`_ Update WireGuard to 0.0.20190913 -* `T1716 <https://phabricator.vyos.net/T1716>`_ Update Intel NIC drivers to recent versions -* `T1726 <https://phabricator.vyos.net/T1726>`_ Update Linux Firmware binaries to a more recent version 2019-03-14 -> 2019-10-07 -* `T1728 <https://phabricator.vyos.net/T1728>`_ Update Linux Kernel to 4.19.79 -* `T1737 <https://phabricator.vyos.net/T1737>`_ SNMP tab completion missing -* `T1738 <https://phabricator.vyos.net/T1738>`_ Copy SNMP configuration from node to node raises exception -* `T1740 <https://phabricator.vyos.net/T1740>`_ Broken OSPFv2 virtual-link authentication -* `T1742 <https://phabricator.vyos.net/T1742>`_ NHRP unable to commit. -* `T1745 <https://phabricator.vyos.net/T1745>`_ dhcp-server commit fails with "DHCP range stop address x must be greater or equal to the range start address y!" when static mapping has same IP as range stop -* `T1749 <https://phabricator.vyos.net/T1749>`_ numeric validator doesn't support multiple ranges -* `T1769 <https://phabricator.vyos.net/T1769>`_ Remove complex SNMPv3 Transport Security Model (TSM) -* `T1772 <https://phabricator.vyos.net/T1772>`_ <regex> constraints in XML are partially broken -* `T1778 <https://phabricator.vyos.net/T1778>`_ Kilobits/Megabits difference in configuration Vyos/FRR -* `T1780 <https://phabricator.vyos.net/T1780>`_ Adding ipsec ike closeaction -* `T1786 <https://phabricator.vyos.net/T1786>`_ disable-dhcp-nameservers is missed in current host_name.py implementation -* `T1788 <https://phabricator.vyos.net/T1788>`_ Intel QAT (QuickAssist Technology ) implementation -* `T1792 <https://phabricator.vyos.net/T1792>`_ Update WireGuard to Debian release 0.0.20191012-1 -* `T1800 <https://phabricator.vyos.net/T1800>`_ Update Linux Kernel to v4.19.84 -* `T1809 <https://phabricator.vyos.net/T1809>`_ Wireless: SSID scan does not work in AP mode -* `T1811 <https://phabricator.vyos.net/T1811>`_ Upgrade from 1.1.8: Config file migration failed: module=l2tp -* `T1812 <https://phabricator.vyos.net/T1812>`_ DHCP: hostnames of clients not resolving after update v1.2.3 -> 1.2-rolling -* `T1819 <https://phabricator.vyos.net/T1819>`_ Reboot kills SNMPv3 configuration -* `T1822 <https://phabricator.vyos.net/T1822>`_ Priority inversion wireless interface dhcpv6 -* `T1836 <https://phabricator.vyos.net/T1836>`_ import-conf-mode-commands in vyos-1x/scripts fails to create an xml -* `T1839 <https://phabricator.vyos.net/T1839>`_ LLDP shows "VyOS unknown" instead of "VyOS" -* `T1841 <https://phabricator.vyos.net/T1841>`_ PPP ipv6-up.d direcotry missing -* `T1893 <https://phabricator.vyos.net/T1893>`_ igmp-proxy: Do not allow adding unknown interface -* `T1904 <https://phabricator.vyos.net/T1904>`_ update eth1 and eth2 link files for the vep4600 - - -1.2.3 ------ - -1.2.3 is a maintenance and feature backport release made in September 2019. - -New features -^^^^^^^^^^^^ - -* HTTP API -* "set service dns forwarding allow-from <IPv4 net|IPv6 net>" option for limiting queries to specific client networks (T1524) -* Functions for checking if a commit is in progress (T1503) -* "set system contig-mangement commit-archive source-address" option (T1543) -* Intel NIC drivers now support receive side scaling and multiqueue (T1554) - -Resolved issues -^^^^^^^^^^^^^^^ - -* OSPF max-metric values over 100 no longer causes commit errors (T1209) -* Fixes issue with DNS forwarding not performing recursive lookups on domain specific forwarders (T1333) -* Special characters in VRRP passwords are handled correctly (T1362) -* BGP weight is applied properly (T1377) -* Fixed permission for log files (T1420) -* Wireguard interfaces now support /31 addresses (T1425) -* Wireguard correctly handles firewall marks (T1428) -* DHCPv6 static mappings now work correctly (T1439) -* Flood ping commands now works correctly (T1450) -* Op mode "show firewall" commands now support counters longer than 8 digits (T1460) -* Fixed priority inversion in VTI commands (T1465) -* Fixed remote-as check in the BGP route-reflector-client option (T1468) -* It's now possible to re-create VRRP groups with RFC compatibility mode enabled (T1472) -* Fixed a typo in DHCPv6 server help strings (T1527) -* Unnumbered BGP peers now support VLAN interfaces (T1529) -* Fixed "set system syslog global archive file" command (T1530) -* Multiple fixes in cluster configuration scripts (T1531) -* Fixed missing help text for "service dns" (T1537) -* Fixed input validation in DHCPv6 relay options (T1541) -* It's now possible to create a QinQ interface and a firewall assigned to it in one commit (T1551) -* URL filtering now uses correct rule database path and works again (T1559) -* "show log vpn ipsec" command works again (T1579) -* "show arp interface <intf>" command works again (T1576) -* Fixed regression in L2TP/IPsec server (T1605) -* Netflow/sFlow captures IPv6 traffic correctly (T1613) -* "renew dhcpv6" command now works from op mode (T1616) -* BGP remove-private-as option iBGP vs eBGP check works correctly now (T1642) -* Multiple improvements in name servers and hosts configuration handling (T1540, T1360, T1264, T1623) - -Internals -^^^^^^^^^ - -/etc/resolv.conf and /etc/hosts files are now managed by the vyos-hostsd service that listens on a ZMQ socket for update messages. - -1.2.2 ------ - -1.2.2 is a maintenance release made in July 2019. - -New features -^^^^^^^^^^^^ - -* Options for per-interface MSS clamping. -* BGP extended next-hop capability -* Relaxed BGP multipath option -* Internal and external options for "remote-as" (accept any AS as long as it's the same to this router or different, respectively) -* "Unnumbered" (interface-based) BGP peers -* BGP no-prepend option -* Additive BGP community option -* OSPFv3 network type option -* Custom arguments for VRRP scripts -* A script for querying values from config files - -Resolved issues -^^^^^^^^^^^^^^^ - -* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability -* VRRP health-check scripts now can use arguments (T1371) -* DNS server addresses coming from a DHCP server are now correctly propagated to resolv.conf (T1497) -* Domain-specific name servers in DNS forwarding are now used for recursive queries (T1469) -* “run show dhcpv6 server leases” now display leases correctly (T1433) -* Deleting “firewall options” node no longer causes errors (T1461) -* Correct hostname is sent to remote syslog again (T1458) -* Board serial number from DMI is correctly displayed in “show version” (T1438) -* Multiple corrections in remote syslog config (T1358, T1355, T1294) -* Fixed missing newline in /etc/hosts (T1255) -* “system domain-name” is correctly included in /etc/resolv.conf (T1174) -* Fixed priority inversion in “interfaces vti vtiX ip” settings (T1465) -* Fixed errors when installing with RAID1 on UEFI machines (T1446) -* Fixed an error on disabling an interfaces that has no address (T1387) -* Fixed deleting VLAN interface with non-default MTU (T1367) -* vyos.config return_effective_values() function now correctly returns a list rather than a string (T1505) - -1.2.1 ------ - -VyOS 1.2.1 is a maintenance release made in April 2019. - -Resolved issues -^^^^^^^^^^^^^^^ - -* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers. -* The kernel now includes drivers for various USB serial adapters, which allows people to add a serial console to a machine without onboard RS232, or connect to something else from the router (`T1326 <https://phabricator.vyos.net/T1326>`_). -* The collection of network card firmware is now much more extensive. -* VRRP now correctly uses a virtual rather than physical MAC addresses in the RFC-compliant mode (`T1271 <https://phabricator.vyos.net/T1271>`_). -* DHCP WPAD URL option works correctly again (`T1330 <https://phabricator.vyos.net/T1330>`_) -* Many to many NAT rules now can use source/destination and translation networks of non-matching size (`T1312 <https://phabricator.vyos.net/T1312>`_). If 1:1 network bits translation is desired, it’s now user’s responsibility to check if prefix length matches. -* IPv6 network prefix translation is fixed (`T1290 <https://phabricator.vyos.net/T1290>`_). -* Non-alphanumeric characters such as “>” can now be safely used in PPPoE passwords (`T1308 <https://phabricator.vyos.net/T1308>`_). -* “show | commands” no longer fails when a config section ends with a leaf node such as “timezone” in “show system | commands” (`T1305 <https://phabricator.vyos.net/T1305>`_). -* “show | commands” correctly works in config mode now (`T1235 <https://phabricator.vyos.net/T1235>`_). -* VTI is now compatible with the DHCP-interface IPsec option (`T1298 <https://phabricator.vyos.net/T1298>`_). -* “show dhcp server statistics” command was broken in latest Crux (`T1277 <https://phabricator.vyos.net/T1277>`_). -* An issue with TFTP server refusing to listen on addresses other than loopback was fixed (`T1261 <https://phabricator.vyos.net/T1261>`_). -* Template issue that might cause UDP broadcast relay fail to start is fixed (`T1224 <https://phabricator.vyos.net/T1224>`_). -* VXLAN value validation is improved (`T1067 <https://phabricator.vyos.net/T1067>`_). -* Blank hostnames in DHCP updates no longer can crash DNS forwarding (`T1211 <https://phabricator.vyos.net/T1211>`_). -* Correct configuration is now generated for DHCPv6 relays with more than one upstream interface (`T1322 <https://phabricator.vyos.net/T1322>`_). -* “relay-agents-packets” option works correctly now (`T1234 <https://phabricator.vyos.net/T1234>`_). -* Dynamic DNS data is now cleaned on configuration change (`T1231 <https://phabricator.vyos.net/T1231>`_). -* Remote Syslog can now use a fully qualified domain name (`T1282 <https://phabricator.vyos.net/T1282>`_). -* ACPI power off works again (`T1279 <https://phabricator.vyos.net/T1279>`_). -* Negation in WAN load balancing rules works again (`T1247 <https://phabricator.vyos.net/T1247>`_). -* FRR’s staticd now starts on boot correctly (`T1218 <https://phabricator.vyos.net/T1218>`_). -* The installer now correctly detects SD card devices (`T1296 <https://phabricator.vyos.net/T1296>`_). -* Wireguard peers can be disabled now (`T1225 <https://phabricator.vyos.net/T1225>`_). -* The issue with wireguard interfaces impossible to delete is fixed (`T1217 <https://phabricator.vyos.net/T1217>`_). -* Unintended IPv6 access is fixed in SNMP configuration (`T1160 <https://phabricator.vyos.net/T1160>`_). -* It’s now possible to exclude hosts from the transparent web proxy (`T1060 <https://phabricator.vyos.net/T1060>`_). -* An issue with rules impossible to delete from the zone-based firewall is fixed (`T484 <https://phabricator.vyos.net/T484>`_). - -Earlier releases -================ - -See `the wiki <https://wiki.vyos.net/wiki/1.2.0/release_notes>`_. diff --git a/docs/appendix/troubleshooting.rst b/docs/appendix/troubleshooting.rst deleted file mode 100644 index b1ae27ae..00000000 --- a/docs/appendix/troubleshooting.rst +++ /dev/null @@ -1,385 +0,0 @@ -.. _troubleshooting: - -Troubleshooting -=============== - -Sometimes things break or don't work as expected. This section describes -several troubleshooting tools provided by VyOS that can help when something -goes wrong. - -Basic Connectivity Verification -------------------------------- - -Verifying connectivity can be done with the familiar `ping` and `traceroute` -commands. The options for each are shown (the options for each command were -displayed using the built-in help as described in the :ref:`cli` -section and are omitted from the output here): - -.. code-block:: none - - vyos@vyos:~$ ping - Possible completions: - <hostname> Send Internet Control Message Protocol (ICMP) echo request - <x.x.x.x> - <h:h:h:h:h:h:h:h> - -Several options are available when more extensive troubleshooting is needed: - -.. code-block:: none - - vyos@vyos:~$ ping 8.8.8.8 - Possible completions: - <Enter> Execute the current command - adaptive Ping options - allow-broadcast - audible - bypass-route - count - deadline - flood - interface - interval - mark - no-loopback - numeric - pattern - quiet - record-route - size - timestamp - tos - ttl - verbose - -.. code-block:: none - - vyos@vyos:~$ traceroute - Possible completions: - <hostname> Track network path to specified node - <x.x.x.x> - <h:h:h:h:h:h:h:h> - ipv4 Track network path to <hostname|IPv4 address> - ipv6 Track network path to <hostname|IPv6 address> - -However, another tool, mtr_, is available which combines ping and traceroute -into a single tool. An example of its output is shown: - -.. code-block:: none - - vyos@vyos:~$ mtr 10.62.212.12 - - My traceroute [v0.85] - vyos (0.0.0.0) - Keys: Help Display mode Restart statistics Order of fields quit - Packets Pings - Host Loss% Snt Last Avg Best Wrst StDev - 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 - 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 - 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 - 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 - -.. note:: The output of ``mtr`` consumes the screen and will replace your - command prompt. - -Several options are available for changing the display output. Press `h` to -invoke the built in help system. To quit, just press `q` and you'll be returned -to the VyOS command prompt. - - - -Interface names ---------------- - -If you find the names of your interfaces have changed, this could be -because your MAC addresses have changed. - -* For example, you have a VyOS VM with 4 Ethernet interfaces named - eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different host and find your interfaces now are eth4, eth5, eth6 and eth7. - - One way to fix this issue **taking control of the MAC addresses** is: - - Log into VyOS and run this command to display your interface settings. - - .. code-block:: none - - show interfaces detail - - Take note of MAC addresses. - - Now, in order to update a MAC address in the configuration, run this - command specifying the interface name and MAC address you want. - - .. code-block:: none - - set interfaces eth0 hw-id 00:0c:29:da:a4:fe - - If it is a VM, go into the settings of the host and set the MAC - address to the settings found in the config.boot file. You can also - set the MAC to static if the host allows so. - - -* Another example could be when cloning VyOS VMs in GNS3 and you get - into the same issue: interface names have changed. - - And **a more generic way to fix it** is just deleting every MAC - address at the configuration file of the cloned machine. They will be - correctly regenerated automatically. - - - -Monitoring ----------- - -Network Interfaces -^^^^^^^^^^^^^^^^^^ - -It's possible to monitor network traffic, either at the flow level or protocol -level. This can be useful when troubleshooting a variety of protocols and -configurations. The following interface types can be monitored: - -.. code-block:: none - - vyos@vyos:~$ monitor interfaces - Possible completions: - <Enter> Execute the current command - bonding Monitor a bonding interface - bridge Monitor a bridge interface - ethernet Monitor a ethernet interface - loopback Monitor a loopback interface - openvpn Monitor an openvpn interface - pppoe Monitor pppoe interface - pseudo-ethernet - Monitor a pseudo-ethernet interface - tunnel Monitor a tunnel interface - vrrp Monitor a vrrp interface - vti Monitor a vti interface - wireless Monitor wireless interface - -To monitor traffic flows, issue the :code:`monitor interfaces <type> <name> flow` -command, replacing `<type>` and `<name>` with your desired interface type and -name, respectively. Output looks like the following: - -.. code-block:: none - - 12.5Kb 25.0Kb 37.5Kb 50.0Kb 62.5Kb - ???????????????????????????????????????????????????????????????????????????????????????????????????? - 10.11.111.255 => 10.11.110.37 0b 0b 0b - <= 624b 749b 749b - 10.11.110.29 => 10.62.200.11 0b 198b 198b - <= 0b 356b 356b - 255.255.255.255 => 10.11.110.47 0b 0b 0b - <= 724b 145b 145b - 10.11.111.255 => 10.11.110.47 0b 0b 0b - <= 724b 145b 145b - 10.11.111.255 => 10.11.110.255 0b 0b 0b - <= 680b 136b 136b - ???????????????????????????????????????????????????????????????????????????????????????????????????? - TX: cumm: 26.7KB peak: 40.6Kb rates: 23.2Kb 21.4Kb 21.4Kb - RX: 67.5KB 63.6Kb 54.6Kb 54.0Kb 54.0Kb - TOTAL: 94.2KB 104Kb 77.8Kb 75.4Kb 75.4Kb - -Several options are available for changing the display output. Press `h` to -invoke the built in help system. To quit, just press `q` and you'll be returned -to the VyOS command prompt. - -To monitor interface traffic, issue the :code:`monitor interfaces <type> <name> -traffic` command, replacing `<type>` and `<name>` with your desired interface -type and name, respectively. This command invokes the familiar tshark_ utility -and the following options are available: - -.. code-block:: none - - vyos@vyos:~$ monitor interfaces ethernet eth0 traffic - Possible completions: - <Enter> Execute the current command - detail Monitor detailed traffic for the specified ethernet interface - filter Monitor filtered traffic for the specified ethernet interface - save Save monitored traffic to a file - unlimited Monitor traffic for the specified ethernet interface - -To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command -prompt. The `detail` keyword provides verbose output of the traffic seen on -the monitored interface. The `filter` keyword accepts valid `PCAP filter -expressions`_, enclosed in single or double quotes (e.g. "port 25" or "port 161 -and udp"). The `save` keyword allows you to save the traffic dump to a file. -The `unlimited` keyword is used to specify that an unlimited number of packets -can be captured (by default, 1,000 packets are captured and you're returned to -the VyOS command prompt). - -Interface Bandwith -^^^^^^^^^^^^^^^^^^ - -to take a quick view on the used bandwith of an interface use the ``monitor bandwith`` command - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth interface eth0 - -show the following: - -.. code-block:: none - - eth0 bmon 3.5 - Interfaces │ RX bps pps %│ TX bps pps % - >eth0 │ 141B 2 │ 272B 1 - ───────────────────────────────┴───────────────────────┴──────────────────────────────────────────────────────────────── - B (RX Bytes/second) - 198.00 .|....|..................................................... - 165.00 .|....|..................................................... - 132.00 ||..|.|..................................................... - 99.00 ||..|.|..................................................... - 66.00 |||||||..................................................... - 33.00 |||||||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 - KiB (TX Bytes/second) - 3.67 ......|..................................................... - 3.06 ......|..................................................... - 2.45 ......|..................................................... - 1.84 ......|..................................................... - 1.22 ......|..................................................... - 0.61 :::::||..................................................... - 1 5 10 15 20 25 30 35 40 45 50 55 60 - - ───────────────────────────────────────── Press d to enable detailed statistics ──────────────────────────────────────── - ─────────────────────────────────────── Press i to enable additional information ─────────────────────────────────────── - Wed Apr 3 14:46:59 2019 Press ? for help - -| Press ``d`` for more detailed informations or ``i`` for additional information. -| To exit press ``q`` and than ``y`` - -Interface performance -^^^^^^^^^^^^^^^^^^^^^ - -To take a look on the network bandwith between two nodes, the ``monitor bandwidth-test`` command is used to run iperf. - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth-test - Possible completions: - accept Wait for bandwidth test connections (port TCP/5001) - initiate Initiate a bandwidth test - -| The ``accept`` command open a listen iperf server on TCP Port 5001 -| The ``initiate`` command conncet to this server. - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth-test initiate - Possible completions: - <hostname> Initiate a bandwidth test to specified host (port TCP/5001) - <x.x.x.x> - <h:h:h:h:h:h:h:h> - - -Monitor command -^^^^^^^^^^^^^^^ - -The ``monitor command`` command allows you to repeatedly run a command to view a continuously refreshed output. -The command is run and output every 2 seconds, allowing you to monitor the output continuously without having to re-run the command. This can be useful to follow routing adjacency formation. - -.. code-block:: none - - vyos@router:~$ monitor command "show interfaces" - -Will clear the screen and show you the output of ``show interfaces`` every 2 seconds. - -.. code-block:: none - - Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper s... Sun Mar 26 02:49:46 2019 - - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 192.168.1.1/24 u/u - eth0.5 198.51.100.4/24 u/u WAN - lo 127.0.0.1/8 u/u - ::1/128 - vti0 172.32.254.2/30 u/u - vti1 172.32.254.9/30 u/u - -Clear Command -------------- - -Sometimes you need to clear counters or statistics to troubleshoot better. - -To do this use the ``clear`` command in Operational mode. - -to clear the console output - -.. code-block:: none - - vyos@vyos:~$ clear console - -to clear interface counters - -.. code-block:: none - - # clear all interfaces - vyos@vyos:~$ clear interface ethernet counters - # clear specific interface - vyos@vyos:~$ clear interface ehternet eth0 counters - -The command follow the same logic as the ``set`` command in configuration mode. - -.. code-block:: none - - # clear all counters of a interface type - vyos@vyos:~$ clear interface <interface_type> counters - # clear counter of a interface in interface_type - vyos@vyos:~$ clear interface <interface_type> <interace_name> counters - - -to clear counters on firewall rulesets or single rules - -.. code-block:: none - - vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters - vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters - - vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters - vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters - - -Basic System Information ------------------------- - -.. _boot-steps: - -Boot steps -^^^^^^^^^^ - -VyOS 1.2.0+ uses `Debian Jessie`_ as the base Linux operating system. -Jessie was the first version of Debian that uses `systemd`_ as the default init system. - -These are the boot steps for VyOS 1.2.0+ - -1. The BIOS loads Grub (or isolinux for the Live CD) -2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` -3. Kernel Launches Systemd ``/lib/systemd/systemd`` -4. Systemd loads the VyOS service file ``/lib/systemd/system/vyos-router.service`` -5. The service file launches the VyOS router init script ``/usr/libexec/vyos/init/vyos-router`` - this is part of the `vyatta-cfg`_ Debian package - - 1. Starts FRR_ - successor to `GNU Zebra`_ and `Quagga`_ - - 2. Initialises the boot configuration file - copies over ``config.boot.default`` if there is no configuration - 3. Runs the configuration migration, if the configuration is for an older version of VyOS - 4. Runs The pre-config script, if there is one ``/config/scripts/vyos-preconfig-bootup.script`` - 5. If the config file was upgraded, runs any post upgrade scripts ``/config/scripts/post-upgrade.d`` - 6. Starts **rl-system** and **firewall** - 7. Mounts the ``/boot`` partition - 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/vyatta-boot-config-loader /opt/vyatta/etc/config/config.boot`` - - 1. The config loader script writes log entries to ``/var/log/vyatta-config-loader.log`` - - 10. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` - 11. Finally it runs the post-config script ``/config/scripts/vyos-postconfig-bootup.script`` - -.. _Quagga: http://www.quagga.net/ -.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ -.. _FRR: https://frrouting.org/ -.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg -.. _systemd: _https://freedesktop.org/wiki/Software/systemd/ -.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ -.. _mtr: http://www.bitwizard.nl/mtr/ -.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html -.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html diff --git a/docs/commandscripting.rst b/docs/automation/command-scripting.rst index 98e97d3c..98e97d3c 100644 --- a/docs/commandscripting.rst +++ b/docs/automation/command-scripting.rst diff --git a/docs/automation/index.rst b/docs/automation/index.rst new file mode 100644 index 00000000..e07dfecc --- /dev/null +++ b/docs/automation/index.rst @@ -0,0 +1,15 @@ +############### +VyOS Automation +############### + + + * Ansible + * Saltstack + * HTTP-API + * startup scripts + + +.. toctree:: + :maxdepth: 1 + + command-scripting
\ No newline at end of file diff --git a/docs/changelog/1.2.1.rst b/docs/changelog/1.2.1.rst new file mode 100644 index 00000000..4f22dd0a --- /dev/null +++ b/docs/changelog/1.2.1.rst @@ -0,0 +1,52 @@ +1.2.1 +===== + +VyOS 1.2.1 is a maintenance release made in April 2019. + +Resolved issues +--------------- + +* Package updates: kernel 4.19.32, open-vm-tools 10.3, latest Intel NIC drivers +* :vytask:`T1326` The kernel now includes drivers for various USB serial + adapters, which allows people to add a serial console to a machine without + onboard RS232, or connect to something else from the router +* The collection of network card firmware is now much more extensive +* :vytask:`T1271` VRRP now correctly uses a virtual rather than physical MAC + addresses in the RFC-compliant mode +* :vytask:`T1330` DHCP WPAD URL option works correctly again +* :vytask:`T1312` Many to many NAT rules now can use source/destination and + translation networks of non-matching size. If 1:1 network bits translation is + desired, it's now users responsibility to check if prefix length matches. +* :vytask:`T1290` IPv6 network prefix translation is fixed +* :vytask:`T1308` Non-alphanumeric characters such as ``>`` can now be safely + used in PPPoE passwords +* :vytask:`T1305` ``show | commands`` no longer fails when a config section ends + with a leaf node such as ``timezone`` in ``show system | commands`` +* :vytask:`T1235` ``show | commands`` correctly works in config mode now +* :vytask:`T1298` VTI is now compatible with the DHCP-interface IPsec option +* :vytask:`T1277` ``show dhcp server statistics`` command was broken in latest + Crux +* :vytask:`T1261` An issue with TFTP server refusing to listen on addresses + other than loopback was fixed +* :vytask:`T1224` Template issue that might cause UDP broadcast relay fail to + start is fixed +* :vytask:`T1067` VXLAN value validation is improved +* :vytask:`T1211` Blank hostnames in DHCP updates no longer can crash DNS + forwarding +* :vytask:`T1322` Correct configuration is now generated for DHCPv6 relays with + more than one upstream interface +* :vytask:`T1234` ``relay-agents-packets`` option works correctly now +* :vytask:`T1231` Dynamic DNS data is now cleaned on configuration change +* :vytask:`T1282` Remote Syslog can now use a fully qualified domain name +* :vytask:`T1279` ACPI power off works again +* :vytask:`T1247` Negation in WAN load balancing rules works again +* :vytask:`T1218` FRR staticd now starts on boot correctly +* :vytask:`T1296` The installer now correctly detects SD card devices +* :vytask:`T1225` Wireguard peers can be disabled now +* :vytask:`T1217` The issue with Wireguard interfaces impossible to delete + is fixed +* :vytask:`T1160` Unintended IPv6 access is fixed in SNMP configuration +* :vytask:`T1060` It's now possible to exclude hosts from the transparent + web proxy +* :vytask:`T484` An issue with rules impossible to delete from the zone-based + firewall is fixed
\ No newline at end of file diff --git a/docs/changelog/1.2.2.rst b/docs/changelog/1.2.2.rst new file mode 100644 index 00000000..17ba941f --- /dev/null +++ b/docs/changelog/1.2.2.rst @@ -0,0 +1,46 @@ +1.2.2 +===== + +1.2.2 is a maintenance release made in July 2019. + +New features +------------ + +* Options for per-interface MSS clamping. +* BGP extended next-hop capability +* Relaxed BGP multipath option +* Internal and external options for "remote-as" (accept any AS as long as it's + the same to this router or different, respectively) +* "Unnumbered" (interface-based) BGP peers +* BGP no-prepend option +* Additive BGP community option +* OSPFv3 network type option +* Custom arguments for VRRP scripts +* A script for querying values from config files + +Resolved issues +--------------- + +* Linux kernel 4.19.54, including a fix for the TCP SACK vulnerability +* :vytask:`T1371` VRRP health-check scripts now can use arguments +* :vytask:`T1497` DNS server addresses coming from a DHCP server are now + correctly propagated to resolv.conf +* :vytask:`T1469` Domain-specific name servers in DNS forwarding are now used + for recursive queries +* :vytask:`T1433` ``run show dhcpv6 server leases`` now display leases correctly +* :vytask:`T1461` Deleting ``firewall options`` node no longer causes errors +* :vytask:`T1458` Correct hostname is sent to remote syslog again +* :vytask:`T1438` Board serial number from DMI is correctly displayed in + ``show version`` +* :vytask:`T1358`, :vytask:`T1355`, :vytask:`T1294` Multiple corrections in + remote syslog config +* :vytask:`T1255` Fixed missing newline in ``/etc/hosts`` +* :vytask:`T1174` ``system domain-name`` is correctly included in + ``/etc/resolv.conf`` +* :vytask:`T1465` Fixed priority inversion in ``interfaces vti vtiX ip`` + settings +* :vytask:`T1446` Fixed errors when installing with RAID1 on UEFI machines +* :vytask:`T1387` Fixed an error on disabling an interfaces that has no address +* :vytask:`T1367` Fixed deleting VLAN interface with non-default MTU +* :vytask:`T1505` vyos.config ``return_effective_values()`` function now + correctly returns a list rather than a string
\ No newline at end of file diff --git a/docs/changelog/1.2.3.rst b/docs/changelog/1.2.3.rst new file mode 100644 index 00000000..653beec1 --- /dev/null +++ b/docs/changelog/1.2.3.rst @@ -0,0 +1,62 @@ +1.2.3 +===== + +1.2.3 is a maintenance and feature backport release made in September 2019. + +New features +------------ + +* HTTP API +* :vytask:`T1524` "set service dns forwarding allow-from <IPv4 net|IPv6 net>" + option for limiting queries to specific client networks +* :vytask:`T1503` Functions for checking if a commit is in progress +* :vytask:`T1543` "set system contig-mangement commit-archive source-address" + option +* :vytask:`T1554` Intel NIC drivers now support receive side scaling and + multiqueue + +Resolved issues +--------------- + +* :vytask:`T1209` OSPF max-metric values over 100 no longer causes commit + errors +* :vytask:`T1333` Fixes issue with DNS forwarding not performing recursive + lookups on domain specific forwarders +* :vytask:`T1362` Special characters in VRRP passwords are handled correctly +* :vytask:`T1377` BGP weight is applied properly +* :vytask:`T1420` Fixed permission for log files +* :vytask:`T1425` Wireguard interfaces now support /31 addresses +* :vytask:`T1428` Wireguard correctly handles firewall marks +* :vytask:`T1439` DHCPv6 static mappings now work correctly +* :vytask:`T1450` Flood ping commands now works correctly +* :vytask:`T1460` Op mode "show firewall" commands now support counters longer + than 8 digits (T1460) +* :vytask:`T1465` Fixed priority inversion in VTI commands +* :vytask:`T1468` Fixed remote-as check in the BGP route-reflector-client option +* :vytask:`T1472` It's now possible to re-create VRRP groups with RFC + compatibility mode enabled +* :vytask:`T1527` Fixed a typo in DHCPv6 server help strings +* :vytask:`T1529` Unnumbered BGP peers now support VLAN interfaces +* :vytask:`T1530` Fixed "set system syslog global archive file" command +* :vytask:`T1531` Multiple fixes in cluster configuration scripts +* :vytask:`T1537` Fixed missing help text for "service dns" +* :vytask:`T1541` Fixed input validation in DHCPv6 relay options +* :vytask:`T1551` It's now possible to create a QinQ interface and a firewall + assigned to it in one commit +* :vytask:`T1559` URL filtering now uses correct rule database path and works + again +* :vytask:`T1579` "show log vpn ipsec" command works again +* :vytask:`T1576` "show arp interface <intf>" command works again +* :vytask:`T1605` Fixed regression in L2TP/IPsec server +* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly +* :vytask:`T1616` "renew dhcpv6" command now works from op mode +* :vytask:`T1642` BGP remove-private-as option iBGP vs eBGP check works + correctly now +* :vytask:`T1540`, :vytask:`T1360`, :vytask:`T1264`, :vytask:`T1623` Multiple + improvements in name servers and hosts configuration handling + +Internals +--------- + +``/etc/resolv.conf`` and ``/etc/hosts`` files are now managed by the +*vyos-hostsd* service that listens on a ZMQ socket for update messages.
\ No newline at end of file diff --git a/docs/changelog/1.2.4.rst b/docs/changelog/1.2.4.rst new file mode 100644 index 00000000..3e228880 --- /dev/null +++ b/docs/changelog/1.2.4.rst @@ -0,0 +1,77 @@ +1.2.4 +===== + +1.2.4 is a maintenance release made in December 2019. + +Resolved issues +--------------- + +* :vytask:`T258` Can not configure wan load-balancing on vyos-1.2 +* :vytask:`T818` SNMP v3 - remove required engineid from user node +* :vytask:`T1030` Upgrade ddclient from 3.8.2 to 3.9. + (support Cloudflare API v4) +* :vytask:`T1183` BFD Support via FRR +* :vytask:`T1299` Allow SNMPd to be extended with custom scripts +* :vytask:`T1351` accel-pppoe adding CIDR based IP pool option +* :vytask:`T1391` In route-map set community additive +* :vytask:`T1394` syslog systemd and host_name.py race condition +* :vytask:`T1401` Copying files with the FTP protocol fails if the passwor + contains special characters +* :vytask:`T1421` OpenVPN client push-route stopped working, needs added quotes + to fix +* :vytask:`T1430` Add options for custom DHCP client-id and hostname +* :vytask:`T1447` Python subprocess called without import in host_name.py +* :vytask:`T1470` improve output of "show dhcpv6 server leases" +* :vytask:`T1485` Enable 'AdvIntervalOpt' option in for radvd.conf +* :vytask:`T1496` Separate rolling release and LTS kernel builds +* :vytask:`T1560` "set load-balancing wan rule 0" causes segfault and prevent + load balancing from starting +* :vytask:`T1568` strip-private command improvement for additional masking o + IPv6 and MAC address +* :vytask:`T1578` completion offers "show table", but show table does not exist +* :vytask:`T1593` Support ip6gre +* :vytask:`T1597` /usr/sbin/rsyslogd after deleting "system syslog" +* :vytask:`T1638` vyos-hostsd not setting system domain name +* :vytask:`T1678` hostfile-update missing line feed +* :vytask:`T1694` NTPd: Do not listen on all interfaces by default +* :vytask:`T1701` Delete domain-name and domain-search won't work +* :vytask:`T1705` High CPU usage by bgpd when snmp is active +* :vytask:`T1707` DHCP static mapping and exclude address not working +* :vytask:`T1708` Update Rolling Release Kernel to 4.19.76 +* :vytask:`T1709` Update WireGuard to 0.0.20190913 +* :vytask:`T1716` Update Intel NIC drivers to recent versions +* :vytask:`T1726` Update Linux Firmware binaries to a more recen + version 2019-03-14 -> 2019-10-07 +* :vytask:`T1728` Update Linux Kernel to 4.19.79 +* :vytask:`T1737` SNMP tab completion missing +* :vytask:`T1738` Copy SNMP configuration from node to node raises exception +* :vytask:`T1740` Broken OSPFv2 virtual-link authentication +* :vytask:`T1742` NHRP unable to commit. +* :vytask:`T1745` dhcp-server commit fails with "DHCP range stop address + must be greater or equal to the range start address y!" when static mapping + has same IP as range stop +* :vytask:`T1749` numeric validator doesn't support multiple ranges +* :vytask:`T1769` Remove complex SNMPv3 Transport Security Model (TSM) +* :vytask:`T1772` <regex> constraints in XML are partially broken +* :vytask:`T1778` Kilobits/Megabits difference in configuration Vyos/FRR +* :vytask:`T1780` Adding ipsec ike closeaction +* :vytask:`T1786` disable-dhcp-nameservers is missed in current host_name.p + implementation +* :vytask:`T1788` Intel QAT (QuickAssist Technology ) implementation +* :vytask:`T1792` Update WireGuard to Debian release 0.0.20191012-1 +* :vytask:`T1800` Update Linux Kernel to v4.19.84 +* :vytask:`T1809` Wireless: SSID scan does not work in AP mode +* :vytask:`T1811` Upgrade from 1.1.8: Config file migratio + failed: module=l2tp +* :vytask:`T1812` DHCP: hostnames of clients not resolving afte + update v1.2.3 -> 1.2-rolling +* :vytask:`T1819` Reboot kills SNMPv3 configuration +* :vytask:`T1822` Priority inversion wireless interface dhcpv6 +* :vytask:`T1825` Improve DHCP configuration error message +* :vytask:`T1836` import-conf-mode-commands in vyos-1x/scripts fails + to create an xml +* :vytask:`T1839` LLDP shows "VyOS unknown" instead of "VyOS" +* :vytask:`T1841` PPP ipv6-up.d direcotry missing +* :vytask:`T1893` igmp-proxy: Do not allow adding unknown interface +* :vytask:`T1903` Implementation udev predefined interface naming +* :vytask:`T1904` update eth1 and eth2 link files for the vep4600
\ No newline at end of file diff --git a/docs/changelog/1.2.5.rst b/docs/changelog/1.2.5.rst new file mode 100644 index 00000000..6eabc6cf --- /dev/null +++ b/docs/changelog/1.2.5.rst @@ -0,0 +1,70 @@ +1.2.5 +===== + +1.2.5 is a maintenance release made in April 2020. + +Resolved issues +--------------- + +* :vytask:`1020` OSPF Stops distributing default route after a while +* :vytask:`1228` pppoe default-route force option not working (Rel 1.2.0-rc11) +* :vytask:`1301` bgp peer-groups don't work when "no-ipv4-unicast" is enabled. +* :vytask:`1341` Adding rate-limiter for pppoe server users +* :vytask:`1376` Incorrect DHCP lease counting +* :vytask:`1392` Large firewall rulesets cause the system to lose configuration + and crash at startup +* :vytask:`1416` 2 dhcp server run in failover mode can't sync hostname with + each other +* :vytask:`1452` accel-pppoe - add vendor option to shaper +* :vytask:`1490` BGP configuration (is lost|not applied) when updating + 1.1.8 -> 1.2.1 +* :vytask:`1780` Adding ipsec ike closeaction +* :vytask:`1803` Unbind NTP while it's not requested... +* :vytask:`1821` "authentication mode radius" has no effect for PPPoE server +* :vytask:`1827` Increase default gc_thresh +* :vytask:`1828` Missing completion helper for "set system syslog host + 192.0.2.1 facility all protocol" +* :vytask:`1832` radvd adding feature DNSSL branch.example.com example.com to + existing package +* :vytask:`1837` PPPoE unrecognized option 'replacedefaultroute' +* :vytask:`1851` wireguard - changing the pubkey on an existing peer seems to + destroy the running config. +* :vytask:`1858` l2tp: Delete depricated outside-nexthop and add gateway-address +* :vytask:`1864` Lower IPSec DPD timeout lower limit from 10s -> 2s +* :vytask:`1879` Extend Dynamic DNS XML definition value help strings and + validators +* :vytask:`1881` Execute permissions are removed from custom SNMP scripts at + commit time +* :vytask:`1884` Keeping VRRP transition-script native behaviour and adding + stop-script +* :vytask:`1891` Router announcements broken on boot +* :vytask:`1900` Enable SNMP for VRRP. +* :vytask:`1902` Add redistribute non main table in bgp +* :vytask:`1909` Incorrect behaviour of static routes with overlapping networks +* :vytask:`1913` "system ipv6 blacklist" command has no effect +* :vytask:`1914` IPv6 multipath hash policy does not apply +* :vytask:`1917` Update WireGuard to Debian release 0.0.20191219-1 +* :vytask:`1934` Change default hostname when deploy from OVA without params. +* :vytask:`1935` NIC identification and usage problem in Hyper-V environments +* :vytask:`1936` pppoe-server CLI control features +* :vytask:`1964` SNMP Script-extensions allows names with spaces, but commit + fails +* :vytask:`1967` BGP parameter "enforce-first-as" does not work anymore +* :vytask:`1970` Correct adding interfaces on boot +* :vytask:`1971` Missing modules in initrd.img for PXE boot +* :vytask:`1998` Update FRR to 7.3 +* :vytask:`2001` Error when router reboot +* :vytask:`2032` Monitor bandwidth bits +* :vytask:`2059` Set source-validation on bond vif don't work +* :vytask:`2066` PPPoE interface can be created multiple times - last wins +* :vytask:`2069` PPPoE-client does not works with service-name option +* :vytask:`2077` ISO build from crux branch is failing +* :vytask:`2079` Update Linux Kernel to v4.19.106 +* :vytask:`2087` Add maxfail 0 option to pppoe configuration. +* :vytask:`2100` BGP route adverisement wih checks rib +* :vytask:`2120` "reset vpn ipsec-peer" doesn't work with named peers +* :vytask:`2197` Cant add vif-s interface into a bridge +* :vytask:`2228` WireGuard does not allow ports < 1024 to be used +* :vytask:`2252` HTTP API add system image can return '504 Gateway Time-out' +* :vytask:`2272` Set system flow-accounting disable-imt has syntax error +* :vytask:`2276` PPPoE server vulnerability
\ No newline at end of file diff --git a/docs/changelog/1.2.6.rst b/docs/changelog/1.2.6.rst new file mode 100644 index 00000000..9c048f58 --- /dev/null +++ b/docs/changelog/1.2.6.rst @@ -0,0 +1,106 @@ +1.2.6-S1 +======== + +1.2.6-S1 is a security release release made in September 2020. + +Resolved issues +--------------- + +VyOS 1.2.6 release was found to be suspectible to CVE-2020-10995. It's a low- +impact vulnerability in the PowerDNS recursor that allows an attacker to cause +performance degradation via a specially crafted authoritative DNS server reply. + +* :vytask:`2899` remote syslog server migration error on update + +1.2.6 +===== + +1.2.6 is a maintenance release made in September 2020. + +Resolved issues +--------------- + +* :vytask:`103` DHCP server prepends shared network name to hostnames +* :vytask:`125` Missing PPPoE interfaces in l2tp configuration +* :vytask:`1194` cronjob is being setup even if not saved +* :vytask:`1205` module pcspkr missing +* :vytask:`1219` Redundant active-active configuration, asymmetric routing and + conntrack-sync cache +* :vytask:`1220` Show transceiver information from plugin modules, e.g SFP+, + QSFP +* :vytask:`1221` BGP - Default route injection is not processed by the specific + route-map +* :vytask:`1241` Remove of policy route throws CLI error +* :vytask:`1291` Under certain conditions the VTI will stay forever down +* :vytask:`1463` Missing command `show ip bgp scan` appears in command + completion +* :vytask:`1575` `show snmp mib ifmib` crashes with IndexError +* :vytask:`1699` Default net.ipv6.route.max_size 32768 is too low +* :vytask:`1729` PIM (Protocol Independent Multicast) implementation +* :vytask:`1901` Semicolon in values is interpreted as a part of the shell + command by validators +* :vytask:`1934` Change default hostname when deploy from OVA without params. +* :vytask:`1938` syslog doesn't start automatically +* :vytask:`1949` Multihop IPv6 BFD is unconfigurable +* :vytask:`1953` DDNS service name validation rejects valid service names +* :vytask:`1956` PPPoE server: support PADO-delay +* :vytask:`1973` Allow route-map to match on BGP local preference value +* :vytask:`1974` Allow route-map to set administrative distance +* :vytask:`1982` Increase rotation for atop.acct +* :vytask:`1983` Expose route-map when BGP routes are programmed in to FIB +* :vytask:`1985` pppoe: Enable ipv6 modules without configured ipv6 pools +* :vytask:`2000` strongSwan does not install routes to table 220 in certain + cases +* :vytask:`2021` OSPFv3 doesn't support decimal area syntax +* :vytask:`2062` Wrong dhcp-server static route subnet bytes +* :vytask:`2091` swanctl.conf file is not generated properly is more than one + IPsec profile is used +* :vytask:`2131` Improve syslog remote host CLI definition +* :vytask:`2224` Update Linux Kernel to v4.19.114 +* :vytask:`2286` IPoE server vulnerability +* :vytask:`2303` Unable to delete the image version that came from OVA +* :vytask:`2305` Add release name to "show version" command +* :vytask:`2311` Statically configured name servers may not take precedence + over ones from DHCP +* :vytask:`2327` Unable to create syslog server entry with different port +* :vytask:`2332` Backport node option for a syslog server +* :vytask:`2342` Bridge l2tpv3 + ethX errors +* :vytask:`2344` PPPoE server client static IP assignment silently fails +* :vytask:`2385` salt-minion: improve completion helpers +* :vytask:`2389` BGP community-list unknown command +* :vytask:`2398` op-mode "dhcp client leases interface" completion helper + misses interfaces +* :vytask:`2402` Live ISO should warn when configuring that changes won't + persist +* :vytask:`2443` NHRP: Add debugging information to syslog +* :vytask:`2448` `monitor protocol bgp` subcommands fail with 'command + incomplete' +* :vytask:`2458` Update FRR to 7.3.1 +* :vytask:`2476` Bond member description change leads to network outage +* :vytask:`2478` login radius: use NAS-IP-Address if defined source address +* :vytask:`2482` Update PowerDNS recursor to 4.3.1 for CVE-2020-10995 +* :vytask:`2517` vyos-container: link_filter: No such file or directory +* :vytask:`2526` Wake-On-Lan CLI implementation +* :vytask:`2528` "update dns dynamic" throws FileNotFoundError excepton +* :vytask:`2536` "show log dns forwarding" still refers to dnsmasq +* :vytask:`2538` Update Intel NIC drivers to recent release (preparation for + Kernel >=5.4) +* :vytask:`2545` Show physical device offloading capabilities for specified + ethernet interface +* :vytask:`2563` Wrong interface binding for Dell VEP 1445 +* :vytask:`2605` SNMP service is not disabled by default +* :vytask:`2625` Provide generic Library for package builds +* :vytask:`2686` FRR: BGP: large-community configuration is not applied + properly after upgrading FRR to 7.3.x series +* :vytask:`2701` `vpn ipsec pfs enable` doesn't work with IKE groups +* :vytask:`2728` Protocol option ignored for IPSec peers in transport mode +* :vytask:`2734` WireGuard: fwmark CLI definition is inconsistent +* :vytask:`2757` "show system image version" contains additional new-line + character breaking output +* :vytask:`2797` Update Linux Kernel to v4.19.139 +* :vytask:`2822` Update Linux Kernel to v4.19.141 +* :vytask:`2829` PPPoE server: mppe setting is implemented as node instead of + leafNode +* :vytask:`2831` Update Linux Kernel to v4.19.142 +* :vytask:`2852` rename dynamic dns interface breaks ddclient.cache permissions +* :vytask:`2853` Intel QAT acceleration does not work
\ No newline at end of file diff --git a/docs/changelog/index.rst b/docs/changelog/index.rst new file mode 100644 index 00000000..ae964145 --- /dev/null +++ b/docs/changelog/index.rst @@ -0,0 +1,18 @@ +.. _release-notes: + + +######### +Changelog +######### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + 1.2.6 + 1.2.5 + 1.2.4 + 1.2.3 + 1.2.2 + 1.2.1 diff --git a/docs/cli.rst b/docs/cli.rst index 89030ddc..d5f00a45 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,9 +1,14 @@ .. _cli: -Command-Line Interface -====================== +###################### +Command Line Interface +###################### + +The VyOS :abbr:`CLI (Command-Line Interface)` comprises an operational and a +configuration mode. -The VyOS CLI comprises an :ref:`commandtree_operationmode` and a :ref:`commandtree_configmode`. +Operational Mode +################ Operational mode allows for commands to perform operational system tasks and view system and service status, while configuration mode allows for the @@ -67,6 +72,9 @@ When viewing in page mode the following commands are available: * **[left-arrow]** and **[right-arrow]** can be used to scroll left or right in the event that the output has lines which exceed the terminal size. +Configuration Mode +################## + To enter configuration mode use the `configure` command: .. code-block:: none @@ -85,3 +93,732 @@ To enter configuration mode use the `configure` command: See the configuration section of this document for more information on configuration mode. + + +.. _configuration-overview: + + +###################### +Configuration Overview +###################### + +VyOS makes use of a unified configuration file for the entire system's +configuration: ``/config/config.boot``. This allows easy template +creation, backup, and replication of system configuration. A system can +thus also be easily cloned by simply copying the required configuration +files. + +Terminology +########### + +A VyOS system has three major types of configurations: + +* **Active** or **running configuration** is the system configuration + that is loaded and currently active (used by VyOS). Any change in + the configuration will have to be committed to belong to the + active/running configuration. + +* **Working configuration** is the one that is currently being modified + in configuration mode. Changes made to the working configuration do + not go into effect until the changes are committed with the + :cfgcmd:`commit` command. At which time the working configuration will + become the active or running configuration. + +* **Saved configuration** is the one saved to a file using the + :cfgcmd:`save` command. It allows you to keep safe a configuration for + future uses. There can be multiple configuration files. The default or + "boot" configuration is saved and loaded from the file + ``/config/config.boot``. + +Seeing and navigating the configuration +####################################### + +.. opcmd:: show configuration + + View the current active configuration, also known as the running + configuration, from the operational mode. + + .. code-block:: none + + vyos@vyos:~$ show configuration + interfaces { + ethernet eth0 { + address dhcp + hw-id 00:53:00:00:aa:01 + } + loopback lo { + } + } + service { + ssh { + port 22 + } + } + system { + config-management { + commit-revisions 20 + } + console { + device ttyS0 { + speed 9600 + } + } + login { + user vyos { + authentication { + encrypted-password **************** + } + level admin + } + } + ntp { + server 0.pool.ntp.org { + } + server 1.pool.ntp.org { + } + server 2.pool.ntp.org { + } + } + syslog { + global { + facility all { + level notice + } + facility protocols { + level debug + } + } + } + } + +By default, the configuration is displayed in a hierarchy like the above +example, this is only one of the possible ways to display the +configuration. When the configuration is generated and the device is +configured, changes are added through a collection of :cfgcmd:`set` and +:cfgcmd:`delete` commands. + +.. opcmd:: show configuration commands + + Get a collection of all the set commands required which led to the + running configuration. + + .. code-block:: none + + vyos@vyos:~$ show configuration commands + set interfaces ethernet eth0 address 'dhcp' + set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' + set interfaces loopback 'lo' + set service ssh port '22' + set system config-management commit-revisions '20' + set system console device ttyS0 speed '9600' + set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' + set system login user vyos level 'admin' + set system ntp server '0.pool.ntp.org' + set system ntp server '1.pool.ntp.org' + set system ntp server '2.pool.ntp.org' + set system syslog global facility all level 'notice' + set system syslog global facility protocols level 'debug' + +Both these ``show`` commands should be executed when in operational +mode, they do not work directly in configuration mode. There is a +special way on how to `run_opmode_from_config_mode`_ + +.. hint:: Use the ``show configuration commands | strip-private`` + command when you want to hide private data. You may want to do so if + you want to share your configuration on the `forum`_. + +.. _`forum`: https://forum.vyos.io + + +The config mode +=============== + +When entering the configuration mode you are navigating inside a tree +structure, to enter configuration mode enter the command +:opcmd:`configure` when in operational mode. + +.. code-block:: none + + vyos@vyos$ configure + [edit] + vyos@vyos# + + +.. note:: When going into configuration mode, prompt changes from + ``$`` to ``#``. + + +All commands executed here are relative to the configuration level you +have entered. You can do everything from the top level, but commands +will be quite lengthy when manually typing them. + +The current hierarchy level can be changed by the :cfgcmd:`edit` +command. + +.. code-block:: none + + [edit] + 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. Use +eithe the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top +of the hierarchy. You can also use the :cfgcmd:`up` command to move only +one level up at a time. + +.. cfgcmd:: show + +The :cfgcmd:`show` command within configuration mode will show the +working configuration indicating line changes with ``+`` for additions, +``>`` for replacements and ``-`` for deletions. + +**Example:** + +.. code-block:: none + + vyos@vyos:~$ configure + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + description MY_OLD_DESCRIPTION + disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } + [edit] + vyos@vyos# set interfaces ethernet eth0 address dhcp + [edit] + vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION + [edit] + vyos@vyos# delete interfaces ethernet eth0 disable + [edit] + vyos@vyos# show interfaces + ethernet eth0 { + + address dhcp + > description MY_NEW_DESCRIPTION + - disable + hw-id 00:53:dd:44:3b:03 + } + loopback lo { + } + +It is also possible to display all `set` commands within configuration +mode using :cfgcmd:`show | commands` + +.. code-block:: none + + vyos@vyos# show interfaces ethernet eth0 | commands + set address dhcp + set hw-id 00:53:ad:44:3b:03 + +These commands are also relative to the level you are inside and only +relevant configuration blocks will be displayed when entering a +sub-level. + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# show + address dhcp + hw-id 00:53:ad:44:3b:03 + +Exiting from the configuration mode is done via the :cfgcmd:`exit` +command from the top level, executing :cfgcmd:`exit` from within a +sub-level takes you back to the top level. + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# exit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + + +Editing the configuration +######################### + +The configuration can be edited by the use of :cfgcmd:`set` and +:cfgcmd:`delete` commands from within configuration mode. + +.. cfgcmd:: set + + Use this command to set the value of a parameter or to create a new + element. + +Configuration commands are flattened from the tree into 'one-liner' +commands shown in :opcmd:`show configuration commands` from operation +mode. Commands are relative to the level where they are executed and all +redundant information from the current level is removed from the command +entered. + +.. code-block:: none + + [edit] + vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 + + +.. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# set address 203.0.113.6/24 + + +These two commands above are essentially the same, just executed from +different levels in the hierarchy. + +.. cfgcmd:: delete + + To delete a configuration entry use the :cfgcmd:`delete` command, + this also deletes all sub-levels under the current level you've + specified in the :cfgcmd:`delete` command. Deleting an entry will + also result in the element reverting back to its default value if one + exists. + + .. code-block:: none + + [edit interfaces ethernet eth0] + vyos@vyos# delete address 192.0.2.100/24 + +.. cfgcmd:: commit + + Any change you do on the configuration, will not take effect until + committed using the :cfgcmd:`commit` command in configuration mode. + + .. code-block:: none + + vyos@vyos# commit + [edit] + vyos@vyos# exit + Warning: configuration changes have not been saved. + vyos@vyos:~$ + +.. _save: + +.. cfgcmd:: save + + Use this command to preserve configuration changes upon reboot. By + default it is stored at */config/config.boot*. In the case you want + to store the configuration file somewhere else, you can add a local + path, an SCP address, an FTP address or a TFTP address. + + .. code-block:: none + + vyos@vyos# save + Saving configuration to '/config/config.boot'... + Done + + .. code-block:: none + + vyos@vyos# save [tab] + Possible completions: + <Enter> Save to system config file + <file> Save to file on local machine + scp://<user>:<passwd>@<host>/<file> Save to file on remote machine + ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine + tftp://<host>/<file> Save to file on remote machine + vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot + Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... + ######################################################################## 100.0% + Done + +.. cfgcmd:: exit [discard] + + Configuration mode can not be exited while uncommitted changes exist. + To exit configuration mode without applying changes, the + :cfgcmd:`exit discard` command must be used. + + All changes in the working config will thus be lost. + + .. code-block:: none + + vyos@vyos# exit + Cannot exit: configuration modified. + Use 'exit discard' to discard the changes and exit. + [edit] + vyos@vyos# exit discard + + +.. cfgcmd:: commit-confirm <minutes> + + Use this command to temporarily commit your changes and set the + number of minutes available for validation. ``confirm`` must + be entered within those minutes, otherwise the system will reboot + into the previous configuration. The default value is 10 minutes. + + + What if you are doing something dangerous? Suppose you want to setup + a firewall, and you are not sure there are no mistakes that will lock + you out of your system. You can use confirmed commit. If you issue + the ``commit-confirm`` command, your changes will be commited, and if + you don't issue issue the ``confirm`` command in 10 minutes, your + system will reboot into previous config revision. + + .. code-block:: none + + vyos@router# set interfaces ethernet eth0 firewall local name FromWorld + vyos@router# commit-confirm + commit confirm will be automatically reboot in 10 minutes unless confirmed + Proceed? [confirm]y + [edit] + vyos@router# confirm + [edit] + + + .. note:: A reboot because you did not enter ``confirm`` will not + take you necessarily to the *saved configuration*, but to the + point before the unfortunate commit. + + +.. cfgcmd:: copy + + Copy a configuration element. + + You can copy and remove configuration subtrees. Suppose you set up a + firewall ruleset ``FromWorld`` with one rule that allows traffic from + specific subnet. Now you want to setup a similar rule, but for + different subnet. Change your edit level to + ``firewall name FromWorld`` and use ``copy rule 10 to rule 20``, then + modify rule 20. + + + .. code-block:: none + + vyos@router# show firewall name FromWorld + default-action drop + rule 10 { + action accept + source { + address 203.0.113.0/24 + } + } + [edit] + vyos@router# edit firewall name FromWorld + [edit firewall name FromWorld] + vyos@router# copy rule 10 to rule 20 + [edit firewall name FromWorld] + vyos@router# set rule 20 source address 198.51.100.0/24 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + +.. cfgcmd:: rename + + Rename a configuration element. + + You can also rename config subtrees: + + .. code-block:: none + + vyos@router# rename rule 10 to rule 5 + [edit firewall name FromWorld] + vyos@router# commit + [edit firewall name FromWorld] + + Note that ``show`` command respects your edit level and from this + level you can view the modified firewall ruleset with just ``show`` + with no parameters. + + .. code-block:: none + + vyos@router# show + default-action drop + rule 5 { + action accept + source { + address 203.0.113.0/24 + } + } + rule 20 { + action accept + source { + address 198.51.100.0/24 + } + } + + +.. cfgcmd:: comment <config node> "comment text" + + Add comment as an annotation to a configuration node. + + The ``comment`` command allows you to insert a comment above the + ``<config node>`` configuration section. When shown, comments are + enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments + need to be commited, just like other config changes. + + To remove an existing comment from your current configuration, + specify an empty string enclosed in double quote marks (``""``) as + the comment text. + + Example: + + .. code-block:: none + + vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" + vyos@vyos# commit + vyos@vyos# show + firewall { + /* Yes I know this VyOS is cool */ + all-ping enable + broadcast-ping disable + ... + } + + .. note:: An important thing to note is that since the comment is + added on top of the section, it will not appear if the ``show + <section>`` command is used. With the above example, the + ``show firewall`` command would return starting after the + ``firewall {`` line, hiding the comment. + + +.. _run_opmode_from_config_mode: + +Access opmode from config mode +############################## + +When inside configuration mode you are not directly able to execute +operational commands. + +.. cfgcmd:: run + + Access to these commands are possible through the use of the + ``run [command]`` command. From this command you will have access to + everything accessible from operational mode. + + Command completion and syntax help with ``?`` and ``[tab]`` will also + work. + + .. code-block:: none + + [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 + +Managing configurations +####################### + +VyOS comes with an integrated versioning system for the system +configuration. It automatically maintains a backup of every previous +configuration which has been committed to the system. The configurations +are versioned locally for rollback but they can also be stored on a +remote host for archiving/backup reasons. + +Local Archive +============= + +Revisions are stored on disk. You can view, compare and rollback them to +any previous revisions if something goes wrong. + +.. opcmd:: show system commit + + View all existing revisions on the local system. + + .. code-block:: none + + vyos@vyos:~$ show system commit + 0 2015-03-30 08:53:03 by vyos via cli + 1 2015-03-30 08:52:20 by vyos via cli + 2 2015-03-26 21:26:01 by root via boot-config-loader + 3 2015-03-26 20:43:18 by root via boot-config-loader + 4 2015-03-25 11:06:14 by root via boot-config-loader + 5 2015-03-25 01:04:28 by root via boot-config-loader + 6 2015-03-25 00:16:47 by vyos via cli + 7 2015-03-24 23:43:45 by root via boot-config-loader + + +.. cfgcmd:: set system config-management commit-revisions <N> + + You can specify the number of revisions stored on disk. N can be in + the range of 0 - 65535. When the number of revisions exceeds the + configured value, the oldest revision is removed. The default setting + for this value is to store 100 revisions locally. + + +Compare configurations +====================== + +VyOS lets you compare different configurations. + +.. cfgcmd:: compare <saved | N> <M> + + Use this command to spot what the differences are between different + configurations. + + .. code-block:: none + + vyos@vyos# compare [tab] + Possible completions: + <Enter> Compare working & active configurations + saved Compare working & saved configurations + <N> Compare working with revision N + <N> <M> Compare revision N with M + Revisions: + 0 2013-12-17 20:01:37 root by boot-config-loader + 1 2013-12-13 15:59:31 root by boot-config-loader + 2 2013-12-12 21:56:22 vyos by cli + 3 2013-12-12 21:55:11 vyos by cli + 4 2013-12-12 21:27:54 vyos by cli + 5 2013-12-12 21:23:29 vyos by cli + 6 2013-12-12 21:13:59 root by boot-config-loader + 7 2013-12-12 16:25:19 vyos by cli + 8 2013-12-12 15:44:36 vyos by cli + 9 2013-12-12 15:42:07 root by boot-config-loader + 10 2013-12-12 15:42:06 root by init + + The command :cfgcmd:`compare` allows you to compare different type of + configurations. It also lets you compare different revisions through + the :cfgcmd:`compare N M` command, where N and M are revision + numbers. The output will describe how the configuration N is when + compared to M indicating with a plus sign (``+``) the additional + parts N has when compared to M, and indicating with a minus sign + (``-``) the lacking parts N misses when compared to M. + + .. code-block:: none + + vyos@vyos# compare 0 6 + [edit interfaces] + +dummy dum1 { + + address 10.189.0.1/31 + +} + [edit interfaces ethernet eth0] + +vif 99 { + + address 10.199.0.1/31 + +} + -vif 900 { + - address 192.0.2.4/24 + -} + + +.. opcmd:: show system commit diff <number> + + Show commit revision difference. + + +The command above also lets you see the difference between two commits. +By default the difference with the running config is shown. + +.. code-block:: none + + vyos@router# run show system commit diff 4 + [edit system] + +ipv6 { + + disable-forwarding + +} + +This means four commits ago we did ``set system ipv6 disable-forwarding``. + + +Rollback Changes +================ + +You can rollback configuration changes using the rollback command. This +will apply the selected revision and trigger a system reboot. + +.. cfgcmd:: rollback <N> + + Rollback to revision N (currently requires reboot) + + .. code-block:: none + + vyos@vyos# compare 1 + [edit system] + >host-name vyos-1 + [edit] + + vyos@vyos# rollback 1 + Proceed with reboot? [confirm][y] + Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): + The system is going down for reboot NOW! + +Remote Archive +============== + +VyOS can upload the configuration to a remote location after each call +to :cfgcmd:`commit`. You will have to set the commit-archive location. +TFTP, FTP, SCP and SFTP servers are supported. Every time a +:cfgcmd:`commit` is successfull the ``config.boot`` file will be copied +to the defined destination(s). The filename used on the remote host will +be ``config.boot-hostname.YYYYMMDD_HHMMSS``. + +.. cfgcmd:: set system config-management commit-archive location <URI> + + Specify remote location of commit archive as any of the below + :abbr:`URI (Uniform Resource Identifier)` + + * ``scp://<user>:<passwd>@<host>/<dir>`` + * ``sftp://<user>:<passwd>@<host>/<dir>`` + * ``ftp://<user>:<passwd>@<host>/<dir>`` + * ``tftp://<host>/<dir>`` + +.. note:: The number of revisions don't affect the commit-archive. + +.. note:: You may find VyOS not allowing the secure connection because + it cannot verify the legitimacy of the remote server. You can use + the workaround below to quickly add the remote host's SSH + fingerprint to your ``~/.ssh/known_hosts`` file: + + .. code-block:: none + + vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts + +Saving and loading manually +=========================== + +You can use the ``save`` and ``load`` commands if you want to manually +manage specific configuration files. + +When using the save_ command, you can add a specific location where +to store your configuration file. And, when needed it, you will be able +to load it with the ``load`` command: + +.. cfgcmd:: load <URI> + + Use this command to load a configuration which will replace the + running configuration. Define the location of the configuration file + to be loaded. You can use a path to a local file, an SCP address, an + SFTP address, an FTP address, an HTTP address, an HTTPS address or a + TFTP address. + + .. code-block:: none + + vyos@vyos# load + Possible completions: + <Enter> Load from system config file + <file> Load from file on local machine + scp://<user>:<passwd>@<host>/<file> Load from file on remote machine + sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine + http://<host>/<file> Load from file on remote machine + https://<host>/<file> Load from file on remote machine + tftp://<host>/<file> Load from file on remote machine + + + +Restore Default +=============== + +In the case you want to completely delete your configuration and restore +the default one, you can enter the following command in configuration +mode: + +.. code-block:: none + + load /opt/vyatta/etc/config.boot.default + +You will be asked if you want to continue. If you accept, you will have +to use :cfgcmd:`commit` if you want to make the changes active. + +Then you may want to :cfgcmd:`save` in order to delete the saved +configuration too. + +.. note:: If you are remotely connected, you will lose your connection. + You may want to copy first the config, edit it to ensure + connectivity, and load the edited config. diff --git a/docs/appendix/commandtree/configmode.rst b/docs/commandtree/configmode.rst index d4148c22..d4148c22 100644 --- a/docs/appendix/commandtree/configmode.rst +++ b/docs/commandtree/configmode.rst diff --git a/docs/appendix/commandtree/index.rst b/docs/commandtree/index.rst index c3bca008..c3bca008 100644 --- a/docs/appendix/commandtree/index.rst +++ b/docs/commandtree/index.rst diff --git a/docs/appendix/commandtree/operationmode.rst b/docs/commandtree/operationmode.rst index 8092f248..8092f248 100644 --- a/docs/appendix/commandtree/operationmode.rst +++ b/docs/commandtree/operationmode.rst diff --git a/docs/conf.py b/docs/conf.py index 97f31360..37af7af5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,7 @@ sys.path.append(os.path.abspath("./_ext")) # -- Project information ----------------------------------------------------- project = u'VyOS' -copyright = u'2020, VyOS maintainers and contributors' +copyright = u'2021, VyOS maintainers and contributors' author = u'VyOS maintainers and contributors' # The short X.Y version diff --git a/docs/appendix/examples/azure-vpn-bgp.rst b/docs/configexamples/azure-vpn-bgp.rst index 57f82396..57f82396 100644 --- a/docs/appendix/examples/azure-vpn-bgp.rst +++ b/docs/configexamples/azure-vpn-bgp.rst diff --git a/docs/appendix/examples/azure-vpn-dual-bgp.rst b/docs/configexamples/azure-vpn-dual-bgp.rst index cbe9a4d9..cbe9a4d9 100644 --- a/docs/appendix/examples/azure-vpn-dual-bgp.rst +++ b/docs/configexamples/azure-vpn-dual-bgp.rst diff --git a/docs/appendix/examples/bgp-ipv6-unnumbered.rst b/docs/configexamples/bgp-ipv6-unnumbered.rst index 283dcd45..283dcd45 100644 --- a/docs/appendix/examples/bgp-ipv6-unnumbered.rst +++ b/docs/configexamples/bgp-ipv6-unnumbered.rst diff --git a/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst b/docs/configexamples/dhcp-relay-through-gre-bridge.rst index f94eb67f..f94eb67f 100644 --- a/docs/appendix/examples/dhcp-relay-through-gre-bridge.rst +++ b/docs/configexamples/dhcp-relay-through-gre-bridge.rst diff --git a/docs/appendix/examples/dmvpn.rst b/docs/configexamples/dmvpn.rst index 30ca8e86..30ca8e86 100644 --- a/docs/appendix/examples/dmvpn.rst +++ b/docs/configexamples/dmvpn.rst diff --git a/docs/appendix/examples/index.rst b/docs/configexamples/index.rst index 5216b18f..073bc125 100644 --- a/docs/appendix/examples/index.rst +++ b/docs/configexamples/index.rst @@ -1,20 +1,19 @@ .. _examples: -Configuration Examples -====================== - -This chapter contains various configuration Examples +Configuration Blueprints +======================== +This chapter contains various configuration examples: .. toctree:: :maxdepth: 2 - dmvpn + dhcp-relay-through-gre-bridge zone-policy bgp-ipv6-unnumbered ospf-unnumbered azure-vpn-bgp azure-vpn-dual-bgp tunnelbroker-ipv6 - dhcp-relay-through-gre-bridge wan-load-balancing + dmvpn diff --git a/docs/appendix/examples/ospf-unnumbered.rst b/docs/configexamples/ospf-unnumbered.rst index 84fc691e..84fc691e 100644 --- a/docs/appendix/examples/ospf-unnumbered.rst +++ b/docs/configexamples/ospf-unnumbered.rst diff --git a/docs/appendix/examples/tunnelbroker-ipv6.rst b/docs/configexamples/tunnelbroker-ipv6.rst index ca3921ec..ca3921ec 100644 --- a/docs/appendix/examples/tunnelbroker-ipv6.rst +++ b/docs/configexamples/tunnelbroker-ipv6.rst diff --git a/docs/appendix/examples/wan-load-balancing.rst b/docs/configexamples/wan-load-balancing.rst index 7093defe..7093defe 100644 --- a/docs/appendix/examples/wan-load-balancing.rst +++ b/docs/configexamples/wan-load-balancing.rst diff --git a/docs/appendix/examples/zone-policy.rst b/docs/configexamples/zone-policy.rst index 7a25d063..7a25d063 100644 --- a/docs/appendix/examples/zone-policy.rst +++ b/docs/configexamples/zone-policy.rst diff --git a/docs/configuration-overview.rst b/docs/configuration-overview.rst deleted file mode 100644 index 71bfc360..00000000 --- a/docs/configuration-overview.rst +++ /dev/null @@ -1,730 +0,0 @@ -.. _configuration-overview: - -###################### -Configuration Overview -###################### - -VyOS makes use of a unified configuration file for the entire system's -configuration: ``/config/config.boot``. This allows easy template -creation, backup, and replication of system configuration. A system can -thus also be easily cloned by simply copying the required configuration -files. - -Terminology -=========== -live -A VyOS system has three major types of configurations: - -* **Active** or **running configuration** is the system configuration - that is loaded and currently active (used by VyOS). Any change in - the configuration will have to be committed to belong to the - active/running configuration. - -* **Working configuration** is the one that is currently being modified - in configuration mode. Changes made to the working configuration do - not go into effect until the changes are committed with the - :cfgcmd:`commit` command. At which time the working configuration will - become the active or running configuration. - -* **Saved configuration** is the one saved to a file using the - :cfgcmd:`save` command. It allows you to keep safe a configuration for - future uses. There can be multiple configuration files. The default or - "boot" configuration is saved and loaded from the file - ``/config/config.boot``. - -Seeing and navigating the configuration -======================================= - -.. opcmd:: show configuration - - View the current active configuration, also known as the running - configuration, from the operational mode. - - .. code-block:: none - - vyos@vyos:~$ show configuration - interfaces { - ethernet eth0 { - address dhcp - hw-id 00:53:00:00:aa:01 - } - loopback lo { - } - } - service { - ssh { - port 22 - } - } - system { - config-management { - commit-revisions 20 - } - console { - device ttyS0 { - speed 9600 - } - } - login { - user vyos { - authentication { - encrypted-password **************** - } - level admin - } - } - ntp { - server 0.pool.ntp.org { - } - server 1.pool.ntp.org { - } - server 2.pool.ntp.org { - } - } - syslog { - global { - facility all { - level notice - } - facility protocols { - level debug - } - } - } - } - -By default, the configuration is displayed in a hierarchy like the above -example, this is only one of the possible ways to display the -configuration. When the configuration is generated and the device is -configured, changes are added through a collection of :cfgcmd:`set` and -:cfgcmd:`delete` commands. - -.. opcmd:: show configuration commands - - Get a collection of all the set commands required which led to the - running configuration. - - .. code-block:: none - - vyos@vyos:~$ show configuration commands - set interfaces ethernet eth0 address 'dhcp' - set interfaces ethernet eth0 hw-id '00:53:dd:44:3b:0f' - set interfaces loopback 'lo' - set service ssh port '22' - set system config-management commit-revisions '20' - set system console device ttyS0 speed '9600' - set system login user vyos authentication encrypted-password '$6$Vt68...QzF0' - set system login user vyos level 'admin' - set system ntp server '0.pool.ntp.org' - set system ntp server '1.pool.ntp.org' - set system ntp server '2.pool.ntp.org' - set system syslog global facility all level 'notice' - set system syslog global facility protocols level 'debug' - -Both these ``show`` commands should be executed when in operational -mode, they do not work directly in configuration mode. There is a -special way on how to :ref:`run_opmode_from_config_mode`. - -.. hint:: Use the ``show configuration commands | strip-private`` - command when you want to hide private data. You may want to do so if - you want to share your configuration on the `forum`_. - -.. _`forum`: https://forum.vyos.io - - -The config mode ---------------- - -When entering the configuration mode you are navigating inside a tree -structure, to enter configuration mode enter the command -:opcmd:`configure` when in operational mode. - -.. code-block:: none - - vyos@vyos$ configure - [edit] - vyos@vyos# - - -.. note:: When going into configuration mode, prompt changes from - ``$`` to ``#``. - - -All commands executed here are relative to the configuration level you -have entered. You can do everything from the top level, but commands -will be quite lengthy when manually typing them. - -The current hierarchy level can be changed by the :cfgcmd:`edit` -command. - -.. code-block:: none - - [edit] - 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. Use -eithe the :cfgcmd:`top` or :cfgcmd:`exit` command to go back to the top -of the hierarchy. You can also use the :cfgcmd:`up` command to move only -one level up at a time. - -.. cfgcmd:: show - -The :cfgcmd:`show` command within configuration mode will show the -working configuration indicating line changes with ``+`` for additions, -``>`` for replacements and ``-`` for deletions. - -**Example:** - -.. code-block:: none - - vyos@vyos:~$ configure - [edit] - vyos@vyos# show interfaces - ethernet eth0 { - description MY_OLD_DESCRIPTION - disable - hw-id 00:53:dd:44:3b:03 - } - loopback lo { - } - [edit] - vyos@vyos# set interfaces ethernet eth0 address dhcp - [edit] - vyos@vyos# set interfaces ethernet eth0 description MY_NEW_DESCRIPTION - [edit] - vyos@vyos# delete interfaces ethernet eth0 disable - [edit] - vyos@vyos# show interfaces - ethernet eth0 { - + address dhcp - > description MY_NEW_DESCRIPTION - - disable - hw-id 00:53:dd:44:3b:03 - } - loopback lo { - } - -It is also possible to display all `set` commands within configuration -mode using :cfgcmd:`show | commands` - -.. code-block:: none - - vyos@vyos# show interfaces ethernet eth0 | commands - set address dhcp - set hw-id 00:53:ad:44:3b:03 - -These commands are also relative to the level you are inside and only -relevant configuration blocks will be displayed when entering a -sub-level. - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# show - address dhcp - hw-id 00:53:ad:44:3b:03 - -Exiting from the configuration mode is done via the :cfgcmd:`exit` -command from the top level, executing :cfgcmd:`exit` from within a -sub-level takes you back to the top level. - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# exit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - - -Editing the configuration -========================= - -The configuration can be edited by the use of :cfgcmd:`set` and -:cfgcmd:`delete` commands from within configuration mode. - -.. cfgcmd:: set - - Use this command to set the value of a parameter or to create a new - element. - -Configuration commands are flattened from the tree into 'one-liner' -commands shown in :opcmd:`show configuration commands` from operation -mode. Commands are relative to the level where they are executed and all -redundant information from the current level is removed from the command -entered. - -.. code-block:: none - - [edit] - vyos@vyos# set interface ethernet eth0 address 192.0.2.100/24 - - -.. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# set address 203.0.113.6/24 - - -These two commands above are essentially the same, just executed from -different levels in the hierarchy. - -.. cfgcmd:: delete - - To delete a configuration entry use the :cfgcmd:`delete` command, - this also deletes all sub-levels under the current level you've - specified in the :cfgcmd:`delete` command. Deleting an entry will - also result in the element reverting back to its default value if one - exists. - - .. code-block:: none - - [edit interfaces ethernet eth0] - vyos@vyos# delete address 192.0.2.100/24 - -.. cfgcmd:: commit - - Any change you do on the configuration, will not take effect until - committed using the :cfgcmd:`commit` command in configuration mode. - - .. code-block:: none - - vyos@vyos# commit - [edit] - vyos@vyos# exit - Warning: configuration changes have not been saved. - vyos@vyos:~$ - -.. _save: - -.. cfgcmd:: save - - Use this command to preserve configuration changes upon reboot. By - default it is stored at */config/config.boot*. In the case you want - to store the configuration file somewhere else, you can add a local - path, an SCP address, an FTP address or a TFTP address. - - .. code-block:: none - - vyos@vyos# save - Saving configuration to '/config/config.boot'... - Done - - .. code-block:: none - - vyos@vyos# save [tab] - Possible completions: - <Enter> Save to system config file - <file> Save to file on local machine - scp://<user>:<passwd>@<host>/<file> Save to file on remote machine - ftp://<user>:<passwd>@<host>/<file> Save to file on remote machine - tftp://<host>/<file> Save to file on remote machine - vyos@vyos# save tftp://192.168.0.100/vyos-test.config.boot - Saving configuration to 'tftp://192.168.0.100/vyos-test.config.boot'... - ######################################################################## 100.0% - Done - -.. cfgcmd:: exit [discard] - - Configuration mode can not be exited while uncommitted changes exist. - To exit configuration mode without applying changes, the - :cfgcmd:`exit discard` command must be used. - - All changes in the working config will thus be lost. - - .. code-block:: none - - vyos@vyos# exit - Cannot exit: configuration modified. - Use 'exit discard' to discard the changes and exit. - [edit] - vyos@vyos# exit discard - - -.. cfgcmd:: commit-confirm <minutes> - - Use this command to temporarily commit your changes and set the - number of minutes available for validation. ``confirm`` must - be entered within those minutes, otherwise the system will reboot - into the previous configuration. The default value is 10 minutes. - - - What if you are doing something dangerous? Suppose you want to setup - a firewall, and you are not sure there are no mistakes that will lock - you out of your system. You can use confirmed commit. If you issue - the ``commit-confirm`` command, your changes will be commited, and if - you don't issue issue the ``confirm`` command in 10 minutes, your - system will reboot into previous config revision. - - .. code-block:: none - - vyos@router# set interfaces ethernet eth0 firewall local name FromWorld - vyos@router# commit-confirm - commit confirm will be automatically reboot in 10 minutes unless confirmed - Proceed? [confirm]y - [edit] - vyos@router# confirm - [edit] - - - .. note:: A reboot because you did not enter ``confirm`` will not - take you necessarily to the *saved configuration*, but to the - point before the unfortunate commit. - - -.. cfgcmd:: copy - - Copy a configuration element. - - You can copy and remove configuration subtrees. Suppose you set up a - firewall ruleset ``FromWorld`` with one rule that allows traffic from - specific subnet. Now you want to setup a similar rule, but for - different subnet. Change your edit level to - ``firewall name FromWorld`` and use ``copy rule 10 to rule 20``, then - modify rule 20. - - - .. code-block:: none - - vyos@router# show firewall name FromWorld - default-action drop - rule 10 { - action accept - source { - address 203.0.113.0/24 - } - } - [edit] - vyos@router# edit firewall name FromWorld - [edit firewall name FromWorld] - vyos@router# copy rule 10 to rule 20 - [edit firewall name FromWorld] - vyos@router# set rule 20 source address 198.51.100.0/24 - [edit firewall name FromWorld] - vyos@router# commit - [edit firewall name FromWorld] - - -.. cfgcmd:: rename - - Rename a configuration element. - - You can also rename config subtrees: - - .. code-block:: none - - vyos@router# rename rule 10 to rule 5 - [edit firewall name FromWorld] - vyos@router# commit - [edit firewall name FromWorld] - - Note that ``show`` command respects your edit level and from this - level you can view the modified firewall ruleset with just ``show`` - with no parameters. - - .. code-block:: none - - vyos@router# show - default-action drop - rule 5 { - action accept - source { - address 203.0.113.0/24 - } - } - rule 20 { - action accept - source { - address 198.51.100.0/24 - } - } - - -.. cfgcmd:: comment <config node> "comment text" - - Add comment as an annotation to a configuration node. - - The ``comment`` command allows you to insert a comment above the - ``<config node>`` configuration section. When shown, comments are - enclosed with ``/*`` and ``*/`` as open/close delimiters. Comments - need to be commited, just like other config changes. - - To remove an existing comment from your current configuration, - specify an empty string enclosed in double quote marks (``""``) as - the comment text. - - Example: - - .. code-block:: none - - vyos@vyos# comment firewall all-ping "Yes I know this VyOS is cool" - vyos@vyos# commit - vyos@vyos# show - firewall { - /* Yes I know this VyOS is cool */ - all-ping enable - broadcast-ping disable - ... - } - - .. note:: An important thing to note is that since the comment is - added on top of the section, it will not appear if the ``show - <section>`` command is used. With the above example, the `show - firewall` command would return starting after the ``firewall - {`` line, hiding the comment. - - - - - - -.. _run_opmode_from_config_mode: - -Access opmode from config mode -============================== - -When inside configuration mode you are not directly able to execute -operational commands. - -.. cfgcmd:: run - - Access to these commands are possible through the use of the - ``run [command]`` command. From this command you will have access to - everything accessible from operational mode. - - Command completion and syntax help with ``?`` and ``[tab]`` will also - work. - - .. code-block:: none - - [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 - -Managing configurations -======================= - -VyOS comes with an integrated versioning system for the system -configuration. It automatically maintains a backup of every previous -configuration which has been committed to the system. The configurations -are versioned locally for rollback but they can also be stored on a -remote host for archiving/backup reasons. - -Local Archive -------------- - -Revisions are stored on disk. You can view, compare and rollback them to -any previous revisions if something goes wrong. - -.. opcmd:: show system commit - - View all existing revisions on the local system. - - .. code-block:: none - - vyos@vyos:~$ show system commit - 0 2015-03-30 08:53:03 by vyos via cli - 1 2015-03-30 08:52:20 by vyos via cli - 2 2015-03-26 21:26:01 by root via boot-config-loader - 3 2015-03-26 20:43:18 by root via boot-config-loader - 4 2015-03-25 11:06:14 by root via boot-config-loader - 5 2015-03-25 01:04:28 by root via boot-config-loader - 6 2015-03-25 00:16:47 by vyos via cli - 7 2015-03-24 23:43:45 by root via boot-config-loader - - -.. cfgcmd:: set system config-management commit-revisions <N> - - You can specify the number of revisions stored on disk. N can be in - the range of 0 - 65535. When the number of revisions exceeds the - configured value, the oldest revision is removed. The default setting - for this value is to store 100 revisions locally. - - -Compare configurations ----------------------- - -VyOS lets you compare different configurations. - -.. cfgcmd:: compare <saved | N> <M> - - Use this command to spot what the differences are between different - configurations. - - .. code-block:: none - - vyos@vyos# compare [tab] - Possible completions: - <Enter> Compare working & active configurations - saved Compare working & saved configurations - <N> Compare working with revision N - <N> <M> Compare revision N with M - Revisions: - 0 2013-12-17 20:01:37 root by boot-config-loader - 1 2013-12-13 15:59:31 root by boot-config-loader - 2 2013-12-12 21:56:22 vyos by cli - 3 2013-12-12 21:55:11 vyos by cli - 4 2013-12-12 21:27:54 vyos by cli - 5 2013-12-12 21:23:29 vyos by cli - 6 2013-12-12 21:13:59 root by boot-config-loader - 7 2013-12-12 16:25:19 vyos by cli - 8 2013-12-12 15:44:36 vyos by cli - 9 2013-12-12 15:42:07 root by boot-config-loader - 10 2013-12-12 15:42:06 root by init - - The command :cfgcmd:`compare` allows you to compare different type of - configurations. It also lets you compare different revisions through - the :cfgcmd:`compare N M` command, where N and M are revision - numbers. The output will describe how the configuration N is when - compared to M indicating with a plus sign (``+``) the additional - parts N has when compared to M, and indicating with a minus sign - (``-``) the lacking parts N misses when compared to M. - - .. code-block:: none - - vyos@vyos# compare 0 6 - [edit interfaces] - +dummy dum1 { - + address 10.189.0.1/31 - +} - [edit interfaces ethernet eth0] - +vif 99 { - + address 10.199.0.1/31 - +} - -vif 900 { - - address 192.0.2.4/24 - -} - - -.. opcmd:: show system commit diff <number> - - Show commit revision difference. - - -The command above also lets you see the difference between two commits. -By default the difference with the running config is shown. - -.. code-block:: none - - vyos@router# run show system commit diff 4 - [edit system] - +ipv6 { - + disable-forwarding - +} - -This means four commits ago we did ``set system ipv6 disable-forwarding``. - - -Rollback Changes ----------------- - -You can rollback configuration changes using the rollback command. This -will apply the selected revision and trigger a system reboot. - -.. cfgcmd:: rollback <N> - - Rollback to revision N (currently requires reboot) - - .. code-block:: none - - vyos@vyos# compare 1 - [edit system] - >host-name vyos-1 - [edit] - - vyos@vyos# rollback 1 - Proceed with reboot? [confirm][y] - Broadcast message from root@vyos-1 (pts/0) (Tue Dec 17 21:07:45 2013): - The system is going down for reboot NOW! - -Remote Archive --------------- - -VyOS can upload the configuration to a remote location after each call -to :cfgcmd:`commit`. You will have to set the commit-archive location. -TFTP, FTP, SCP and SFTP servers are supported. Every time a -:cfgcmd:`commit` is successfull the ``config.boot`` file will be copied -to the defined destination(s). The filename used on the remote host will -be ``config.boot-hostname.YYYYMMDD_HHMMSS``. - -.. cfgcmd:: set system config-management commit-archive location <URI> - - Specify remote location of commit archive as any of the below - :abbr:`URI (Uniform Resource Identifier)` - - * ``scp://<user>:<passwd>@<host>/<dir>`` - * ``sftp://<user>:<passwd>@<host>/<dir>`` - * ``ftp://<user>:<passwd>@<host>/<dir>`` - * ``tftp://<host>/<dir>`` - -.. note:: The number of revisions don't affect the commit-archive. - -.. note:: You may find VyOS not allowing the secure connection because - it cannot verify the legitimacy of the remote server. You can use - the workaround below to quickly add the remote host's SSH - fingerprint to your ``~/.ssh/known_hosts`` file: - - .. code-block:: none - - vyos@vyos# ssh-keyscan <host> >> ~/.ssh/known_hosts - -Saving and loading manually ---------------------------- - -You can use the ``save`` and ``load`` commands if you want to manually -manage specific configuration files. - -When using the save_ command, you can add a specific location where -to store your configuration file. And, when needed it, you will be able -to load it with the ``load`` command: - -.. cfgcmd:: load <URI> - - Use this command to load a configuration which will replace the - running configuration. Define the location of the configuration file - to be loaded. You can use a path to a local file, an SCP address, an - SFTP address, an FTP address, an HTTP address, an HTTPS address or a - TFTP address. - - .. code-block:: none - - vyos@vyos# load - Possible completions: - <Enter> Load from system config file - <file> Load from file on local machine - scp://<user>:<passwd>@<host>/<file> Load from file on remote machine - sftp://<user>:<passwd>@<host>/<file> Load from file on remote machine - ftp://<user>:<passwd>@<host>/<file> Load from file on remote machine - http://<host>/<file> Load from file on remote machine - https://<host>/<file> Load from file on remote machine - tftp://<host>/<file> Load from file on remote machine - - - -Restore Default ---------------- - -In the case you want to completely delete your configuration and restore -the default one, you can enter the following command in configuration -mode: - -.. code-block:: none - - load /opt/vyatta/etc/config.boot.default - -You will be asked if you want to continue. If you accept, you will have -to use :cfgcmd:`commit` if you want to make the changes active. - -Then you may want to :cfgcmd:`save` in order to delete the saved -configuration too. - -.. note:: If you are remotely connected, you will lose your connection. - You may want to copy first the config, edit it to ensure - connectivity, and load the edited config. diff --git a/docs/firewall.rst b/docs/configuration/firewall/index.rst index 59bbaa31..ed255916 100644 --- a/docs/firewall.rst +++ b/docs/configuration/firewall/index.rst @@ -17,16 +17,6 @@ use of the `FORWARD` chain and either the input or output interface. The `INPUT` chain, which is used for local traffic to the OS, is a reference to as `local` with respect to its input interface. -Zone-based Firewall Policy --------------------------- - -As an alternative to applying policy to an interface directly, a zone-based -firewall can be created to simplify configuration when multiple interfaces -belong to the same security zone. Instead of applying to rulesets to interfaces -they are applied to source zone-destination zone pairs. - -An example to zone-based firewalls can be found here: :ref:`examples-zone-policy`. - Groups ------ @@ -100,6 +90,72 @@ Once a rule-set is created, it can be applied to an interface. set interfaces ethernet eth1 firewall out name INSIDE-OUT +.. _routing-mss-clamp: + +TCP-MSS Clamping +---------------- + +As Internet wide PMTU discovery rarely works, we sometimes need to clamp +our TCP MSS value to a specific value. This is a field in the TCP +Options part of a SYN packet. By setting the MSS value, you are telling +the remote side unequivocally 'do not try to send me packets bigger than +this value'. + +Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS +value for IPv4 and IPv6. + + +.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting + in 1452 bytes on a 1492 byte MTU. + + +IPv4 +^^^^ + +.. cfgcmd:: set firewall options interface <interface> adjust-mss <number-of-bytes> + + Use this command to set the maximum segment size for IPv4 transit + packets on a specific interface (500-1460 bytes). + + +Example +""""""" + +Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and +`1372` +for your WireGuard `wg02` tunnel. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss '1452' + set firewall options interface wg02 adjust-mss '1372' + +IPv6 +^^^^^ + +.. cfgcmd:: set firewall options interface <interface> adjust-mss6 <number-of-bytes> + + Use this command to set the maximum segment size for IPv6 transit + packets on a specific interface (1280-1492 bytes). + + +Example +""""""" + +Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and +`wg02` interface. + +.. code-block:: none + + set firewall options interface pppoe0 adjust-mss6 '1280' + set firewall options interface wg02 adjust-mss6 '1280' + + + +.. hint:: When doing your byte calculations, you might find useful this + `Visual packet size calculator <https://baturin.org/tools/encapcalc/>`_. + + Applying a Rule-Set to a Zone ----------------------------- diff --git a/docs/high-availability.rst b/docs/configuration/highavailability/index.rst index 81cc2d44..81cc2d44 100644 --- a/docs/high-availability.rst +++ b/docs/configuration/highavailability/index.rst diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst new file mode 100644 index 00000000..ee2c6354 --- /dev/null +++ b/docs/configuration/index.rst @@ -0,0 +1,22 @@ +################### +Configuration Guide +################### + +The following structure respresent the cli structure. + +.. toctree:: + :maxdepth: 1 + :includehidden: + + firewall/index + highavailability/index + interfaces/index + loadbalancing/index + nat/index + policy/index + protocols/index + service/index + system/index + trafficpolicy/index + vpn/index + zonepolicy/index
\ No newline at end of file diff --git a/docs/interfaces/bonding.rst b/docs/configuration/interfaces/bonding.rst index 76c8714a..76c8714a 100644 --- a/docs/interfaces/bonding.rst +++ b/docs/configuration/interfaces/bonding.rst diff --git a/docs/interfaces/bridging.rst b/docs/configuration/interfaces/bridge.rst index 30ece53d..30ece53d 100644 --- a/docs/interfaces/bridging.rst +++ b/docs/configuration/interfaces/bridge.rst diff --git a/docs/interfaces/dummy.rst b/docs/configuration/interfaces/dummy.rst index dea4c387..dea4c387 100644 --- a/docs/interfaces/dummy.rst +++ b/docs/configuration/interfaces/dummy.rst diff --git a/docs/configuration/interfaces/ethernet.rst b/docs/configuration/interfaces/ethernet.rst new file mode 100644 index 00000000..18530c8a --- /dev/null +++ b/docs/configuration/interfaces/ethernet.rst @@ -0,0 +1,263 @@ + +Ethernet Interfaces +------------------- +.. _interfaces-ethernet: + +Ethernet interfaces allow for the configuration of speed, duplex, and hw-id +(MAC address). Below is an example configuration: + +.. code-block:: none + + set interfaces ethernet eth1 address '192.168.0.1/24' + set interfaces ethernet eth1 address '2001:db8:1::ffff/64' + set interfaces ethernet eth1 description 'INSIDE' + set interfaces ethernet eth1 duplex 'auto' + set interfaces ethernet eth1 speed 'auto' + +Resulting in: + +.. code-block:: none + + ethernet eth1 { + address 192.168.0.1/24 + address 2001:db8:1::ffff/64 + description INSIDE + duplex auto + hw-id 00:0c:29:44:3b:19 + smp_affinity auto + speed auto + } + +In addition, Ethernet interfaces provide the extended operational commands: + +* `show interfaces ethernet <name> physical` +* `show interfaces ethernet <name> statistics` + +Statistics available are driver dependent. + +.. code-block:: none + + vyos@vyos:~$ show interfaces ethernet eth0 physical + Settings for eth0: + Supported ports: [ TP ] + Supported link modes: 10baseT/Half 10baseT/Full + 100baseT/Half 100baseT/Full + 1000baseT/Full + Supports auto-negotiation: Yes + Advertised link modes: 10baseT/Half 10baseT/Full + 100baseT/Half 100baseT/Full + 1000baseT/Full + Advertised pause frame use: No + Advertised auto-negotiation: Yes + Speed: 1000Mb/s + Duplex: Full + Port: Twisted Pair + PHYAD: 0 + Transceiver: internal + Auto-negotiation: on + MDI-X: Unknown + Supports Wake-on: d + Wake-on: d + Current message level: 0x00000007 (7) + Link detected: yes + driver: e1000 + version: 7.3.21-k8-NAPI + firmware-version: + bus-info: 0000:02:01.0 + + vyos@vyos:~$ show interfaces ethernet eth0 statistics + NIC statistics: + rx_packets: 3530 + tx_packets: 2179 + [...] + +VLAN Sub-Interfaces (802.1Q) +---------------------------- +.. _interfaces-vlan: + +802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The +term used for this is `vif`. Configuration of a tagged sub-interface is +accomplished using the configuration command +`set interfaces ethernet <name> vif <vlan-id>`. + +.. code-block:: none + + set interfaces ethernet eth1 vif 100 description 'VLAN 100' + set interfaces ethernet eth1 vif 100 address '192.168.100.1/24' + set interfaces ethernet eth1 vif 100 address '2001:db8:100::1/64' + +Resulting in: + +.. code-block:: none + + ethernet eth1 { + address 192.168.100.1/24 + address 2001:db8:100::1/64 + description INSIDE + duplex auto + hw-id 00:0c:29:44:3b:19 + smp_affinity auto + speed auto + vif 100 { + address 192.168.100.1/24 + description "VLAN 100" + } + } + +VLAN interfaces are shown as `<name>.<vlan-id>`, e.g. `eth1.100`: + +.. code-block:: none + + vyos@vyos:~$ show interfaces + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 172.16.51.129/24 u/u OUTSIDE + eth1 192.168.0.1/24 u/u INSIDE + eth1.100 192.168.100.1/24 u/u VLAN 100 + lo 127.0.0.1/8 u/u + ::1/128 + + + +.. _interfaces-qinq: + +QinQ +---- + +QinQ (802.1ad_) — allows multiple VLAN tags to be inserted into a single frame. + +QinQ can be used to tunnel vlans in a vlan. + +**vif-s** and **vif-c** stand for the ethertype tags that get set: + +The inner tag is the tag which is closest to the payload portion of the frame; it is officially called C-TAG (Customer tag, with ethertype 0x8100). +The outer tag is the one closer/closest to the Ethernet header; its name is S-TAG (Service tag, ethertype 0x88a8). + +Configuration commands: + +.. code-block:: none + + interfaces + ethernet <eth[0-999]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + vif-s <[0-4096]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + vif-c <[0-4096]> + address <ipv4> + address <ipv6> + description <txt> + disable + ip + <usual IP options> + ipv6 + <usual IPv6 options> + + +Example: + +.. code-block:: none + + set interfaces ethernet eth0 vif-s 333 + set interfaces ethernet eth0 vif-s 333 address 192.0.2.10/32 + set interfaces ethernet eth0 vif-s 333 vif-c 777 + set interfaces ethernet eth0 vif-s 333 vif-c 777 address 10.10.10.10/24 + +.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad + +.. _pppoe: + + +PPPoE +===== + +There are two main ways to setup VyOS to connect over a PPPoE internet connection. This is due to most ISPs (Internet Service Providers) providing a DSL modem that is also a wireless router. + +**First Method:** (Common for Homes) + +In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an RFC1918_ address, such as 192.168.1.0/24 by default. + +For a simple home network using just the ISP's equipment, this is usually desirable. But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features. + +**Second Method:** (Common for Businesses) + +In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control it. +In order for this method to work, you will have to figure out how to make your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL Transceiver device to connect between the Ethernet link of your VyOS and the phone cable. +Once your DSL Transceiver is in Bridge Mode, you should get no IP address from it. +Please make sure you connect to the Ethernet Port 1 if your DSL Transeiver has a switch, as some of them only work this way. +Once you have an Ethernet device connected, i.e. eth0, then you can configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. + +**Here is an example configuration:** + +.. code-block:: none + + set interface ethernet eth0 description "DSL Modem" + set interface ethernet eth0 duplex auto + set interface ethernet eth0 smp_affinity auto + set interface ethernet eth0 speed auto + set interface ethernet eth0 pppoe 0 default-route auto + set interface ethernet eth0 pppoe 0 mtu 1492 + set interface ethernet eth0 pppoe 0 name-server auto + set interface ethernet eth0 pppoe 0 user-id <PPPoE Username> + set interface ethernet eth0 pppoe 0 password <PPPoE Password> + + +* You should add a firewall to your configuration above as well by assigning it to the pppoe0 itself as shown here: + +.. code-block:: none + + set interface ethernet eth0 pppoe 0 firewall in name NET-IN + set interface ethernet eth0 pppoe 0 firewall local name NET-LOCAL + set interface ethernet eth0 pppoe 0 firewall out name NET-OUT + +* You need your PPPoE credentials from your DSL ISP in order to configure this. The usual username is in the form of name@host.net but may vary depending on ISP. +* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. If you are switching from a DHCP based ISP like cable then be aware that things like VPN links may need to have their MTU sizes adjusted to work within this limit. +* With the ``default-route`` option set to ``auto``, VyOS will only add the Default Gateway you receive from your DSL ISP to the routing table if you have no other WAN connections. If you wish to use a Dual WAN connection, change the ``default-route`` option to ``force``. + +Handling and troubleshooting +---------------------------- + +You can test connecting and disconnecting with the below commands: + +.. code-block:: none + + disconnect interface 0 + connect interface 0 + + +You can check the PPPoE connection logs with the following: + +This command shows the current statistics, status and some of the settings (i.e. MTU) for the current connection on pppoe0. + +.. code-block:: none + + show interfaces pppoe 0 + +This command shows the entire log for the PPPoE connection starting with the oldest data. Scroll down with the <space> key to reach the end where the current data is. + +.. code-block:: none + + show interfaces pppoe 0 log + + +This command shows the same log as without the 'tail' option but only starts with the last few lines and continues to show added lines until you exit with ``Ctrl + x`` + +.. code-block:: none + + show interfaces pppoe 0 log tail + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/interfaces/addresses.rst b/docs/configuration/interfaces/index.rst index 6799b027..e22c8708 100644 --- a/docs/interfaces/addresses.rst +++ b/docs/configuration/interfaces/index.rst @@ -1,3 +1,24 @@ +########## +Interfaces +########## + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + bonding + bridge + dummy + ethernet + l2tpv3 + openvpn + tunnel + vxlan + wireguard + wireless + + .. _interfaces-addresses: Interface Addresses diff --git a/docs/interfaces/l2tpv3.rst b/docs/configuration/interfaces/l2tpv3.rst index 4514412d..4514412d 100644 --- a/docs/interfaces/l2tpv3.rst +++ b/docs/configuration/interfaces/l2tpv3.rst diff --git a/docs/vpn/openvpn.rst b/docs/configuration/interfaces/openvpn.rst index 1462e202..b2559c95 100644 --- a/docs/vpn/openvpn.rst +++ b/docs/configuration/interfaces/openvpn.rst @@ -1,7 +1,8 @@ .. _openvpn: +####### OpenVPN -------- +####### Traditionally hardware routers implement IPsec exclusively due to relative ease of implementing it in hardware and insufficient CPU power for doing @@ -32,7 +33,7 @@ configured using the `set vpn` stanza, OpenVPN is configured as a network interface using `set interfaces openvpn`. OpenVPN Site-To-Site -^^^^^^^^^^^^^^^^^^^^ +#################### While many are aware of OpenVPN as a Client VPN solution, it is often overlooked as a site-to-site VPN solution due to lack of support for this mode @@ -43,7 +44,7 @@ static keys, which is simpler in many cases. In this example, we'll configure a simple site-to-site OpenVPN tunnel using a 2048-bit pre-shared key. First, one one of the systems generate the key using the operational command -`generate openvpn key <filename>`. This will generate a key with the name +``generate openvpn key <filename>``. This will generate a key with the name provided in the `/config/auth/` directory. Once generated, you will need to copy this key to the remote router. @@ -155,7 +156,7 @@ OpenVPN status can be verified using the `show openvpn` operational commands. See the built-in help for a complete list of options. OpenVPN Server -^^^^^^^^^^^^^^ +############## Multi-client server is the most popular OpenVPN mode on routers. It always uses x.509 authentication and therefore requires a PKI setup. This guide assumes you @@ -229,10 +230,10 @@ internally, so we need to create a route to the 10.23.0.0/20 network ourselves: Client Authentication -********************* +===================== OpenLDAP -======== +-------- Enterprise installations usually ship a kind of directory service which is used to have a single password store for all employees. VyOS and OpenVPN support using @@ -271,7 +272,7 @@ The required config file may look like: </Authorization> Active Directory -================ +---------------- Despite the fact that AD is a superset of LDAP @@ -357,7 +358,7 @@ A complete LDAP auth OpenVPN configuration could look like the following example } 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 @@ -370,7 +371,7 @@ using their CN attribute in the SSL certificate. Server -****** +====== .. code-block:: none @@ -394,7 +395,7 @@ Server set interfaces openvpn vtun10 use-lzo-compression Client -****** +====== .. code-block:: none @@ -411,7 +412,7 @@ Client 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 @@ -429,12 +430,12 @@ Please use this only as last resort - things might break and OpenVPN won't start if you pass invalid options/syntax. Troubleshooting -=============== +############### VyOS provides some operational commands on OpenVPN. Check status ------------- +============ The following commands let you check tunnel status. @@ -452,7 +453,7 @@ The following commands let you check tunnel status. Reset OpenVPN -------------- +============= The following commands let you reset OpenVPN. diff --git a/docs/interfaces/tunnel.rst b/docs/configuration/interfaces/tunnel.rst index 43c217a0..43c217a0 100644 --- a/docs/interfaces/tunnel.rst +++ b/docs/configuration/interfaces/tunnel.rst diff --git a/docs/interfaces/vxlan.rst b/docs/configuration/interfaces/vxlan.rst index e3eb5c43..e3eb5c43 100644 --- a/docs/interfaces/vxlan.rst +++ b/docs/configuration/interfaces/vxlan.rst diff --git a/docs/vpn/wireguard.rst b/docs/configuration/interfaces/wireguard.rst index a7241613..a7241613 100644 --- a/docs/vpn/wireguard.rst +++ b/docs/configuration/interfaces/wireguard.rst diff --git a/docs/interfaces/wireless.rst b/docs/configuration/interfaces/wireless.rst index a7e796e9..a7e796e9 100644 --- a/docs/interfaces/wireless.rst +++ b/docs/configuration/interfaces/wireless.rst diff --git a/docs/load-balancing.rst b/docs/configuration/loadbalancing/index.rst index cae2f6a5..cae2f6a5 100644 --- a/docs/load-balancing.rst +++ b/docs/configuration/loadbalancing/index.rst diff --git a/docs/nat.rst b/docs/configuration/nat/index.rst index 25e0259b..9b7b69df 100644 --- a/docs/nat.rst +++ b/docs/configuration/nat/index.rst @@ -342,7 +342,7 @@ 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_before_vpn_topology.png +.. figure:: /_static/images/nat_before_vpn_topology.png :scale: 100 % :alt: NAT before VPN Topology diff --git a/docs/routing/pbr.rst b/docs/configuration/policy/index.rst index b86e1c0b..ad829a55 100644 --- a/docs/routing/pbr.rst +++ b/docs/configuration/policy/index.rst @@ -1,3 +1,65 @@ + +###### +Policy +###### + +Routing Policies could be used to tell the router (self or neighbors) what routes and their attributes needs to be put into the routing table. + +There could be a wide range of routing policies. Some examples are below: + + * Set some metric to routes learned from a particular neighbor + * Set some attributes (like AS PATH or Community value) to advertised routes to neighbors + * Prefer a specific routing protocol routes over another routing protocol running on the same router + +Routing Policy Example +~~~~~~~~~~~~~~~~~~~~~~ + +**Policy definition:** + +.. code-block:: none + + #Create policy + set policy route-map setmet rule 2 action 'permit' + 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 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 + +**Routes learned before routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ show ip bgp + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 22.22.22.22/32 1.1.1.2 1 0 2 i < Path + + Total number of prefixes 1 + +**Routes learned after routing policy applied:** + +.. code-block:: none + + vyos@vos1:~$ sho ip b + BGP table version is 0, local router ID is 192.168.56.101 + Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, + r RIB-failure, S Stale, R Removed + Origin codes: i - IGP, e - EGP, ? - incomplete + + Network Next Hop Metric LocPrf Weight Path + *> 22.22.22.22/32 1.1.1.2 1 0 2 2 2 2 i < longer AS_path length + + Total number of prefixes 1 + vyos@vos1:~$ + + .. _routing-pbr: Policy-Based Routing (PBR) @@ -52,7 +114,7 @@ Routing tables that will be used in this example are: * ``table 11`` Routing tabled used for VLAN 11 (192.168.189.0/24) * ``main`` Routing table used by VyOS and other interfaces not paritipating in PBR -.. figure:: ../_static/images/pbr_example_1.png +.. figure:: /_static/images/pbr_example_1.png :scale: 80 % :alt: PBR multiple uplinks diff --git a/docs/routing/bgp.rst b/docs/configuration/protocols/bgp.rst index f0550fd4..f0550fd4 100644 --- a/docs/routing/bgp.rst +++ b/docs/configuration/protocols/bgp.rst diff --git a/docs/routing/multicast.rst b/docs/configuration/protocols/igmp.rst index 421c9f0f..421c9f0f 100644 --- a/docs/routing/multicast.rst +++ b/docs/configuration/protocols/igmp.rst diff --git a/docs/routing/index.rst b/docs/configuration/protocols/index.rst index dcc67bc7..a737a026 100644 --- a/docs/routing/index.rst +++ b/docs/configuration/protocols/index.rst @@ -1,7 +1,8 @@ .. _routing: -Routing -======= +######### +Protocols +######### VyOS is a "router first" network operating system. It supports static routing, policy routing, and dynamic routing using standard protocols (RIP, OSPF, and @@ -10,13 +11,8 @@ BGP). .. toctree:: :maxdepth: 1 - arp bgp - ip-commands - multicast + igmp ospf - pbr rip - routing-policy static - mss-clamp diff --git a/docs/routing/ospf.rst b/docs/configuration/protocols/ospf.rst index 1e70f644..1e70f644 100644 --- a/docs/routing/ospf.rst +++ b/docs/configuration/protocols/ospf.rst diff --git a/docs/routing/rip.rst b/docs/configuration/protocols/rip.rst index da00e7b1..da00e7b1 100644 --- a/docs/routing/rip.rst +++ b/docs/configuration/protocols/rip.rst diff --git a/docs/routing/arp.rst b/docs/configuration/protocols/static.rst index 2d08e436..8415981b 100644 --- a/docs/routing/arp.rst +++ b/docs/configuration/protocols/static.rst @@ -1,3 +1,35 @@ +.. _routing-static: + +###### +Static +###### + +Static routes are manually configured network routes. + +A typical use for a static route is a static default route for systems that do +not make use of DHCP or dynamic routing protocols: + +.. code-block:: none + + set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 distance '1' + +Another common use of static routes is to blackhole (drop) traffic. In the +example below, RFC1918_ networks are set as blackhole routes. + +This prevents these networks leaking out public interfaces, but it does not prevent +them from being used as the most specific route has the highest priority. + +.. code-block:: none + + set protocols static route 10.0.0.0/8 blackhole distance '254' + set protocols static route 172.16.0.0/12 blackhole distance '254' + set protocols static route 192.168.0.0/16 blackhole distance '254' + +.. note:: Routes with a distance of 255 are effectively disabled and not + installed into the kernel. + +.. _RFC1918: https://tools.ietf.org/html/rfc1918 + .. _routing-arp: Address Resolution Protocol (ARP) diff --git a/docs/services/udp-broadcast-relay.rst b/docs/configuration/service/broadcast-relay.rst index 40f738e6..40f738e6 100644 --- a/docs/services/udp-broadcast-relay.rst +++ b/docs/configuration/service/broadcast-relay.rst diff --git a/docs/services/conntrack.rst b/docs/configuration/service/conntrack-sync.rst index 28f16d54..28f16d54 100644 --- a/docs/services/conntrack.rst +++ b/docs/configuration/service/conntrack-sync.rst diff --git a/docs/services/dhcp-relay.rst b/docs/configuration/service/dhcp-relay.rst index 0b838442..0b838442 100644 --- a/docs/services/dhcp-relay.rst +++ b/docs/configuration/service/dhcp-relay.rst diff --git a/docs/services/dhcpv6.rst b/docs/configuration/service/dhcp-server.rst index db566d5f..f0d0a7e9 100644 --- a/docs/services/dhcpv6.rst +++ b/docs/configuration/service/dhcp-server.rst @@ -1,4 +1,143 @@ +DHCP Server +----------- + +Multiple DHCP Servers can be run from a single machine. Each DHCP service is +identified by a `shared-network-name`. + +DHCP Server Example +^^^^^^^^^^^^^^^^^^^ + +In this example, we are offering address space in the 172.16.17.0/24 network, +which is on eth1, and pppoe0 is our connection to the internet. We are using +the network name `dhcpexample`. + +Prerequisites +^^^^^^^^^^^^^ + +Configuring the PPPoE interface is assumed to be done already, and appears +on `pppoe0` + +Interface Configuration +^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + set interface ethernet eth1 address 172.16.17.1/24 + +Multiple ranges can be defined and can contain holes. + +.. code-block:: none + + set service dhcp-server shared-network-name dhcpexample authoritative + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router 172.16.17.1 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server 172.16.17.1 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 lease 86400 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 start 172.16.17.100 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 stop 172.16.17.199 + + +Explanation +^^^^^^^^^^^ + +* :code:`set service dhcp-server shared-network-name dhcpexample authoritative` + + This says that this device is the only DHCP server for this network. If other + devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to + any device trying to request an IP address that is + not valid for this network. + +* :code:`set service dhcp-server shared-network-name dhcpexample subnet + 172.16.17.0/24 default-router 172.16.17.1` + + This is a configuration parameter for the subnet, saying that as part of the + response, tell the client that I am the default router for this network + +* :code:`set service dhcp-server shared-network-name dhcpexample subnet + 172.16.17.0/24 dns-server 172.16.17.1` + + This is a configuration parameter for the subnet, saying that as part of the + response, tell the client that I am the DNS server for this network. If you + do not want to run a DNS server, you could also provide one of the public + DNS servers, such as google's. You can add multiple entries by repeating the + line. + +* :code:`set service dhcp-server shared-network-name dhcpexample subnet + 172.16.17.0/24 lease 86400` + + Assign the IP address to this machine for 24 hours. It is unlikely you'd need + to shorten this period, unless you are running a network with lots of devices + appearing and disappearing. + + +* :code:`set service dhcp-server shared-network-name dhcpexample subnet + 172.16.17.0/24 range 0 start 172.16.17.100` + + Make a range of addresses available for clients starting from .100 [...] + +* :code:`set service dhcp-server shared-network-name dhcpexample subnet + 172.16.17.0/24 range 0 stop 172.16.17.199` + + [...] and ending at .199 + + +Failover +^^^^^^^^ + +VyOS provides support for DHCP failover: + +.. code-block:: none + + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover local-address '192.168.0.1' + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover name 'foo' + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover peer-address '192.168.0.2' + +.. note:: `name` must be identical on both sides! + +The primary and secondary statements determines whether the server is +primary or secondary + +.. code-block:: none + + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary' + +or + +.. code-block:: none + + set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'secondary' + +.. note:: In order for the primary and the secondary DHCP server to keep + their lease tables in sync, they must be able to reach each other on TCP + port 647. If you have firewall rules in effect, adjust them accordingly. + +Static mappings MAC/IP +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: none + + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 ip-address 172.16.17.10 + set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 mac-address ff:ff:ff:ff:ff:ff + +DHCP server options +^^^^^^^^^^^^^^^^^^^^^^^^^ + +default-router (DHCP option 003) + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router <ROUTER-IP>` + +dns-server (DHCP option 006) + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server <DNS-SERVER-IP>` + +domain-name Client domain name (DHCP option 015) + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-name "<DOMAIN-NAME>"` + +domain-search (DHCP option 119) + This option can be given multiple times if you need multiple search domains + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_1>"` + :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_2>"` + + + DHCPv6 server ------------- diff --git a/docs/services/dynamic-dns.rst b/docs/configuration/service/dns.rst index 6a3c6e28..c83c93f9 100644 --- a/docs/services/dynamic-dns.rst +++ b/docs/configuration/service/dns.rst @@ -1,3 +1,77 @@ +DNS Forwarding +-------------- + +Use DNS forwarding if you want your router to function as a DNS server for the +local network. There are several options, the easiest being 'forward all +traffic to the system DNS server(s)' (defined with set system name-server): + +.. code-block:: none + + set service dns forwarding system + +Manually setting DNS servers for forwarding: + +.. code-block:: none + + set service dns forwarding name-server 8.8.8.8 + set service dns forwarding name-server 8.8.4.4 + +Manually setting DNS servers with IPv6 connectivity: + +.. code-block:: none + + set service dns forwarding name-server 2001:4860:4860::8888 + set service dns forwarding name-server 2001:4860:4860::8844 + +Setting a forwarding DNS server for a specific domain: + +.. code-block:: none + + set service dns forwarding domain example.com server 192.0.2.1 + +Set which networks or clients are allowed to query the DNS Server. Allow from all: + +.. code-block:: none + + set service dns forwarding allow-from 0.0.0.0/0 + +Example 1 +^^^^^^^^^ + +Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. + +* DNS request for a local domain (example.com) get forwarded to 192.0.2.1 +* Other DNS requests are forwarded to Google's DNS servers. +* The IP address for the LAN interface is 192.168.0.1. + +.. code-block:: none + + set service dns forwarding domain example.com server 192.0.2.1 + set service dns forwarding name-server 8.8.8.8 + set service dns forwarding name-server 8.8.4.4 + set service dns forwarding listen-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 + +Example 2 +^^^^^^^^^ + +Same as example 1 but with additional IPv6 addresses for Google's public DNS +servers. + +The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 + +.. code-block:: none + + set service dns forwarding domain example.com server 192.0.2.1 + set service dns forwarding name-server 8.8.8.8 + set service dns forwarding name-server 8.8.4.4 + set service dns forwarding name-server 2001:4860:4860::8888 + set service dns forwarding name-server 2001:4860:4860::8844 + set service dns forwarding listen-address 2001:db8::1 + set service dns forwarding listen-address 192.168.0.1 + set service dns forwarding allow-from 0.0.0.0/0 + + Dynamic DNS ----------- diff --git a/docs/configuration/service/index.rst b/docs/configuration/service/index.rst new file mode 100644 index 00000000..31ff4e95 --- /dev/null +++ b/docs/configuration/service/index.rst @@ -0,0 +1,21 @@ +####### +Service +####### + + +.. toctree:: + :maxdepth: 1 + :includehidden: + + broadcast-relay + conntrack-sync + dhcp-relay + dhcp-server + dns + lldp + mdns + pppoe-server + snmp + ssh + tftp-server + webproxy diff --git a/docs/services/lldp.rst b/docs/configuration/service/lldp.rst index dccd68fa..dccd68fa 100644 --- a/docs/services/lldp.rst +++ b/docs/configuration/service/lldp.rst diff --git a/docs/services/mdns-repeater.rst b/docs/configuration/service/mdns.rst index 22e824ba..22e824ba 100644 --- a/docs/services/mdns-repeater.rst +++ b/docs/configuration/service/mdns.rst diff --git a/docs/services/pppoe-server.rst b/docs/configuration/service/pppoe-server.rst index 8e37a068..8e37a068 100644 --- a/docs/services/pppoe-server.rst +++ b/docs/configuration/service/pppoe-server.rst diff --git a/docs/services/references.rst b/docs/configuration/service/references.rst index bee936d7..bee936d7 100644 --- a/docs/services/references.rst +++ b/docs/configuration/service/references.rst diff --git a/docs/services/snmp.rst b/docs/configuration/service/snmp.rst index 6418a516..6418a516 100644 --- a/docs/services/snmp.rst +++ b/docs/configuration/service/snmp.rst diff --git a/docs/services/ssh.rst b/docs/configuration/service/ssh.rst index 3af71899..3af71899 100644 --- a/docs/services/ssh.rst +++ b/docs/configuration/service/ssh.rst diff --git a/docs/services/tftp.rst b/docs/configuration/service/tftp-server.rst index 9ce46b02..9ce46b02 100644 --- a/docs/services/tftp.rst +++ b/docs/configuration/service/tftp-server.rst diff --git a/docs/services/webproxy.rst b/docs/configuration/service/webproxy.rst index 61546cda..61546cda 100644 --- a/docs/services/webproxy.rst +++ b/docs/configuration/service/webproxy.rst diff --git a/docs/system/serialconsole.rst b/docs/configuration/system/console.rst index 730c9da1..730c9da1 100644 --- a/docs/system/serialconsole.rst +++ b/docs/configuration/system/console.rst diff --git a/docs/system/eventhandler.rst b/docs/configuration/system/eventhandler.rst index 4421e79c..4421e79c 100644 --- a/docs/system/eventhandler.rst +++ b/docs/configuration/system/eventhandler.rst diff --git a/docs/system/flowaccounting.rst b/docs/configuration/system/flow-accounting.rst index 9c876001..9c876001 100644 --- a/docs/system/flowaccounting.rst +++ b/docs/configuration/system/flow-accounting.rst diff --git a/docs/system/host-information.rst b/docs/configuration/system/host-information.rst index 71209412..71209412 100644 --- a/docs/system/host-information.rst +++ b/docs/configuration/system/host-information.rst diff --git a/docs/system/index.rst b/docs/configuration/system/index.rst index a0d470aa..07ba2ff5 100644 --- a/docs/system/index.rst +++ b/docs/configuration/system/index.rst @@ -9,17 +9,16 @@ should be ready for further configuration which is described in this chapter. .. toctree:: :maxdepth: 2 - :hidden: - eventhandler - flowaccounting host-information - login-users + console + eventhandler + flow-accounting + login + ip + ipv6 + name-server ntp - proxy - serialconsole syslog - system-dns task-scheduler - time-zone - boot-options + time-zone
\ No newline at end of file diff --git a/docs/configuration/system/ip.rst b/docs/configuration/system/ip.rst new file mode 100644 index 00000000..6c158de9 --- /dev/null +++ b/docs/configuration/system/ip.rst @@ -0,0 +1,75 @@ +.. _ip: + +IPv4 +==== + +System configuration commands +----------------------------- + + +.. cfgcmd:: set system ip disable-forwarding + + Use this command to disable IPv4 forwarding on all interfaces. + + +.. cfgcmd:: set system ip arp table-size <number> + + Use this command to define the maximum number of entries to keep in + the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). + + +.. cfgcmd:: set system ip multipath layer4-hashing + + Use this command to use Layer 4 information for IPv4 ECMP hashing. + + +Operational commands +-------------------- + + +show commands +^^^^^^^^^^^^^ + +See below the different parameters available for the IPv4 **show** command: + +.. code-block:: + + vyos@vyos:~$ show ip + Possible completions: + access-list Show all IP access-lists + as-path-access-list + Show all as-path-access-lists + bgp Show Border Gateway Protocol (BGP) information + community-list + Show IP community-lists + extcommunity-list + Show extended IP community-lists + forwarding Show IP forwarding status + groups Show IP multicast group membership + igmp Show IGMP (Internet Group Management Protocol) information + large-community-list + Show IP large-community-lists + multicast Show IP multicast + ospf Show IPv4 Open Shortest Path First (OSPF) routing information + pim Show PIM (Protocol Independent Multicast) information + ports Show IP ports in use by various system services + prefix-list Show all IP prefix-lists + protocol Show IP route-maps per protocol + rip Show Routing Information Protocol (RIP) information + route Show IP routes + + +reset commands +^^^^^^^^^^^^^^ + +And the different IPv4 **reset** commands available: + +.. code-block:: + + vyos@vyos:~$ reset ip + Possible completions: + arp Reset Address Resolution Protocol (ARP) cache + bgp Clear Border Gateway Protocol (BGP) statistics or status + igmp IGMP clear commands + multicast IP multicast routing table + route Reset IP route diff --git a/docs/routing/ip-commands.rst b/docs/configuration/system/ipv6.rst index 60eb582a..8b00ccf8 100644 --- a/docs/routing/ip-commands.rst +++ b/docs/configuration/system/ipv6.rst @@ -1,84 +1,5 @@ -.. _ip-commands: +.. _ipv6: -*********** -IP commands -*********** - - -IPv4 -==== - -System configuration commands ------------------------------ - - -.. cfgcmd:: set system ip disable-forwarding - - Use this command to disable IPv4 forwarding on all interfaces. - - -.. cfgcmd:: set system ip arp table-size <number> - - Use this command to define the maximum number of entries to keep in - the ARP cache (1024, 2048, 4096, 8192, 16384, 32768). - - -.. cfgcmd:: set system ip multipath layer4-hashing - - Use this command to use Layer 4 information for IPv4 ECMP hashing. - - -Operational commands --------------------- - - -show commands -^^^^^^^^^^^^^ - -See below the different parameters available for the IPv4 **show** command: - -.. code-block:: - - vyos@vyos:~$ show ip - Possible completions: - access-list Show all IP access-lists - as-path-access-list - Show all as-path-access-lists - bgp Show Border Gateway Protocol (BGP) information - community-list - Show IP community-lists - extcommunity-list - Show extended IP community-lists - forwarding Show IP forwarding status - groups Show IP multicast group membership - igmp Show IGMP (Internet Group Management Protocol) information - large-community-list - Show IP large-community-lists - multicast Show IP multicast - ospf Show IPv4 Open Shortest Path First (OSPF) routing information - pim Show PIM (Protocol Independent Multicast) information - ports Show IP ports in use by various system services - prefix-list Show all IP prefix-lists - protocol Show IP route-maps per protocol - rip Show Routing Information Protocol (RIP) information - route Show IP routes - - -reset commands -^^^^^^^^^^^^^^ - -And the different IPv4 **reset** commands available: - -.. code-block:: - - vyos@vyos:~$ reset ip - Possible completions: - arp Reset Address Resolution Protocol (ARP) cache - bgp Clear Border Gateway Protocol (BGP) statistics or status - igmp IGMP clear commands - multicast IP multicast routing table - route Reset IP route - IPv6 ==== diff --git a/docs/system/login-users.rst b/docs/configuration/system/login.rst index c34e41a0..c34e41a0 100644 --- a/docs/system/login-users.rst +++ b/docs/configuration/system/login.rst diff --git a/docs/system/system-dns.rst b/docs/configuration/system/name-server.rst index 70848f6d..70848f6d 100644 --- a/docs/system/system-dns.rst +++ b/docs/configuration/system/name-server.rst diff --git a/docs/system/ntp.rst b/docs/configuration/system/ntp.rst index 95ff0692..95ff0692 100644 --- a/docs/system/ntp.rst +++ b/docs/configuration/system/ntp.rst diff --git a/docs/system/syslog.rst b/docs/configuration/system/syslog.rst index 9f3e1a28..9f3e1a28 100644 --- a/docs/system/syslog.rst +++ b/docs/configuration/system/syslog.rst diff --git a/docs/system/task-scheduler.rst b/docs/configuration/system/task-scheduler.rst index 7fe49988..7fe49988 100644 --- a/docs/system/task-scheduler.rst +++ b/docs/configuration/system/task-scheduler.rst diff --git a/docs/system/time-zone.rst b/docs/configuration/system/time-zone.rst index 9e1690e8..9e1690e8 100644 --- a/docs/system/time-zone.rst +++ b/docs/configuration/system/time-zone.rst diff --git a/docs/qos.rst b/docs/configuration/trafficpolicy/index.rst index 6826b83c..6beb660e 100644 --- a/docs/qos.rst +++ b/docs/configuration/trafficpolicy/index.rst @@ -1,8 +1,8 @@ .. _qos: -*** -QoS -*** +############## +Traffic Policy +############## The generic name of Quality of Service or Traffic Control involves things like shaping traffic, scheduling or dropping packets, which diff --git a/docs/vpn/dmvpn.rst b/docs/configuration/vpn/dmvpn.rst index 9da6dde2..e6487292 100644 --- a/docs/vpn/dmvpn.rst +++ b/docs/configuration/vpn/dmvpn.rst @@ -38,7 +38,7 @@ The tunnel will be set to mGRE if for encapsulation `gre` is set, and no `remote-ip` is set. If the public ip is provided by DHCP the tunnel `local-ip` can be set to "0.0.0.0". If you do set the `remote-ip` directive at any point, the interface will need to be `delete`'d from the config and recreated without the `remote-ip` config ever being set. -.. figure:: ../_static/images/vpn_dmvpn_topology01.png +.. figure:: /_static/images/vpn_dmvpn_topology01.png :scale: 40 % :alt: Baseline DMVPN topology diff --git a/docs/vpn/index.rst b/docs/configuration/vpn/index.rst index 055a2d5c..522842d1 100644 --- a/docs/vpn/index.rst +++ b/docs/configuration/vpn/index.rst @@ -10,10 +10,8 @@ This chapter describes the available VPN services provided by VyOS. .. toctree:: :hidden: - openvpn l2tp site2site_ipsec - gre-ipsec + ipsec dmvpn pptp - wireguard diff --git a/docs/vpn/gre-ipsec.rst b/docs/configuration/vpn/ipsec.rst index 38849f67..38849f67 100644 --- a/docs/vpn/gre-ipsec.rst +++ b/docs/configuration/vpn/ipsec.rst diff --git a/docs/vpn/l2tp.rst b/docs/configuration/vpn/l2tp.rst index 64223475..64223475 100644 --- a/docs/vpn/l2tp.rst +++ b/docs/configuration/vpn/l2tp.rst diff --git a/docs/vpn/pptp.rst b/docs/configuration/vpn/pptp.rst index 72b3feb0..72b3feb0 100644 --- a/docs/vpn/pptp.rst +++ b/docs/configuration/vpn/pptp.rst diff --git a/docs/vpn/references.rst b/docs/configuration/vpn/references.rst index 49b65cb0..49b65cb0 100644 --- a/docs/vpn/references.rst +++ b/docs/configuration/vpn/references.rst diff --git a/docs/vpn/site2site_ipsec.rst b/docs/configuration/vpn/site2site_ipsec.rst index bdafd6ce..e0156a6f 100644 --- a/docs/vpn/site2site_ipsec.rst +++ b/docs/configuration/vpn/site2site_ipsec.rst @@ -218,7 +218,7 @@ IKEv2 Imagine the following topology -.. figure:: ../_static/images/vpn_s2s_ikev2.png +.. figure:: /_static/images/vpn_s2s_ikev2.png :scale: 50 % :alt: IPSec IKEv2 site2site VPN diff --git a/docs/configuration/zonepolicy/index.rst b/docs/configuration/zonepolicy/index.rst new file mode 100644 index 00000000..5da40d6d --- /dev/null +++ b/docs/configuration/zonepolicy/index.rst @@ -0,0 +1,9 @@ +Zone-based Firewall Policy +-------------------------- + +As an alternative to applying policy to an interface directly, a zone-based +firewall can be created to simplify configuration when multiple interfaces +belong to the same security zone. Instead of applying to rulesets to interfaces +they are applied to source zone-destination zone pairs. + +An example to zone-based firewalls can be found here: :ref:`examples-zone-policy`.
\ No newline at end of file diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..8dd81d60 --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,13 @@ +############ +Contributing +############ + +.. toctree:: + :maxdepth: 2 + + issues-features + development + vyos_cli + coding_guidelines + upstream-packages + build-vyos
\ No newline at end of file diff --git a/docs/contributing/issues_features.rst b/docs/contributing/issues-features.rst index 02de2df6..02de2df6 100644 --- a/docs/contributing/issues_features.rst +++ b/docs/contributing/issues-features.rst diff --git a/docs/copyright.rst b/docs/copyright.rst new file mode 100644 index 00000000..b727272b --- /dev/null +++ b/docs/copyright.rst @@ -0,0 +1,19 @@ +################ +Copyright Notice +################ + +Copyright (C) 2018-2019 VyOS maintainers and contributors + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on all +copies. + +Permission is granted to copy and distribute modified versions of this manual +under the conditions for verbatim copying, provided that the entire resulting +derived work is distributed under the terms of a permission notice identical +to this one. + +Permission is granted to copy and distribute translations of this manual into +another language, under the above conditions for modified versions, except that +this permission notice may be stated in a translation approved by the VyOS +maintainers.
\ No newline at end of file diff --git a/docs/contributing/documentation.rst b/docs/documentation.rst index 40edf750..40edf750 100644 --- a/docs/contributing/documentation.rst +++ b/docs/documentation.rst diff --git a/docs/index.rst b/docs/index.rst index d0f2c6e7..e3c92e22 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,85 +4,43 @@ VyOS User Guide ############### - -.. toctree:: - :caption: Introduction - :name: intro - :maxdepth: 2 - - about - history - install - cli - quick-start - .. toctree:: - :caption: Configuration - :name: configuration - :maxdepth: 2 - - configuration-overview - interfaces/index - routing/index - firewall - nat - vpn/index - qos - services/index - system/index - high-availability - load-balancing - image-mgmt - commandscripting -.. modules + :maxdepth: 1 + introducing/about + introducing/history + changelog/index .. toctree:: - :caption: Appendix - :name: appendix :maxdepth: 2 + :includehidden: + :caption: First Steps - appendix/releasenotes - appendix/troubleshooting - appendix/examples/index - appendix/commandtree/index - appendix/vyos-on-vmware - appendix/vyos-on-gns3 - appendix/vyos-on-baremetal - appendix/migrate-from-vyatta + installation/index + quick-start + cli + commandtree/index .. toctree:: - :caption: Contributing - :name: contributing :maxdepth: 2 - - contributing/issues_features - contributing/development - contributing/documentation - contributing/vyos_cli - contributing/coding_guidelines - contributing/upstream-packages - contributing/build-vyos + :includehidden: + :caption: Adminguide + configuration/index + operation/index + automation/index + troubleshooting/index + configexamples/index -################ -Copyright Notice -################ -Copyright (C) 2018-2019 VyOS maintainers and contributors -Permission is granted to make and distribute verbatim copies of this manual -provided the copyright notice and this permission notice are preserved on all -copies. - -Permission is granted to copy and distribute modified versions of this manual -under the conditions for verbatim copying, provided that the entire resulting -derived work is distributed under the terms of a permission notice identical -to this one. +.. toctree:: + :maxdepth: 2 + :includehidden: + :caption: Development -Permission is granted to copy and distribute translations of this manual into -another language, under the above conditions for modified versions, except that -this permission notice may be stated in a translation approved by the VyOS -maintainers. + contributing/index + documentation + copyright
\ No newline at end of file diff --git a/docs/installation/cloud/index.rst b/docs/installation/cloud/index.rst new file mode 100644 index 00000000..f6060762 --- /dev/null +++ b/docs/installation/cloud/index.rst @@ -0,0 +1,9 @@ +################################## +Running VyOS in Cloud Environments +################################## + + + +.. toctree:: + :caption: Content + diff --git a/docs/image-mgmt.rst b/docs/installation/image.rst index 143d02b2..074a0245 100644 --- a/docs/image-mgmt.rst +++ b/docs/installation/image.rst @@ -90,85 +90,7 @@ configured to be the default. Copyright: VyOS maintainers and contributors -.. _update_vyos: -Update VyOS -=========== - -New system images can be added using the :opcmd:`add system image` -command. The command will extract the chosen image and will prompt you -to use the current system configuration and SSH security keys, allowing -for the new image to boot using the current configuration. - -.. note:: Only LTS releases are PGP-signed. - -.. opcmd:: add system image <url | path> [vrf name] [username user [password pass]] - - Use this command to install a new system image. You can reach the - image from the web (http://, https://) or from your local system, - e.g. /tmp/vyos-1.2.3-amd64.iso. - - The `add system image` command also supports installing new versions - of VyOS through an optional given VRF. Also if URL in question requires - authentication, you can specify an optional username and password via - the commandline which will be passed as "Basic-Auth" to the server. - -If there is not enough **free disk space available**, the installation -will be canceled. To delete images use the :opcmd:`delete system image` -command. - -VyOS configuration is associated to each image, and **each image has a -unique copy of its configuration**. This is different than a traditional -network router where the configuration is shared across all images. - -.. note:: If you have any personal files, like some scripts you created, - and you don't want them to be lost during the upgrade, make sure - those files are stored in ``/config`` as this directory is always copied - to newer installed images. - -You can access files from a previous installation and copy them to your -current image if they were located in the ``/config`` directory. This -can be done using the :opcmd:`copy` command. So, for instance, in order -to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the -following command: - -.. code:: - - copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 - - -Example -""""""" - -.. code-block:: none - - vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k - ISO download succeeded. - Checking for digital signature file... - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 - curl: (22) The requested URL returned error: 404 Not Found - - Unable to fetch digital signature file. - Do you want to continue without signature check? (yes/no) [yes] - Checking MD5 checksums of files on the ISO image...OK. - Done! - - What would you like to name this image? [vyos-1.3-rolling-201912201452]: - - OK. This image will be named: vyos-1.3-rolling-201912201452 - - -.. hint:: | The most up-do-date Rolling Release for AMD64 can be accessed using the following URL: - | https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - -After reboot you might want to verify the version you are running with -the :opcmd:`show version` command. System rollback diff --git a/docs/installation/index.rst b/docs/installation/index.rst new file mode 100644 index 00000000..187f3bf1 --- /dev/null +++ b/docs/installation/index.rst @@ -0,0 +1,17 @@ +################################# +Installation and Image Management +################################# + + + +.. toctree:: + :maxdepth: 2 + :caption: Content + + install + virtual/index + cloud/index + vyos-on-baremetal + update + image + migrate-from-vyatta
\ No newline at end of file diff --git a/docs/install.rst b/docs/installation/install.rst index 87be9561..8b567752 100644 --- a/docs/install.rst +++ b/docs/installation/install.rst @@ -494,7 +494,7 @@ Known Issues This is a list of known issues that can arise during installation. Black screen on install -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- GRUB attempts to redirect all output to a serial port for ease of installation on headless hosts. This appears to cause an hard lockup on some hardware that lacks a serial port, with the result being a diff --git a/docs/appendix/migrate-from-vyatta.rst b/docs/installation/migrate-from-vyatta.rst index eba9dc59..eba9dc59 100644 --- a/docs/appendix/migrate-from-vyatta.rst +++ b/docs/installation/migrate-from-vyatta.rst diff --git a/docs/installation/update.rst b/docs/installation/update.rst new file mode 100644 index 00000000..a3a887f0 --- /dev/null +++ b/docs/installation/update.rst @@ -0,0 +1,79 @@ +.. _update_vyos: + +Update VyOS +=========== + +New system images can be added using the :opcmd:`add system image` +command. The command will extract the chosen image and will prompt you +to use the current system configuration and SSH security keys, allowing +for the new image to boot using the current configuration. + +.. note:: Only LTS releases are PGP-signed. + +.. opcmd:: add system image <url | path> [vrf name] [username user [password pass]] + + Use this command to install a new system image. You can reach the + image from the web (http://, https://) or from your local system, + e.g. /tmp/vyos-1.2.3-amd64.iso. + + The `add system image` command also supports installing new versions + of VyOS through an optional given VRF. Also if URL in question requires + authentication, you can specify an optional username and password via + the commandline which will be passed as "Basic-Auth" to the server. + +If there is not enough **free disk space available**, the installation +will be canceled. To delete images use the :opcmd:`delete system image` +command. + +VyOS configuration is associated to each image, and **each image has a +unique copy of its configuration**. This is different than a traditional +network router where the configuration is shared across all images. + +.. note:: If you have any personal files, like some scripts you created, + and you don't want them to be lost during the upgrade, make sure + those files are stored in ``/config`` as this directory is always copied + to newer installed images. + +You can access files from a previous installation and copy them to your +current image if they were located in the ``/config`` directory. This +can be done using the :opcmd:`copy` command. So, for instance, in order +to copy ``/config/config.boot`` from VyOS 1.2.1 image, you would use the +following command: + +.. code:: + + copy file 1.2.1://config/config.boot to /tmp/config.boot.1.2.1 + + +Example +""""""" + +.. code-block:: none + + vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 100 338M 100 338M 0 0 3837k 0 0:01:30 0:01:30 --:--:-- 3929k + ISO download succeeded. + Checking for digital signature file... + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed + 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0 + curl: (22) The requested URL returned error: 404 Not Found + + Unable to fetch digital signature file. + Do you want to continue without signature check? (yes/no) [yes] + Checking MD5 checksums of files on the ISO image...OK. + Done! + + What would you like to name this image? [vyos-1.3-rolling-201912201452]: + + OK. This image will be named: vyos-1.3-rolling-201912201452 + + +.. hint:: | The most up-do-date Rolling Release for AMD64 can be accessed using the following URL: + | https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso + +After reboot you might want to verify the version you are running with +the :opcmd:`show version` command.
\ No newline at end of file diff --git a/docs/appendix/vyos-on-gns3.rst b/docs/installation/virtual/gns3.rst index f17715b2..f17715b2 100644 --- a/docs/appendix/vyos-on-gns3.rst +++ b/docs/installation/virtual/gns3.rst diff --git a/docs/installation/virtual/index.rst b/docs/installation/virtual/index.rst new file mode 100644 index 00000000..dab5bc59 --- /dev/null +++ b/docs/installation/virtual/index.rst @@ -0,0 +1,9 @@ +#################################### +Running VyOS in Virtual Environments +#################################### + +.. toctree:: + :caption: Content + + gns3 + vmware
\ No newline at end of file diff --git a/docs/appendix/vyos-on-vmware.rst b/docs/installation/virtual/vmware.rst index 6feb95ba..6feb95ba 100644 --- a/docs/appendix/vyos-on-vmware.rst +++ b/docs/installation/virtual/vmware.rst diff --git a/docs/appendix/vyos-on-baremetal.rst b/docs/installation/vyos-on-baremetal.rst index 14ba2adf..14ba2adf 100644 --- a/docs/appendix/vyos-on-baremetal.rst +++ b/docs/installation/vyos-on-baremetal.rst diff --git a/docs/interfaces/ethernet.rst b/docs/interfaces/ethernet.rst deleted file mode 100644 index c7744b6c..00000000 --- a/docs/interfaces/ethernet.rst +++ /dev/null @@ -1,72 +0,0 @@ - -Ethernet Interfaces -------------------- -.. _interfaces-ethernet: - -Ethernet interfaces allow for the configuration of speed, duplex, and hw-id -(MAC address). Below is an example configuration: - -.. code-block:: none - - set interfaces ethernet eth1 address '192.168.0.1/24' - set interfaces ethernet eth1 address '2001:db8:1::ffff/64' - set interfaces ethernet eth1 description 'INSIDE' - set interfaces ethernet eth1 duplex 'auto' - set interfaces ethernet eth1 speed 'auto' - -Resulting in: - -.. code-block:: none - - ethernet eth1 { - address 192.168.0.1/24 - address 2001:db8:1::ffff/64 - description INSIDE - duplex auto - hw-id 00:0c:29:44:3b:19 - smp_affinity auto - speed auto - } - -In addition, Ethernet interfaces provide the extended operational commands: - -* `show interfaces ethernet <name> physical` -* `show interfaces ethernet <name> statistics` - -Statistics available are driver dependent. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 physical - Settings for eth0: - Supported ports: [ TP ] - Supported link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Supports auto-negotiation: Yes - Advertised link modes: 10baseT/Half 10baseT/Full - 100baseT/Half 100baseT/Full - 1000baseT/Full - Advertised pause frame use: No - Advertised auto-negotiation: Yes - Speed: 1000Mb/s - Duplex: Full - Port: Twisted Pair - PHYAD: 0 - Transceiver: internal - Auto-negotiation: on - MDI-X: Unknown - Supports Wake-on: d - Wake-on: d - Current message level: 0x00000007 (7) - Link detected: yes - driver: e1000 - version: 7.3.21-k8-NAPI - firmware-version: - bus-info: 0000:02:01.0 - - vyos@vyos:~$ show interfaces ethernet eth0 statistics - NIC statistics: - rx_packets: 3530 - tx_packets: 2179 - [...] diff --git a/docs/interfaces/index.rst b/docs/interfaces/index.rst deleted file mode 100644 index aa8d264e..00000000 --- a/docs/interfaces/index.rst +++ /dev/null @@ -1,63 +0,0 @@ -.. _network-interfaces: - -Network Interfaces -================== - -Configured interfaces on a VyOS system can be displayed using the -`show interfaces` command. - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 172.16.51.129/24 u/u OUTSIDE - eth1 192.168.0.1/24 u/u INSIDE - lo 127.0.0.1/8 u/u - ::1/128 - vyos@vyos:~$ - -A specific interface can be shown using the `show interfaces <type> <name>` -command. - -.. code-block:: none - - vyos@vyos:~$ show interfaces ethernet eth0 - eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP qlen 1000 - link/ether 00:0c:29:44:3b:0f brd ff:ff:ff:ff:ff:ff - inet 172.16.51.129/24 brd 172.16.51.255 scope global eth0 - inet6 fe80::20c:29ff:fe44:3b0f/64 scope link - valid_lft forever preferred_lft forever - Description: OUTSIDE - - RX: bytes packets errors dropped overrun mcast - 274397 3064 0 0 0 0 - TX: bytes packets errors dropped carrier collisions - 257276 1890 0 0 0 0 - vyos@vyos:~$ - -Different network interfaces provide type-specific configuration. Ethernet -interfaces, for example, allow the configuration of speed and duplex. - -Many services, such as network routing, firewall, and traffic policy also -maintain interface-specific configuration. These will be covered in their -respective sections. - - -.. toctree:: - :maxdepth: 2 - :hidden: - - addresses - dummy - ethernet - l2tpv3 - pppoe - wireless - bridging - bonding - tunnel - vlan - qinq - vxlan diff --git a/docs/interfaces/pppoe.rst b/docs/interfaces/pppoe.rst deleted file mode 100644 index d8625722..00000000 --- a/docs/interfaces/pppoe.rst +++ /dev/null @@ -1,82 +0,0 @@ -.. _pppoe: - - -PPPoE -===== - -There are two main ways to setup VyOS to connect over a PPPoE internet connection. This is due to most ISPs (Internet Service Providers) providing a DSL modem that is also a wireless router. - -**First Method:** (Common for Homes) - -In this method, the DSL Modem/Router connects to the ISP for you with your credentials preprogrammed into the device. This gives you an RFC1918_ address, such as 192.168.1.0/24 by default. - -For a simple home network using just the ISP's equipment, this is usually desirable. But if you want to run VyOS as your firewall and router, this will result in having a double NAT and firewall setup. This results in a few extra layers of complexity, particularly if you use some NAT or tunnel features. - -**Second Method:** (Common for Businesses) - -In order to have full control and make use of multiple static public IP addresses, your VyOS will have to initiate the PPPoE connection and control it. -In order for this method to work, you will have to figure out how to make your DSL Modem/Router switch into a Bridged Mode so it only acts as a DSL Transceiver device to connect between the Ethernet link of your VyOS and the phone cable. -Once your DSL Transceiver is in Bridge Mode, you should get no IP address from it. -Please make sure you connect to the Ethernet Port 1 if your DSL Transeiver has a switch, as some of them only work this way. -Once you have an Ethernet device connected, i.e. eth0, then you can configure it to open the PPPoE session for you and your DSL Transceiver (Modem/Router) just acts to translate your messages in a way that vDSL/aDSL understands. - -**Here is an example configuration:** - -.. code-block:: none - - set interface ethernet eth0 description "DSL Modem" - set interface ethernet eth0 duplex auto - set interface ethernet eth0 smp_affinity auto - set interface ethernet eth0 speed auto - set interface ethernet eth0 pppoe 0 default-route auto - set interface ethernet eth0 pppoe 0 mtu 1492 - set interface ethernet eth0 pppoe 0 name-server auto - set interface ethernet eth0 pppoe 0 user-id <PPPoE Username> - set interface ethernet eth0 pppoe 0 password <PPPoE Password> - - -* You should add a firewall to your configuration above as well by assigning it to the pppoe0 itself as shown here: - -.. code-block:: none - - set interface ethernet eth0 pppoe 0 firewall in name NET-IN - set interface ethernet eth0 pppoe 0 firewall local name NET-LOCAL - set interface ethernet eth0 pppoe 0 firewall out name NET-OUT - -* You need your PPPoE credentials from your DSL ISP in order to configure this. The usual username is in the form of name@host.net but may vary depending on ISP. -* The largest MTU size you can use with DSL is 1492 due to PPPoE overhead. If you are switching from a DHCP based ISP like cable then be aware that things like VPN links may need to have their MTU sizes adjusted to work within this limit. -* With the ``default-route`` option set to ``auto``, VyOS will only add the Default Gateway you receive from your DSL ISP to the routing table if you have no other WAN connections. If you wish to use a Dual WAN connection, change the ``default-route`` option to ``force``. - -Handling and troubleshooting ----------------------------- - -You can test connecting and disconnecting with the below commands: - -.. code-block:: none - - disconnect interface 0 - connect interface 0 - - -You can check the PPPoE connection logs with the following: - -This command shows the current statistics, status and some of the settings (i.e. MTU) for the current connection on pppoe0. - -.. code-block:: none - - show interfaces pppoe 0 - -This command shows the entire log for the PPPoE connection starting with the oldest data. Scroll down with the <space> key to reach the end where the current data is. - -.. code-block:: none - - show interfaces pppoe 0 log - - -This command shows the same log as without the 'tail' option but only starts with the last few lines and continues to show added lines until you exit with ``Ctrl + x`` - -.. code-block:: none - - show interfaces pppoe 0 log tail - -.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/interfaces/qinq.rst b/docs/interfaces/qinq.rst deleted file mode 100644 index 2049f511..00000000 --- a/docs/interfaces/qinq.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _interfaces-qinq: - -QinQ ----- - -QinQ (802.1ad_) — allows multiple VLAN tags to be inserted into a single frame. - -QinQ can be used to tunnel vlans in a vlan. - -**vif-s** and **vif-c** stand for the ethertype tags that get set: - -The inner tag is the tag which is closest to the payload portion of the frame; it is officially called C-TAG (Customer tag, with ethertype 0x8100). -The outer tag is the one closer/closest to the Ethernet header; its name is S-TAG (Service tag, ethertype 0x88a8). - -Configuration commands: - -.. code-block:: none - - interfaces - ethernet <eth[0-999]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - vif-s <[0-4096]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - vif-c <[0-4096]> - address <ipv4> - address <ipv6> - description <txt> - disable - ip - <usual IP options> - ipv6 - <usual IPv6 options> - - -Example: - -.. code-block:: none - - set interfaces ethernet eth0 vif-s 333 - set interfaces ethernet eth0 vif-s 333 address 192.0.2.10/32 - set interfaces ethernet eth0 vif-s 333 vif-c 777 - set interfaces ethernet eth0 vif-s 333 vif-c 777 address 10.10.10.10/24 - -.. _802.1ad: https://en.wikipedia.org/wiki/IEEE_802.1ad
\ No newline at end of file diff --git a/docs/interfaces/vlan.rst b/docs/interfaces/vlan.rst deleted file mode 100644 index b2f67108..00000000 --- a/docs/interfaces/vlan.rst +++ /dev/null @@ -1,47 +0,0 @@ -VLAN Sub-Interfaces (802.1Q) ----------------------------- -.. _interfaces-vlan: - -802.1Q VLAN interfaces are represented as virtual sub-interfaces in VyOS. The -term used for this is `vif`. Configuration of a tagged sub-interface is -accomplished using the configuration command -`set interfaces ethernet <name> vif <vlan-id>`. - -.. code-block:: none - - set interfaces ethernet eth1 vif 100 description 'VLAN 100' - set interfaces ethernet eth1 vif 100 address '192.168.100.1/24' - set interfaces ethernet eth1 vif 100 address '2001:db8:100::1/64' - -Resulting in: - -.. code-block:: none - - ethernet eth1 { - address 192.168.100.1/24 - address 2001:db8:100::1/64 - description INSIDE - duplex auto - hw-id 00:0c:29:44:3b:19 - smp_affinity auto - speed auto - vif 100 { - address 192.168.100.1/24 - description "VLAN 100" - } - } - -VLAN interfaces are shown as `<name>.<vlan-id>`, e.g. `eth1.100`: - -.. code-block:: none - - vyos@vyos:~$ show interfaces - Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down - Interface IP Address S/L Description - --------- ---------- --- ----------- - eth0 172.16.51.129/24 u/u OUTSIDE - eth1 192.168.0.1/24 u/u INSIDE - eth1.100 192.168.100.1/24 u/u VLAN 100 - lo 127.0.0.1/8 u/u - ::1/128 - diff --git a/docs/about.rst b/docs/introducing/about.rst index 383c95eb..0411344b 100644 --- a/docs/about.rst +++ b/docs/introducing/about.rst @@ -8,7 +8,7 @@ VyOS is an open source network operating system based on Debian GNU/Linux. VyOS provides a free routing platform that competes directly with other commercially available solutions from well known network providers. Because -VyOS is run on standard amd64, i586 and ARM systems, it can be used +VyOS is run on standard amd64, i586 and ARM systems, it is able to be used as a router and firewall platform for cloud deployments. We use multiple live versions of our manual hosted thankfully by @@ -16,7 +16,7 @@ https://readthedocs.org. We will provide one version of the manual for every VyOS major version starting with VyOS 1.2 which will receive Long-term support (LTS). -The manual version is selected/specified by its Git branch name. You can +The manual version is selected/specified by it's Git branch name. You can switch between versions of the documentation by selecting the appropriate branch on the bottom left corner. diff --git a/docs/history.rst b/docs/introducing/history.rst index 957cc6f3..9a13e2b3 100644 --- a/docs/history.rst +++ b/docs/introducing/history.rst @@ -1,45 +1,47 @@ .. _history: -VyOS History -================== +####### +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 +`GPL <https://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 +VyOS is primarily based on `Debian GNU/Linux <https://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 for -Vyatta. +`XORP project <http://www.xorp.org/>`_, which was the original routing engine +for Vyatta. -In the 4.0 release of Vyatta, the routing engine was changed to Quagga. +In the 4.0 release of Vyatta, the routing engine was changed to Quagga. As of +VyOS version 1.2, VyOS now uses `FRRouting <https://frrouting.org/>`_ as the +routing engine. -As of version 1.2.0, VyOS now uses `FRRouting <https://frrouting.org/>`_ as -the routing engine. +How is VyOS different from any other router distributions and platform? -**How it's different from other router distributions and platforms?** - -- More than just a firewall and VPN, VyOS includes extended routing capabilities like OSPFv2, OSPFv3, BGP, - VRRP, and extensive route policy mapping and filtering. +- It's more than just a firewall and VPN, VyOS includes extended routing + capabilities like OSPFv2, OSPFv3, BGP, VRRP, and extensive route policy + mapping and filtering - Unified command line interface in the style of hardware routers. -- Scriptable CLI. +- 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 and execute hooks at commit time. + server and execute hooks at commit time - Image-based upgrade: keep multiple versions on the same system and revert to - previous image if a problem arises. -- Multiple VPN capabilities: OpenVPN, IPSec, Wireguard (in 1.2.0+), DPMVPN, and more. -- IPv4 and IPv6 support. + previous image if a problem arises +- Multiple VPN capabilities: OpenVPN, IPSec, Wireguard, DPMVPN, IKEv2 and more +- DHCP, TFTP, mDNS repeater, broadcast relay and DNS forwarding support +- Both IPv4 and IPv6 support - Runs on physical and virtual platforms alike: small x86 boards, big servers, - KVM, Xen, VMWare, Hyper-V, and more. + KVM, Xen, VMware, Hyper-V, and more - Completely free and open source, with documented internal APIs and build - procedures. -- Community driven. Patches are welcome and all code, bugs, and nightly builds are - public. + procedures +- Community driven. Patches are welcome and all code, bugs, and nightly builds + are publicly accessible diff --git a/docs/system/boot-options.rst b/docs/operation/boot-options.rst index 1070afa9..1070afa9 100644 --- a/docs/system/boot-options.rst +++ b/docs/operation/boot-options.rst diff --git a/docs/operation/index.rst b/docs/operation/index.rst new file mode 100644 index 00000000..321ae169 --- /dev/null +++ b/docs/operation/index.rst @@ -0,0 +1,9 @@ +############## +Operation Mode +############## + +.. toctree:: + :maxdepth: 1 + :includehidden: + + boot-options
\ No newline at end of file diff --git a/docs/routing/mss-clamp.rst b/docs/routing/mss-clamp.rst deleted file mode 100644 index a4edf1c6..00000000 --- a/docs/routing/mss-clamp.rst +++ /dev/null @@ -1,64 +0,0 @@ -.. _routing-mss-clamp: - -TCP-MSS Clamping ----------------- - -As Internet wide PMTU discovery rarely works, we sometimes need to clamp -our TCP MSS value to a specific value. This is a field in the TCP -Options part of a SYN packet. By setting the MSS value, you are telling -the remote side unequivocally 'do not try to send me packets bigger than -this value'. - -Starting with VyOS 1.2 there is a firewall option to clamp your TCP MSS -value for IPv4 and IPv6. - - -.. note:: MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting - in 1452 bytes on a 1492 byte MTU. - - -IPv4 -^^^^ - -.. cfgcmd:: set firewall options interface <interface> adjust-mss <number-of-bytes> - - Use this command to set the maximum segment size for IPv4 transit - packets on a specific interface (500-1460 bytes). - - -Example -""""""" - -Clamp outgoing MSS value in a TCP SYN packet to `1452` for `pppoe0` and -`1372` -for your WireGuard `wg02` tunnel. - -.. code-block:: none - - set firewall options interface pppoe0 adjust-mss '1452' - set firewall options interface wg02 adjust-mss '1372' - -IPv6 -^^^^^ - -.. cfgcmd:: set firewall options interface <interface> adjust-mss6 <number-of-bytes> - - Use this command to set the maximum segment size for IPv6 transit - packets on a specific interface (1280-1492 bytes). - - -Example -""""""" - -Clamp outgoing MSS value in a TCP SYN packet to `1280` for both `pppoe0` and -`wg02` interface. - -.. code-block:: none - - set firewall options interface pppoe0 adjust-mss6 '1280' - set firewall options interface wg02 adjust-mss6 '1280' - - - -.. hint:: When doing your byte calculations, you might find useful this - `Visual packet size calculator <https://baturin.org/tools/encapcalc/>`_. diff --git a/docs/routing/routing-policy.rst b/docs/routing/routing-policy.rst deleted file mode 100644 index 847f3574..00000000 --- a/docs/routing/routing-policy.rst +++ /dev/null @@ -1,59 +0,0 @@ - -Routing-policy --------------- - -Routing Policies could be used to tell the router (self or neighbors) what routes and their attributes needs to be put into the routing table. - -There could be a wide range of routing policies. Some examples are below: - - * Set some metric to routes learned from a particular neighbor - * Set some attributes (like AS PATH or Community value) to advertised routes to neighbors - * Prefer a specific routing protocol routes over another routing protocol running on the same router - -Routing Policy Example -~~~~~~~~~~~~~~~~~~~~~~ - -**Policy definition:** - -.. code-block:: none - - #Create policy - set policy route-map setmet rule 2 action 'permit' - 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 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 - -**Routes learned before routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ show ip bgp - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 22.22.22.22/32 1.1.1.2 1 0 2 i < Path - - Total number of prefixes 1 - -**Routes learned after routing policy applied:** - -.. code-block:: none - - vyos@vos1:~$ sho ip b - BGP table version is 0, local router ID is 192.168.56.101 - Status codes: s suppressed, d damped, h history, * valid, > best, i - internal, - r RIB-failure, S Stale, R Removed - Origin codes: i - IGP, e - EGP, ? - incomplete - - Network Next Hop Metric LocPrf Weight Path - *> 22.22.22.22/32 1.1.1.2 1 0 2 2 2 2 i < longer AS_path length - - Total number of prefixes 1 - vyos@vos1:~$ diff --git a/docs/routing/static.rst b/docs/routing/static.rst deleted file mode 100644 index 01e88988..00000000 --- a/docs/routing/static.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _routing-static: - -Static ------- - -Static routes are manually configured network routes. - -A typical use for a static route is a static default route for systems that do -not make use of DHCP or dynamic routing protocols: - -.. code-block:: none - - set protocols static route 0.0.0.0/0 next-hop 10.1.1.1 distance '1' - -Another common use of static routes is to blackhole (drop) traffic. In the -example below, RFC1918_ networks are set as blackhole routes. - -This prevents these networks leaking out public interfaces, but it does not prevent -them from being used as the most specific route has the highest priority. - -.. code-block:: none - - set protocols static route 10.0.0.0/8 blackhole distance '254' - set protocols static route 172.16.0.0/12 blackhole distance '254' - set protocols static route 192.168.0.0/16 blackhole distance '254' - -.. note:: Routes with a distance of 255 are effectively disabled and not - installed into the kernel. - -.. _RFC1918: https://tools.ietf.org/html/rfc1918 diff --git a/docs/services/dhcp.rst b/docs/services/dhcp.rst deleted file mode 100644 index f11d9a7e..00000000 --- a/docs/services/dhcp.rst +++ /dev/null @@ -1,138 +0,0 @@ - -DHCP Server ------------ - -Multiple DHCP Servers can be run from a single machine. Each DHCP service is -identified by a `shared-network-name`. - -DHCP Server Example -^^^^^^^^^^^^^^^^^^^ - -In this example, we are offering address space in the 172.16.17.0/24 network, -which is on eth1, and pppoe0 is our connection to the internet. We are using -the network name `dhcpexample`. - -Prerequisites -^^^^^^^^^^^^^ - -Configuring the PPPoE interface is assumed to be done already, and appears -on `pppoe0` - -Interface Configuration -^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set interface ethernet eth1 address 172.16.17.1/24 - -Multiple ranges can be defined and can contain holes. - -.. code-block:: none - - set service dhcp-server shared-network-name dhcpexample authoritative - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router 172.16.17.1 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server 172.16.17.1 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 lease 86400 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 start 172.16.17.100 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 range 0 stop 172.16.17.199 - - -Explanation -^^^^^^^^^^^ - -* :code:`set service dhcp-server shared-network-name dhcpexample authoritative` - - This says that this device is the only DHCP server for this network. If other - devices are trying to offer DHCP leases, this machine will send 'DHCPNAK' to - any device trying to request an IP address that is - not valid for this network. - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 default-router 172.16.17.1` - - This is a configuration parameter for the subnet, saying that as part of the - response, tell the client that I am the default router for this network - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 dns-server 172.16.17.1` - - This is a configuration parameter for the subnet, saying that as part of the - response, tell the client that I am the DNS server for this network. If you - do not want to run a DNS server, you could also provide one of the public - DNS servers, such as google's. You can add multiple entries by repeating the - line. - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 lease 86400` - - Assign the IP address to this machine for 24 hours. It is unlikely you'd need - to shorten this period, unless you are running a network with lots of devices - appearing and disappearing. - - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 range 0 start 172.16.17.100` - - Make a range of addresses available for clients starting from .100 [...] - -* :code:`set service dhcp-server shared-network-name dhcpexample subnet - 172.16.17.0/24 range 0 stop 172.16.17.199` - - [...] and ending at .199 - - -Failover -^^^^^^^^ - -VyOS provides support for DHCP failover: - -.. code-block:: none - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover local-address '192.168.0.1' - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover name 'foo' - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover peer-address '192.168.0.2' - -.. note:: `name` must be identical on both sides! - -The primary and secondary statements determines whether the server is -primary or secondary - -.. code-block:: none - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'primary' - -or - -.. code-block:: none - - set service dhcp-server shared-network-name 'LAN' subnet '192.168.0.0/24' failover status 'secondary' - -.. note:: In order for the primary and the secondary DHCP server to keep - their lease tables in sync, they must be able to reach each other on TCP - port 647. If you have firewall rules in effect, adjust them accordingly. - -Static mappings MAC/IP -^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: none - - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 ip-address 172.16.17.10 - set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 static-mapping static-mapping-01 mac-address ff:ff:ff:ff:ff:ff - -DHCP server options -^^^^^^^^^^^^^^^^^^^^^^^^^ - -default-router (DHCP option 003) - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 default-router <ROUTER-IP>` - -dns-server (DHCP option 006) - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 dns-server <DNS-SERVER-IP>` - -domain-name Client domain name (DHCP option 015) - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-name "<DOMAIN-NAME>"` - -domain-search (DHCP option 119) - This option can be given multiple times if you need multiple search domains - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_1>"` - :code:`set service dhcp-server shared-network-name dhcpexample subnet 172.16.17.0/24 domain-search "<DOMAIN_NAME_2>"` - diff --git a/docs/services/dns-forwarding.rst b/docs/services/dns-forwarding.rst deleted file mode 100644 index 84e4fc93..00000000 --- a/docs/services/dns-forwarding.rst +++ /dev/null @@ -1,72 +0,0 @@ -DNS Forwarding --------------- - -Use DNS forwarding if you want your router to function as a DNS server for the -local network. There are several options, the easiest being 'forward all -traffic to the system DNS server(s)' (defined with set system name-server): - -.. code-block:: none - - set service dns forwarding system - -Manually setting DNS servers for forwarding: - -.. code-block:: none - - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - -Manually setting DNS servers with IPv6 connectivity: - -.. code-block:: none - - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - -Setting a forwarding DNS server for a specific domain: - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.1 - -Set which networks or clients are allowed to query the DNS Server. Allow from all: - -.. code-block:: none - - set service dns forwarding allow-from 0.0.0.0/0 - -Example 1 -^^^^^^^^^ - -Router with two interfaces eth0 (WAN link) and eth1 (LAN). Split DNS for example.com. - -* DNS request for a local domain (example.com) get forwarded to 192.0.2.1 -* Other DNS requests are forwarded to Google's DNS servers. -* The IP address for the LAN interface is 192.168.0.1. - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 - -Example 2 -^^^^^^^^^ - -Same as example 1 but with additional IPv6 addresses for Google's public DNS -servers. - -The IP addresses for the LAN interface are 192.168.0.1 and 2001:db8::1 - -.. code-block:: none - - set service dns forwarding domain example.com server 192.0.2.1 - set service dns forwarding name-server 8.8.8.8 - set service dns forwarding name-server 8.8.4.4 - set service dns forwarding name-server 2001:4860:4860::8888 - set service dns forwarding name-server 2001:4860:4860::8844 - set service dns forwarding listen-address 2001:db8::1 - set service dns forwarding listen-address 192.168.0.1 - set service dns forwarding allow-from 0.0.0.0/0 diff --git a/docs/services/index.rst b/docs/services/index.rst deleted file mode 100644 index dbfcfce2..00000000 --- a/docs/services/index.rst +++ /dev/null @@ -1,27 +0,0 @@ -.. _services: - -.. include:: references.rst - -Services -======== - -This chapter describes the available system/network services provided by VyOS. - -.. toctree:: - :maxdepth: 1 - - conntrack - dhcp - dhcpv6 - dhcp-relay - dns-forwarding - dynamic-dns - lldp - mdns-repeater - ipoe-server - pppoe-server - udp-broadcast-relay - snmp - ssh - tftp - webproxy diff --git a/docs/services/ipoe-server.rst b/docs/services/ipoe-server.rst deleted file mode 100644 index eed4cced..00000000 --- a/docs/services/ipoe-server.rst +++ /dev/null @@ -1,129 +0,0 @@ -IPoE server ------------- - -VyOS utilizes `accel-ppp`_ to provide IPoE server functionality. It can be -used with local authentication (mac-address) or a connected RADIUS server. - -.. note:: **Please be aware, due to an upstream bug, config changes/commits - will restart the ppp daemon and will reset existing IPoE sessions, - in order to become effective.** - -Configuration -^^^^^^^^^^^^^ - -IPoE can be configure on different interfaces, it will depend on each specific situation which interface will provide IPoE to clients. -The clients mac address and the incoming interface is being used as control parameter, to authenticate a client. - -The example configuration below will assign an IP to the client on the incoming interface eth2 with the client mac address 08:00:27:2f:d8:06. -Other DHCP discovery requests will be ignored, unless the client mac has been enabled in the configuration. - -.. code-block:: none - - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' - set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' - - -The first address of the parameter ``client-subnet``, will be used as the default gateway. -Connected sessions can be checked via the ``show ipoe-server sessions`` command. - -.. code-block:: none - - vyos@vyos:~$ show ipoe-server sessions - - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ - ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | | active | 00:45:05 | dccc870fd3134612 - - -IPv6 SLAAC and IA-PD -==================== - -To configure IPv6 assignments for clients, two options need to be configured. A global prefix which is terminated on the clients cpe and a delegated prefix, the client can use -for devices routed via the clients cpe. - -IPv6 DNS addresses are optional. - -.. code-block:: none - - set service ipoe-server authentication interface eth3 mac-address 08:00:27:2F:D8:06 - set service ipoe-server authentication mode 'local' - set service ipoe-server client-ipv6-pool delegate-prefix '2001:db8:1::/48,56' - set service ipoe-server client-ipv6-pool prefix '2001:db8::/48,64' - set service ipoe-server dnsv6-server server-1 '2001:db8::' - set service ipoe-server dnsv6-server server-2 '2001:db8:aaa::' - set service ipoe-server dnsv6-server server-3 '2001:db8:bbb::' - set service ipoe-server interface eth3 client-subnet '192.168.1.0/24' - -.. code-block:: none - - vyos@ipoe-server# run sh ipoe-server sessions - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+---------------------------------+-----------------+------------+--------+----------+------------------ - ipoe0 | eth3 | 08:00:27:2f:d8:06 | 192.168.1.2 | 2001:db8::a00:27ff:fe2f:d806/64 | 2001:db8:1::/56 | | active | 01:02:59 | 4626faf71b12cc25 - - -The clients cpe can now communicate via IPv4 or IPv6. All devices behind ``2001:db8::a00:27ff:fe2f:d806/64`` can use addresses from ``2001:db8:1::/56`` and can -globally communicate without the need of any NAT rules. - - -Automatic VLAN creation -======================= - -To create VLANs per user during runtime, the following settings are required on a per interface basis. VLAN ID and VLAN range can be present in the configuration at the same time. - -.. code-block:: none - - set service ipoe-server interface eth2 network vlan - set service ipoe-server interface eth2 vlan-id 100 - set service ipoe-server interface eth2 vlan-id 200 - set service ipoe-server interface eth2 vlan-range 1000-2000 - set service ipoe-server interface eth2 vlan-range 2500-2700 - - -RADIUS Setup -^^^^^^^^^^^^ - -To use a RADIUS server for authentication and bandwidth-shaping, the following example configuration can be used. - -.. code-block:: none - - set service ipoe-server authentication mode 'radius' - set service ipoe-server authentication radius-server 10.100.100.1 secret 'password' - - -Bandwidth Shaping -^^^^^^^^^^^^^^^^^ - -Bandwidth rate limits can be set for local users within the configuration or via RADIUS based attributes. - - -Bandwidth Shaping for local users -================================= - -The rate-limit is set in kbit/sec. - -.. code-block:: none - - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit download '500' - set service ipoe-server authentication interface eth2 mac-address 08:00:27:2f:d8:06 rate-limit upload '500' - set service ipoe-server authentication mode 'local' - set service ipoe-server dns-server server-1 '8.8.8.8' - set service ipoe-server dns-server server-2 '8.8.4.4' - set service ipoe-server interface eth2 client-subnet '192.168.0.0/24' - - -.. code-block:: none - - vyos@vyos# run show ipoe-server sessions - - ifname | called-sid | calling-sid | ip | ip6 | ip6-dp | rate-limit | state | uptime | sid - -------+------------+-------------------+-------------+-----+--------+------------+--------+----------+------------------ - ipoe0 | eth2 | 08:00:27:2f:d8:06 | 192.168.0.2 | | | 500/500 | active | 00:00:05 | dccc870fd31349fb - - - - -.. _`accel-ppp`: https://accel-ppp.org/ diff --git a/docs/system/proxy.rst b/docs/system/proxy.rst deleted file mode 100644 index f89794dd..00000000 --- a/docs/system/proxy.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _proxy: - -System Proxy -============ - -Some IT environments require the use of a proxy to connect to the Internet. -The option allowes to set a HTTP proxy and if necessary, supports `basic auth`_. - -The code example below sets a proxy for all HTTP, HTTPS and FTP (anonymous ftp) connections, initiated by vyos. - -.. code-block:: none - - set system proxy url http://10.100.100.1 - set system proxy port 8080 - -That enables the update of a system image if the vyos system operates behind a proxy. - -.. code-block:: none - - vyos@vyos:~$ add system image https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - Trying to fetch ISO file from https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso - % Total % Received % Xferd Average Speed Time Time Time Current - Dload Upload Total Spent Left Speed - 1 413M 1 4479k 0 0 995k 0 0:07:04 0:00:04 0:07:00 995k - - - -.. _`basic auth`: https://tools.ietf.org/html/rfc7617 diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst new file mode 100644 index 00000000..a965dbe6 --- /dev/null +++ b/docs/troubleshooting/index.rst @@ -0,0 +1,459 @@ +.. _troubleshooting: + +############### +Troubleshooting +############### + +Sometimes things break or don't work as expected. This section describes +several troubleshooting tools provided by VyOS that can help when something +goes wrong. + +****************** +Connectivity Tests +****************** + +Basic Connectivity Tests +======================== + +Verifying connectivity can be done with the familiar `ping` and `traceroute` +commands. The options for each are shown (the options for each command were +displayed using the built-in help as described in the :ref:`cli` +section and are omitted from the output here): + +.. opcmd:: ping <destination> + + Send ICMP echo requests to destination host. There are multiple options to + ping, inkl. VRF support. + + .. code-block:: none + + vyos@vyos:~$ ping 10.1.1.1 + Possible completions: + <Enter> Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf + + +.. opcmd:: traceroute <destination> + + Trace path to target. + + .. code-block:: none + + vyos@vyos:~$ traceroute + Possible completions: + <hostname> Track network path to specified node + <x.x.x.x> + <h:h:h:h:h:h:h:h> + ipv4 Track network path to <hostname|IPv4 address> + ipv6 Track network path to <hostname|IPv6 address> + + +Advanced Connectivity Tests +=========================== + +.. opcmd:: monitor traceroute <destination> + + However, another helper is available which combines ping and traceroute + into a single tool. An example of its output is shown: + + .. code-block:: none + + vyos@vyos:~$ mtr 10.62.212.12 + + My traceroute [v0.85] + vyos (0.0.0.0) + Keys: Help Display mode Restart statistics Order of fields quit + Packets Pings + Host Loss% Snt Last Avg Best Wrst StDev + 1. 10.11.110.4 0.0% 34 0.5 0.5 0.4 0.8 0.1 + 2. 10.62.255.184 0.0% 34 1.1 1.0 0.9 1.4 0.1 + 3. 10.62.255.71 0.0% 34 1.4 1.4 1.3 2.0 0.1 + 4. 10.62.212.12 0.0% 34 1.6 1.6 1.6 1.7 0.0 + + .. note:: The output consumes the screen and will replace your command + prompt. + + Several options are available for changing the display output. Press `h` to + invoke the built in help system. To quit, just press `q` and you'll be + returned to the VyOS command prompt. + +IPv6 Topology Discovery +======================= + +IPv6 uses different techniques to discover its Neighbors/topology. + +Router Discovery +---------------- + +.. opcmd:: force ipv6-rd interface <interface> [address <ipv6-address>] + + Discover routers via eth0. + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-rd interface eth0 + Soliciting ff02::2 (ff02::2) on eth0... + + Hop limit : 60 ( 0x3c) + Stateful address conf. : No + Stateful other conf. : No + Mobile home agent : No + Router preference : high + Neighbor discovery proxy : No + Router lifetime : 1800 (0x00000708) seconds + Reachable time : unspecified (0x00000000) + Retransmit time : unspecified (0x00000000) + Prefix : 240e:fe:8ca7:ea01::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Prefix : fc00:470:f1cd:101::/64 + On-link : Yes + Autonomous address conf.: Yes + Valid time : 2592000 (0x00278d00) seconds + Pref. time : 14400 (0x00003840) seconds + Recursive DNS server : fc00:470:f1cd::ff00 + DNS server lifetime : 600 (0x00000258) seconds + Source link-layer address: 00:98:2B:F8:3F:11 + from fe80::298:2bff:fef8:3f11 + +Neighbor Discovery +------------------ + +.. opcmd:: force ipv6-nd interface <interface> address <ipv6-address> + + + Example: + + .. code-block:: none + + vyos@vyos:~$ force ipv6-nd interface eth0 address fc00:470:f1cd:101::1 + + Soliciting fc00:470:f1cd:101::1 (fc00:470:f1cd:101::1) on eth0... + Target link-layer address: 00:98:2B:F8:3F:11 from fc00:470:f1cd:101::1 + + +*************** +Interface names +*************** + +If you find the names of your interfaces have changed, this could be because +your MAC addresses have changed. + +* For example, you have a VyOS VM with 4 Ethernet interfaces named + eth0, eth1, eth2 and eth3. Then, you migrate your VyOS VM to a different + host and find your interfaces now are eth4, eth5, eth6 and eth7. + + One way to fix this issue **taking control of the MAC addresses** is: + + Log into VyOS and run this command to display your interface settings. + + .. code-block:: none + + show interfaces detail + + Take note of MAC addresses. + + Now, in order to update a MAC address in the configuration, run this command + specifying the interface name and MAC address you want. + + .. code-block:: none + + set interfaces eth0 hw-id 00:0c:29:da:a4:fe + + If it is a VM, go into the settings of the host and set the MAC address to + the settings found in the config.boot file. You can also set the MAC to + static if the host allows so. + + +* Another example could be when cloning VyOS VMs in GNS3 and you get into the + same issue: interface names have changed. + + And **a more generic way to fix it** is just deleting every MAC address at + the configuration file of the cloned machine. They will be correctly + regenerated automatically. + + +********** +Monitoring +********** + +VyOS features several monitoring tools. + +.. code-block:: none + + vyos@vyos:~$ monitor + Possible completions: + bandwidth Monitor interface bandwidth in real time + bandwidth-test + Initiate or wait for bandwidth test + cluster Monitor clustering service + command Monitor an operational mode command (refreshes every 2 seconds) + conntrack-sync + Monitor conntrack-sync + content-inspection + Monitor Content-Inspection + dhcp Monitor Dynamic Host Control Protocol (DHCP) + dns Monitor a Domain Name Service (DNS) daemon + firewall Monitor Firewall + https Monitor the Secure Hypertext Transfer Protocol (HTTPS) service + lldp Monitor Link Layer Discovery Protocol (LLDP) daemon + log Monitor last lines of messages file + nat Monitor network address translation (NAT) + ndp Monitor the NDP information received by the router through the device + openvpn Monitor OpenVPN + protocol Monitor routing protocols + snmp Monitor Simple Network Management Protocol (SNMP) daemon + stop-all Stop all current background monitoring processes + traceroute Monitor the path to a destination in realtime + traffic Monitor traffic dumps + vpn Monitor VPN + vrrp Monitor Virtual Router Redundancy Protocol (VRRP) + webproxy Monitor Webproxy service + + +Traffic Dumps +============= + +To monitor interface traffic, issue the :code:`monitor traffic interface <name>` +command, replacing `<name>` with your chosen interface. + +.. code-block:: none + + vyos@vyos:~$ monitor traffic interface eth0 + tcpdump: verbose output suppressed, use -v or -vv for full protocol decode + listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes + 15:54:28.581601 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3848, length 64 + 15:54:28.581660 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3848, length 64 + 15:54:29.583399 IP 192.168.0.1 > vyos: ICMP echo request, id 1870, seq 3849, length 64 + 15:54:29.583454 IP vyos > 192.168.0.1: ICMP echo reply, id 1870, seq 3849, length 64 + ^C + 4 packets captured + 4 packets received by filter + 0 packets dropped by kernel + vyos@vyos:~$ + +To quit monitoring, press `Ctrl-c` and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +.. code-block:: none + + vyos@vyos:~$ monitor traffic interface eth0 + Possible completions: + <Enter> Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file + + +Interface Bandwidth Usage +========================= + +to take a quick view on the used bandwidth of an interface use the ``monitor +bandwidth`` command + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth interface eth0 + +show the following: + +.. code-block:: none + + B (RX Bytes/second) + 198.00 .|....|..................................................... + 165.00 .|....|..................................................... + 132.00 ||..|.|..................................................... + 99.00 ||..|.|..................................................... + 66.00 |||||||..................................................... + 33.00 |||||||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + + KiB (TX Bytes/second) + 3.67 ......|..................................................... + 3.06 ......|..................................................... + 2.45 ......|..................................................... + 1.84 ......|..................................................... + 1.22 ......|..................................................... + 0.61 :::::||..................................................... + 1 5 10 15 20 25 30 35 40 45 50 55 60 + +Interface Performance +===================== + +To take a look on the network bandwidth between two nodes, the ``monitor +bandwidth-test`` command is used to run iperf. + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth-test + Possible completions: + accept Wait for bandwidth test connections (port TCP/5001) + initiate Initiate a bandwidth test + +* The ``accept`` command opens a listening iperf server on TCP Port 5001 +* The ``initiate`` command connects to that server to perform the test. + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth-test initiate + Possible completions: + <hostname> Initiate a bandwidth test to specified host (port TCP/5001) + <x.x.x.x> + <h:h:h:h:h:h:h:h> + + +Monitor command +=============== + +The ``monitor command`` command allows you to repeatedly run a command to view +a continuously refreshed output. The command is run and output every 2 seconds, +allowing you to monitor the output continuously without having to re-run the +command. This can be useful to follow routing adjacency formation. + +.. code-block:: none + + vyos@router:~$ monitor command "show interfaces" + +Will clear the screen and show you the output of ``show interfaces`` every +2 seconds. + +.. code-block:: none + + Every 2.0s: /opt/vyatta/bin/vyatta-op-cmd-wrapper Sun Mar 26 02:49:46 2019 + + Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down + Interface IP Address S/L Description + --------- ---------- --- ----------- + eth0 192.168.1.1/24 u/u + eth0.5 198.51.100.4/24 u/u WAN + lo 127.0.0.1/8 u/u + ::1/128 + vti0 172.25.254.2/30 u/u + vti1 172.25.254.9/30 u/u + +**************** +Terminal/Console +**************** + +Sometimes you need to clear counters or statistics to troubleshoot better. + +To do this use the ``clear`` command in Operational mode. + +to clear the console output + +.. code-block:: none + + vyos@vyos:~$ clear console + +to clear interface counters + +.. code-block:: none + + # clear all interfaces + vyos@vyos:~$ clear interface ethernet counters + # clear specific interface + vyos@vyos:~$ clear interface ehternet eth0 counters + +The command follow the same logic as the ``set`` command in configuration mode. + +.. code-block:: none + + # clear all counters of a interface type + vyos@vyos:~$ clear interface <interface_type> counters + # clear counter of a interface in interface_type + vyos@vyos:~$ clear interface <interface_type> <interace_name> counters + + +to clear counters on firewall rulesets or single rules + +.. code-block:: none + + vyos@vyos:~$ clear firewall name <ipv4 ruleset name> counters + vyos@vyos:~$ clear firewall name <ipv4 ruleset name> rule <rule#> counters + + vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> counters + vyos@vyos:~$ clear firewall ipv6-name <ipv6 ruleset name> rule <rule#> counters + + +****************** +System Information +****************** + +.. _boot-steps: + +Boot Steps +========== + +VyOS 1.2 uses `Debian Jessie`_ as the base Linux operating system. Jessie was +the first version of Debian that uses systemd_ as the default init system. + +These are the boot steps for VyOS 1.2 + +1. The BIOS loads Grub (or isolinux for the Live CD) +2. Grub then starts the Linux boot and loads the Linux Kernel ``/boot/vmlinuz`` +3. Kernel Launches Systemd ``/lib/systemd/systemd`` +4. Systemd loads the VyOS service file + ``/lib/systemd/system/vyos-router.service`` +5. The service file launches the VyOS router init script + ``/usr/libexec/vyos/init/vyos-router`` - this is part of the vyatta-cfg_ + Debian package + + 1. Starts FRR_ - successor to `GNU Zebra`_ and Quagga_ + + 2. Initialises the boot configuration file - copies over + ``config.boot.default`` if there is no configuration + 3. Runs the configuration migration, if the configuration is for an older + version of VyOS + 4. Runs The pre-config script, if there is one + ``/config/scripts/vyos-preconfig-bootup.script`` + 5. If the config file was upgraded, runs any post upgrade scripts + ``/config/scripts/post-upgrade.d`` + 6. Starts ``rl-system`` and ``firewall`` + 7. Mounts the ``/boot`` partition + 8. The boot configuration file is then applied by ``/opt/vyatta/sbin/ + vyatta-boot-config-loader/opt/vyatta/etc/config/config.boot`` + + 1. The config loader script writes log entries to + ``/var/log/vyatta-config-loader.log`` + + 10. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` + 11. Finally it runs the post-config script + ``/config/scripts/vyos-postconfig-bootup.script`` + +.. stop_vyoslinter + +.. _Quagga: https://www.quagga.net/ +.. _`GNU Zebra`: https://www.gnu.org/software/zebra/ +.. _FRR: https://frrouting.org/ +.. _vyatta-cfg: https://github.com/vyos/vyatta-cfg +.. _systemd: https://freedesktop.org/wiki/Software/systemd/ +.. _`Debian Jessie`: https://www.debian.org/releases/jessie/ +.. _tshark: https://www.wireshark.org/docs/man-pages/tshark.html +.. _`PCAP filter expressions`: http://www.tcpdump.org/manpages/pcap-filter.7.html + +.. start_vyoslinter diff --git a/vale.ini b/vale.ini new file mode 100644 index 00000000..b7dde1d8 --- /dev/null +++ b/vale.ini @@ -0,0 +1,16 @@ +StylesPath = .github/styles +MinAlertLevel = suggestion + +SkippedScopes = script, style, pre, figure, img, a, code + + +[*.rst] +BasedOnStyles = VyOS, Google + +Google.DateFormat = YES +vale.GenderBias = NO +vale.Hedging = NO +vale.Redundancy = NO +vale.Repetition = YES +vale.Uncomparables = NO +proselint.GenderBias = NO
\ No newline at end of file |