From 5d6fa52b8985f8068314aba26878a1d7d5cb84e5 Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 20:42:32 +0300 Subject: feat: flip swap mechanism — MD as primary, RST as override (Phase 1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This is the first of three phases inverting the per-page swap mechanism so MD becomes the canonical primary and RST becomes the rare override. Phase 1 — file renames + conf.py exclude_patterns flip only: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 254 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 254 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty comment-only since no pages need the RST fallback right now - conf.py exclude_patterns flipped: rst-*.rst is now excluded by default instead of md-*.md - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt (Phase 2 will rewrite swap_sources.py to produce these names; for now no swap script runs because overrides list is empty) Phase 2 (next commit on this branch) will rewrite scripts/swap_sources.py with inverted rename direction, delete scripts/import_myst.py + tests, and update tests/test_swap_sources.py for the new semantics. Phase 3 will be the cleanup pass and ready-for-review flip. Generated by robots https://vyos.io --- docs/troubleshooting/connectivity.md | 147 +++++++++++++++++++++++++++ docs/troubleshooting/connectivity.rst | 150 ---------------------------- docs/troubleshooting/index.md | 17 ++++ docs/troubleshooting/index.rst | 18 ---- docs/troubleshooting/interfaces.md | 36 +++++++ docs/troubleshooting/interfaces.rst | 39 -------- docs/troubleshooting/md-connectivity.md | 147 --------------------------- docs/troubleshooting/md-index.md | 17 ---- docs/troubleshooting/md-interfaces.md | 36 ------- docs/troubleshooting/md-monitoring.md | 152 ---------------------------- docs/troubleshooting/md-system.md | 48 --------- docs/troubleshooting/md-terminal.md | 39 -------- docs/troubleshooting/monitoring.md | 152 ++++++++++++++++++++++++++++ docs/troubleshooting/monitoring.rst | 161 ------------------------------ docs/troubleshooting/rst-connectivity.rst | 150 ++++++++++++++++++++++++++++ docs/troubleshooting/rst-index.rst | 18 ++++ docs/troubleshooting/rst-interfaces.rst | 39 ++++++++ docs/troubleshooting/rst-monitoring.rst | 161 ++++++++++++++++++++++++++++++ docs/troubleshooting/rst-system.rst | 57 +++++++++++ docs/troubleshooting/rst-terminal.rst | 42 ++++++++ docs/troubleshooting/system.md | 48 +++++++++ docs/troubleshooting/system.rst | 57 ----------- docs/troubleshooting/terminal.md | 39 ++++++++ docs/troubleshooting/terminal.rst | 42 -------- 24 files changed, 906 insertions(+), 906 deletions(-) create mode 100644 docs/troubleshooting/connectivity.md delete mode 100644 docs/troubleshooting/connectivity.rst create mode 100644 docs/troubleshooting/index.md delete mode 100644 docs/troubleshooting/index.rst create mode 100644 docs/troubleshooting/interfaces.md delete mode 100644 docs/troubleshooting/interfaces.rst delete mode 100644 docs/troubleshooting/md-connectivity.md delete mode 100644 docs/troubleshooting/md-index.md delete mode 100644 docs/troubleshooting/md-interfaces.md delete mode 100644 docs/troubleshooting/md-monitoring.md delete mode 100644 docs/troubleshooting/md-system.md delete mode 100644 docs/troubleshooting/md-terminal.md create mode 100644 docs/troubleshooting/monitoring.md delete mode 100644 docs/troubleshooting/monitoring.rst create mode 100644 docs/troubleshooting/rst-connectivity.rst create mode 100644 docs/troubleshooting/rst-index.rst create mode 100644 docs/troubleshooting/rst-interfaces.rst create mode 100644 docs/troubleshooting/rst-monitoring.rst create mode 100644 docs/troubleshooting/rst-system.rst create mode 100644 docs/troubleshooting/rst-terminal.rst create mode 100644 docs/troubleshooting/system.md delete mode 100644 docs/troubleshooting/system.rst create mode 100644 docs/troubleshooting/terminal.md delete mode 100644 docs/troubleshooting/terminal.rst (limited to 'docs/troubleshooting') diff --git a/docs/troubleshooting/connectivity.md b/docs/troubleshooting/connectivity.md new file mode 100644 index 00000000..a3c95d8c --- /dev/null +++ b/docs/troubleshooting/connectivity.md @@ -0,0 +1,147 @@ +# 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 \ + +Send ICMP echo requests to destination host. There are multiple options to +ping, including VRF support. + +:::{code-block} none +vyos@vyos:~$ ping 10.1.1.1 +Possible completions: + Execute the current command +adaptive Ping options +allow-broadcast +audible +bypass-route +count +deadline +do-not-fragment +flood +interface +interval +mark +no-loopback +numeric +pattern +quiet +record-route +size +timestamp +tos +ttl +verbose +vrf +::: +``` + +```{opcmd} traceroute \ + +Trace path to target. + +:::{code-block} none +vyos@vyos:~$ traceroute +Possible completions: + Track network path to specified node + + +ipv4 Track network path to +ipv6 Track network path to +::: +``` + + +## Advanced Connectivity Tests + +```{opcmd} monitor traceroute \ + +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 \ [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 \ 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 +::: +``` \ No newline at end of file diff --git a/docs/troubleshooting/connectivity.rst b/docs/troubleshooting/connectivity.rst deleted file mode 100644 index aa2a0151..00000000 --- a/docs/troubleshooting/connectivity.rst +++ /dev/null @@ -1,150 +0,0 @@ -################## -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 - - Send ICMP echo requests to destination host. There are multiple options to - ping, including VRF support. - - .. code-block:: none - - vyos@vyos:~$ ping 10.1.1.1 - Possible completions: - Execute the current command - adaptive Ping options - allow-broadcast - audible - bypass-route - count - deadline - do-not-fragment - flood - interface - interval - mark - no-loopback - numeric - pattern - quiet - record-route - size - timestamp - tos - ttl - verbose - vrf - - -.. opcmd:: traceroute - - Trace path to target. - - .. code-block:: none - - vyos@vyos:~$ traceroute - Possible completions: - Track network path to specified node - - - ipv4 Track network path to - ipv6 Track network path to - - -*************************** -Advanced Connectivity Tests -*************************** - -.. opcmd:: monitor traceroute - - 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 [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 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 diff --git a/docs/troubleshooting/index.md b/docs/troubleshooting/index.md new file mode 100644 index 00000000..31dbd87b --- /dev/null +++ b/docs/troubleshooting/index.md @@ -0,0 +1,17 @@ +(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. + +```{toctree} +:maxdepth: 1 + +connectivity +interfaces +monitoring +terminal +system +``` diff --git a/docs/troubleshooting/index.rst b/docs/troubleshooting/index.rst deleted file mode 100644 index 791afc56..00000000 --- a/docs/troubleshooting/index.rst +++ /dev/null @@ -1,18 +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. - -.. toctree:: - :maxdepth: 1 - - connectivity - interfaces - monitoring - terminal - system diff --git a/docs/troubleshooting/interfaces.md b/docs/troubleshooting/interfaces.md new file mode 100644 index 00000000..553cbf90 --- /dev/null +++ b/docs/troubleshooting/interfaces.md @@ -0,0 +1,36 @@ +# 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. + + ```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. + + ```none + set interfaces ethernet 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. diff --git a/docs/troubleshooting/interfaces.rst b/docs/troubleshooting/interfaces.rst deleted file mode 100644 index 95aceb12..00000000 --- a/docs/troubleshooting/interfaces.rst +++ /dev/null @@ -1,39 +0,0 @@ -############### -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 ethernet 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. diff --git a/docs/troubleshooting/md-connectivity.md b/docs/troubleshooting/md-connectivity.md deleted file mode 100644 index a3c95d8c..00000000 --- a/docs/troubleshooting/md-connectivity.md +++ /dev/null @@ -1,147 +0,0 @@ -# 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 \ - -Send ICMP echo requests to destination host. There are multiple options to -ping, including VRF support. - -:::{code-block} none -vyos@vyos:~$ ping 10.1.1.1 -Possible completions: - Execute the current command -adaptive Ping options -allow-broadcast -audible -bypass-route -count -deadline -do-not-fragment -flood -interface -interval -mark -no-loopback -numeric -pattern -quiet -record-route -size -timestamp -tos -ttl -verbose -vrf -::: -``` - -```{opcmd} traceroute \ - -Trace path to target. - -:::{code-block} none -vyos@vyos:~$ traceroute -Possible completions: - Track network path to specified node - - -ipv4 Track network path to -ipv6 Track network path to -::: -``` - - -## Advanced Connectivity Tests - -```{opcmd} monitor traceroute \ - -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 \ [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 \ 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 -::: -``` \ No newline at end of file diff --git a/docs/troubleshooting/md-index.md b/docs/troubleshooting/md-index.md deleted file mode 100644 index 31dbd87b..00000000 --- a/docs/troubleshooting/md-index.md +++ /dev/null @@ -1,17 +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. - -```{toctree} -:maxdepth: 1 - -connectivity -interfaces -monitoring -terminal -system -``` diff --git a/docs/troubleshooting/md-interfaces.md b/docs/troubleshooting/md-interfaces.md deleted file mode 100644 index 553cbf90..00000000 --- a/docs/troubleshooting/md-interfaces.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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. - - ```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. - - ```none - set interfaces ethernet 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. diff --git a/docs/troubleshooting/md-monitoring.md b/docs/troubleshooting/md-monitoring.md deleted file mode 100644 index 778bb057..00000000 --- a/docs/troubleshooting/md-monitoring.md +++ /dev/null @@ -1,152 +0,0 @@ -# Monitoring - -VyOS features several monitoring tools. - -```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 ` -command, replacing `` with your chosen interface. - -```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 {kbd}`Ctrl-C` and you'll be returned to the VyOS command -prompt. - -Traffic can be filtered and saved. - -```none -vyos@vyos:~$ monitor traffic interface eth0 -Possible completions: - Execute the current command - filter Monitor traffic matching filter conditions - save Save traffic dump from an interface to a file -``` - - -## Interface Bandwidth Usage - -To quickly view the bandwidth usage of an interface, use the `monitor bandwidth` command: - -```none -vyos@vyos:~$ monitor bandwidth interface eth0 -``` - -This shows the following: - -```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. - -```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. - -```none -vyos@vyos:~$ monitor bandwidth-test initiate -Possible completions: - Initiate a bandwidth test to specified host (port TCP/5001) - - -``` - - -## 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. - -```none -vyos@router:~$ monitor command "show interfaces" -``` - -Will clear the screen and show you the output of `show interfaces` every -2 seconds. - -```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 -``` diff --git a/docs/troubleshooting/md-system.md b/docs/troubleshooting/md-system.md deleted file mode 100644 index e855e385..00000000 --- a/docs/troubleshooting/md-system.md +++ /dev/null @@ -1,48 +0,0 @@ -# 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` -> -> 09. Runs `telinit q` to tell the init system to reload `/etc/inittab` -> 10. Finally it runs the post-config script -> `/config/scripts/vyos-postconfig-bootup.script` - -[debian jessie]: https://www.debian.org/releases/jessie/ -[frr]: https://frrouting.org/ -[gnu zebra]: https://www.gnu.org/software/zebra/ -[pcap filter expressions]: http://www.tcpdump.org/manpages/pcap-filter.7.html -[quagga]: https://www.quagga.net/ -[systemd]: https://freedesktop.org/wiki/Software/systemd/ -[tshark]: https://www.wireshark.org/docs/man-pages/tshark.html -[vyatta-cfg]: https://github.com/vyos/vyatta-cfg diff --git a/docs/troubleshooting/md-terminal.md b/docs/troubleshooting/md-terminal.md deleted file mode 100644 index 0d421972..00000000 --- a/docs/troubleshooting/md-terminal.md +++ /dev/null @@ -1,39 +0,0 @@ -# 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 - -```none -vyos@vyos:~$ clear console -``` - -to clear interface counters - -```none -# clear all interfaces -vyos@vyos:~$ clear interface ethernet counters -# clear specific interface -vyos@vyos:~$ clear interface ethernet eth0 counters -``` - -The command follows the same logic as the `set` command in configuration mode. - -```none -# clear all counters of an interface type -vyos@vyos:~$ clear interface counters -# clear counter of an interface in interface_type -vyos@vyos:~$ clear interface counters -``` - -to clear counters on firewall rulesets or single rules - -```none -vyos@vyos:~$ clear firewall name counters -vyos@vyos:~$ clear firewall name rule counters - -vyos@vyos:~$ clear firewall ipv6-name counters -vyos@vyos:~$ clear firewall ipv6-name rule counters -``` diff --git a/docs/troubleshooting/monitoring.md b/docs/troubleshooting/monitoring.md new file mode 100644 index 00000000..778bb057 --- /dev/null +++ b/docs/troubleshooting/monitoring.md @@ -0,0 +1,152 @@ +# Monitoring + +VyOS features several monitoring tools. + +```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 ` +command, replacing `` with your chosen interface. + +```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 {kbd}`Ctrl-C` and you'll be returned to the VyOS command +prompt. + +Traffic can be filtered and saved. + +```none +vyos@vyos:~$ monitor traffic interface eth0 +Possible completions: + Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file +``` + + +## Interface Bandwidth Usage + +To quickly view the bandwidth usage of an interface, use the `monitor bandwidth` command: + +```none +vyos@vyos:~$ monitor bandwidth interface eth0 +``` + +This shows the following: + +```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. + +```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. + +```none +vyos@vyos:~$ monitor bandwidth-test initiate +Possible completions: + Initiate a bandwidth test to specified host (port TCP/5001) + + +``` + + +## 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. + +```none +vyos@router:~$ monitor command "show interfaces" +``` + +Will clear the screen and show you the output of `show interfaces` every +2 seconds. + +```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 +``` diff --git a/docs/troubleshooting/monitoring.rst b/docs/troubleshooting/monitoring.rst deleted file mode 100644 index ef40c937..00000000 --- a/docs/troubleshooting/monitoring.rst +++ /dev/null @@ -1,161 +0,0 @@ -########## -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 ` -command, replacing `` 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 :kbd:`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: - Execute the current command - filter Monitor traffic matching filter conditions - save Save traffic dump from an interface to a file - - -************************* -Interface Bandwidth Usage -************************* - -To quickly view the bandwidth usage of an interface, use the ``monitor bandwidth`` command: - -.. code-block:: none - - vyos@vyos:~$ monitor bandwidth interface eth0 - -This shows 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: - Initiate a bandwidth test to specified host (port TCP/5001) - - - - -*************** -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 diff --git a/docs/troubleshooting/rst-connectivity.rst b/docs/troubleshooting/rst-connectivity.rst new file mode 100644 index 00000000..aa2a0151 --- /dev/null +++ b/docs/troubleshooting/rst-connectivity.rst @@ -0,0 +1,150 @@ +################## +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 + + Send ICMP echo requests to destination host. There are multiple options to + ping, including VRF support. + + .. code-block:: none + + vyos@vyos:~$ ping 10.1.1.1 + Possible completions: + Execute the current command + adaptive Ping options + allow-broadcast + audible + bypass-route + count + deadline + do-not-fragment + flood + interface + interval + mark + no-loopback + numeric + pattern + quiet + record-route + size + timestamp + tos + ttl + verbose + vrf + + +.. opcmd:: traceroute + + Trace path to target. + + .. code-block:: none + + vyos@vyos:~$ traceroute + Possible completions: + Track network path to specified node + + + ipv4 Track network path to + ipv6 Track network path to + + +*************************** +Advanced Connectivity Tests +*************************** + +.. opcmd:: monitor traceroute + + 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 [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 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 diff --git a/docs/troubleshooting/rst-index.rst b/docs/troubleshooting/rst-index.rst new file mode 100644 index 00000000..791afc56 --- /dev/null +++ b/docs/troubleshooting/rst-index.rst @@ -0,0 +1,18 @@ +.. _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. + +.. toctree:: + :maxdepth: 1 + + connectivity + interfaces + monitoring + terminal + system diff --git a/docs/troubleshooting/rst-interfaces.rst b/docs/troubleshooting/rst-interfaces.rst new file mode 100644 index 00000000..95aceb12 --- /dev/null +++ b/docs/troubleshooting/rst-interfaces.rst @@ -0,0 +1,39 @@ +############### +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 ethernet 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. diff --git a/docs/troubleshooting/rst-monitoring.rst b/docs/troubleshooting/rst-monitoring.rst new file mode 100644 index 00000000..ef40c937 --- /dev/null +++ b/docs/troubleshooting/rst-monitoring.rst @@ -0,0 +1,161 @@ +########## +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 ` +command, replacing `` 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 :kbd:`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: + Execute the current command + filter Monitor traffic matching filter conditions + save Save traffic dump from an interface to a file + + +************************* +Interface Bandwidth Usage +************************* + +To quickly view the bandwidth usage of an interface, use the ``monitor bandwidth`` command: + +.. code-block:: none + + vyos@vyos:~$ monitor bandwidth interface eth0 + +This shows 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: + Initiate a bandwidth test to specified host (port TCP/5001) + + + + +*************** +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 diff --git a/docs/troubleshooting/rst-system.rst b/docs/troubleshooting/rst-system.rst new file mode 100644 index 00000000..3a9ec735 --- /dev/null +++ b/docs/troubleshooting/rst-system.rst @@ -0,0 +1,57 @@ +################## +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`` + + 9. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` + 10. 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/docs/troubleshooting/rst-terminal.rst b/docs/troubleshooting/rst-terminal.rst new file mode 100644 index 00000000..fb197730 --- /dev/null +++ b/docs/troubleshooting/rst-terminal.rst @@ -0,0 +1,42 @@ +################ +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 ethernet eth0 counters + +The command follows the same logic as the ``set`` command in configuration mode. + +.. code-block:: none + + # clear all counters of an interface type + vyos@vyos:~$ clear interface counters + # clear counter of an interface in interface_type + vyos@vyos:~$ clear interface counters + + +to clear counters on firewall rulesets or single rules + +.. code-block:: none + + vyos@vyos:~$ clear firewall name counters + vyos@vyos:~$ clear firewall name rule counters + + vyos@vyos:~$ clear firewall ipv6-name counters + vyos@vyos:~$ clear firewall ipv6-name rule counters diff --git a/docs/troubleshooting/system.md b/docs/troubleshooting/system.md new file mode 100644 index 00000000..e855e385 --- /dev/null +++ b/docs/troubleshooting/system.md @@ -0,0 +1,48 @@ +# 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` +> +> 09. Runs `telinit q` to tell the init system to reload `/etc/inittab` +> 10. Finally it runs the post-config script +> `/config/scripts/vyos-postconfig-bootup.script` + +[debian jessie]: https://www.debian.org/releases/jessie/ +[frr]: https://frrouting.org/ +[gnu zebra]: https://www.gnu.org/software/zebra/ +[pcap filter expressions]: http://www.tcpdump.org/manpages/pcap-filter.7.html +[quagga]: https://www.quagga.net/ +[systemd]: https://freedesktop.org/wiki/Software/systemd/ +[tshark]: https://www.wireshark.org/docs/man-pages/tshark.html +[vyatta-cfg]: https://github.com/vyos/vyatta-cfg diff --git a/docs/troubleshooting/system.rst b/docs/troubleshooting/system.rst deleted file mode 100644 index 3a9ec735..00000000 --- a/docs/troubleshooting/system.rst +++ /dev/null @@ -1,57 +0,0 @@ -################## -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`` - - 9. Runs ``telinit q`` to tell the init system to reload ``/etc/inittab`` - 10. 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/docs/troubleshooting/terminal.md b/docs/troubleshooting/terminal.md new file mode 100644 index 00000000..0d421972 --- /dev/null +++ b/docs/troubleshooting/terminal.md @@ -0,0 +1,39 @@ +# 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 + +```none +vyos@vyos:~$ clear console +``` + +to clear interface counters + +```none +# clear all interfaces +vyos@vyos:~$ clear interface ethernet counters +# clear specific interface +vyos@vyos:~$ clear interface ethernet eth0 counters +``` + +The command follows the same logic as the `set` command in configuration mode. + +```none +# clear all counters of an interface type +vyos@vyos:~$ clear interface counters +# clear counter of an interface in interface_type +vyos@vyos:~$ clear interface counters +``` + +to clear counters on firewall rulesets or single rules + +```none +vyos@vyos:~$ clear firewall name counters +vyos@vyos:~$ clear firewall name rule counters + +vyos@vyos:~$ clear firewall ipv6-name counters +vyos@vyos:~$ clear firewall ipv6-name rule counters +``` diff --git a/docs/troubleshooting/terminal.rst b/docs/troubleshooting/terminal.rst deleted file mode 100644 index fb197730..00000000 --- a/docs/troubleshooting/terminal.rst +++ /dev/null @@ -1,42 +0,0 @@ -################ -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 ethernet eth0 counters - -The command follows the same logic as the ``set`` command in configuration mode. - -.. code-block:: none - - # clear all counters of an interface type - vyos@vyos:~$ clear interface counters - # clear counter of an interface in interface_type - vyos@vyos:~$ clear interface counters - - -to clear counters on firewall rulesets or single rules - -.. code-block:: none - - vyos@vyos:~$ clear firewall name counters - vyos@vyos:~$ clear firewall name rule counters - - vyos@vyos:~$ clear firewall ipv6-name counters - vyos@vyos:~$ clear firewall ipv6-name rule counters -- cgit v1.2.3