From dad139434e34d3bbf24fd46c8fa8ea7a54177d0a Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Mon, 30 Mar 2026 13:33:30 +0300 Subject: Split troubleshooting, add contributing index, clean VPN structure (#1804) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Add design spec for documentation improvements Covers 4 work streams: mechanical fixes (headings, indentation, typos), content quality (TODO flags, TBD fills, stub markers), structural reorganization (troubleshooting split, contributing index, VPN cleanup), and RTD platform cleanup (hide versions, delete stale redirects). Co-Authored-By: Claude Opus 4.6 (1M context) * Fix spec issues from review: correct heading chars, tab counts, line numbers Addresses 10 reviewer findings: corrected heading character types (^ was actually -), removed ip.rst (already correct), updated file count from 37 to 35, listed all 13 tab-containing files, fixed troubleshooting line count to 460, added heading level guidance for split pages, clarified contributing/documentation.rst scope, removed current from hide list, added rollback verification step, updated success criteria. Co-Authored-By: Claude Opus 4.6 (1M context) * Add implementation plan for documentation improvements 16 tasks across 4 work streams: mechanical fixes (PR 1, tasks 1-6), content quality (PR 2, tasks 7-10), structural reorg (PR 3, tasks 11-14), and RTD platform cleanup (tasks 15-16). Co-Authored-By: Claude Opus 4.6 (1M context) * Fix 6 issues from plan review - Replace hardcoded RTD token with $RTD_TOKEN variable - Fix Task 7 heading reference to be format-agnostic - Correct RTD PATCH expected response (200, not 204) - Fix version verification to check hidden field, not active - Account for blank lines 402-403 in troubleshooting split - Clarify start/stop_vyoslinter handling in system.rst Co-Authored-By: Claude Opus 4.6 (1M context) * refactor: split troubleshooting into 5 focused sub-pages Split monolithic 460-line troubleshooting/index.rst into: - connectivity.rst (ping, traceroute, mtr, IPv6 discovery) - interfaces.rst (interface naming, MAC addresses) - monitoring.rst (traffic dumps, bandwidth, iperf) - terminal.rst (console clearing, counter resets) - system.rst (boot steps, system information) Co-Authored-By: Claude Sonnet 4.6 * refactor: create contributing/index.rst, simplify root toctree * fix: remove 'pages to sort' placeholders from VPN section * fix: wrap long lines in index.rst for linter compliance * Add design spec for sitemap generation improvement * Fix sitemap spec: remove invalid sitemap_excludes, add version pin * fix: address Copilot review suggestions — grammar, typos, RST markup fixes Co-Authored-By: Claude Sonnet 4.6 * fix: resolve remaining long lines in index.rst Shorten :ref: display text on two lines that exceeded the 80-char limit: "Virtual Environment" -> "VM" (line 24, 90 -> 73 chars) and "Configuration Blueprints" -> "Blueprints" (line 51, 85 -> 71 chars). Both targets remain correct; display text is clear in context. Co-Authored-By: Claude Sonnet 4.6 * chore: remove superpowers specs from PR Specs moved to personal branch yuriy/docs-modernization-specs. Co-Authored-By: Claude Opus 4.6 (1M context) --------- Co-authored-by: Claude Opus 4.6 (1M context) --- docs/configuration/vpn/index.rst | 10 +- docs/configuration/vpn/ipsec/index.rst | 8 - docs/contributing/index.rst | 14 + docs/index.rst | 44 ++-- docs/troubleshooting/connectivity.rst | 150 +++++++++++ docs/troubleshooting/index.rst | 458 +-------------------------------- docs/troubleshooting/interfaces.rst | 39 +++ docs/troubleshooting/monitoring.rst | 161 ++++++++++++ docs/troubleshooting/system.rst | 57 ++++ docs/troubleshooting/terminal.rst | 42 +++ 10 files changed, 498 insertions(+), 485 deletions(-) create mode 100644 docs/contributing/index.rst create mode 100644 docs/troubleshooting/connectivity.rst create mode 100644 docs/troubleshooting/interfaces.rst create mode 100644 docs/troubleshooting/monitoring.rst create mode 100644 docs/troubleshooting/system.rst create mode 100644 docs/troubleshooting/terminal.rst diff --git a/docs/configuration/vpn/index.rst b/docs/configuration/vpn/index.rst index d0121abd..228f83ca 100644 --- a/docs/configuration/vpn/index.rst +++ b/docs/configuration/vpn/index.rst @@ -7,18 +7,10 @@ VPN :maxdepth: 1 :includehidden: + dmvpn ipsec/index l2tp openconnect pptp rsa-keys sstp - - -pages to sort - -.. toctree:: - :maxdepth: 1 - :includehidden: - - dmvpn diff --git a/docs/configuration/vpn/ipsec/index.rst b/docs/configuration/vpn/ipsec/index.rst index e454e2f6..7647d8d2 100644 --- a/docs/configuration/vpn/ipsec/index.rst +++ b/docs/configuration/vpn/ipsec/index.rst @@ -11,11 +11,3 @@ IPsec site2site_ipsec remoteaccess_ipsec troubleshooting_ipsec - -pages to sort - -.. toctree:: - :maxdepth: 1 - :includehidden: - - diff --git a/docs/contributing/index.rst b/docs/contributing/index.rst new file mode 100644 index 00000000..18b925ec --- /dev/null +++ b/docs/contributing/index.rst @@ -0,0 +1,14 @@ +############ +Contributing +############ + +.. toctree:: + :maxdepth: 1 + + build-vyos + development + cla + issues-features + upstream-packages + debugging + testing diff --git a/docs/index.rst b/docs/index.rst index 70b862b4..660daa46 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,20 +11,27 @@ VyOS User Guide .. grid-item-card:: Get / Build VyOS - Quickly :ref:`Build` your own Image or take a look at how to :ref:`download` a free or supported version. + Quickly :ref:`Build` + your own Image or take a look at how to + :ref:`download` + a free or supported version. .. grid-item-card:: Install VyOS - Read about how to install VyOS on :ref:`Bare Metal` or in a - :ref:`Virtual Environment` and - how to use an image with the usual :ref:`cloud` providers + Read about how to install VyOS on + :ref:`Bare Metal` + or in a :ref:`VM ` + and how to use an image with the usual + :ref:`cloud` + providers .. grid-item-card:: Configuration and Operation - Use the :ref:`Quickstart Guide`, to have a fast overview. Or go deeper and - set up :ref:`advanced routing`, + Use the :ref:`Quickstart Guide`, + to have a fast overview. Or go deeper and set up + :ref:`advanced routing`, :ref:`VRFs`, or :ref:`VPNs` for example. @@ -33,21 +40,28 @@ VyOS User Guide Integrate VyOS in your automation Workflow with :ref:`Ansible`, - have your own :ref:`local scripts`, or configure VyOS with the :ref:`HTTPS-API`. + have your own :ref:`local scripts`, + or configure VyOS with the + :ref:`HTTPS-API`. .. grid-item-card:: Examples - Get some inspiration from the :ref:`Configuration Blueprints` + Get some inspiration from the + :ref:`Blueprints ` to build your infrastructure. .. grid-item-card:: Contribute and Community | There are many ways to contribute to the project. - | Add missing parts or improve the :ref:`Documentation`. - | Discuss in `Slack `_ or the `Forum `_. - | Or you can pick up a `Task `_ and fix the :ref:`code`. + | Add missing parts or improve the + :ref:`Documentation`. + | Discuss in `Slack `_ + or the `Forum `_. + | Or you can pick up a `Task `_ + and fix the + :ref:`code`. .. toctree:: @@ -86,13 +100,7 @@ VyOS User Guide :hidden: :caption: Development - contributing/build-vyos - contributing/development - contributing/cla - contributing/issues-features - contributing/upstream-packages - contributing/debugging - contributing/testing + contributing/index .. toctree:: diff --git a/docs/troubleshooting/connectivity.rst b/docs/troubleshooting/connectivity.rst new file mode 100644 index 00000000..aa2a0151 --- /dev/null +++ b/docs/troubleshooting/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/index.rst b/docs/troubleshooting/index.rst index 8a34edd9..791afc56 100644 --- a/docs/troubleshooting/index.rst +++ b/docs/troubleshooting/index.rst @@ -8,453 +8,11 @@ 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 - - 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: - 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 - - -*************** -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 ` -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 `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 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: - 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 - -**************** -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 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 counters - # clear counter of a 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 - - -****************** -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 +.. toctree:: + :maxdepth: 1 + + connectivity + interfaces + monitoring + terminal + system diff --git a/docs/troubleshooting/interfaces.rst b/docs/troubleshooting/interfaces.rst new file mode 100644 index 00000000..95aceb12 --- /dev/null +++ b/docs/troubleshooting/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/monitoring.rst b/docs/troubleshooting/monitoring.rst new file mode 100644 index 00000000..ef40c937 --- /dev/null +++ b/docs/troubleshooting/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/system.rst b/docs/troubleshooting/system.rst new file mode 100644 index 00000000..3a9ec735 --- /dev/null +++ b/docs/troubleshooting/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/terminal.rst b/docs/troubleshooting/terminal.rst new file mode 100644 index 00000000..fb197730 --- /dev/null +++ b/docs/troubleshooting/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 -- cgit v1.2.3