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/troubleshooting/system.rst | 57 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/troubleshooting/system.rst (limited to 'docs/troubleshooting/system.rst') 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 -- cgit v1.2.3