From b8b3044d3c3515d91de0f44785bfd965174867df Mon Sep 17 00:00:00 2001 From: Yuriy Andamasov Date: Wed, 6 May 2026 21:50:08 +0300 Subject: feat: flip swap mechanism on sagitta — MD as primary, RST as override MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mirror of #1899 (current) and #1900 (circinus) for sagitta. Same logic, same scripts, per-branch file set. Changes: - Rename docs/**/md-.md to docs/**/.md (drop md- prefix) for all 210 stems previously listed in docs/_swap.txt - Rename docs/**/.rst to docs/**/rst-.rst (add rst- prefix) for the same 210 stems - Repurpose docs/_swap.txt as docs/_rst_overrides.txt; initially empty - conf.py exclude_patterns flipped: rst-*.rst excluded by default - conf.py runtime-artifact references updated to _rst_override_state.json and _md_exclude.txt - scripts/swap_sources.py imported from current (post-#1899 rewrite, with inverted rename direction) - scripts/import_myst.py and tests/test_import_myst.py deleted (obsolete) - tests/test_swap_sources.py imported from current (post-#1899 rewrite) Side-effect: fixes the same 404 on /en/1.4/ View page source links that #1899 fixed for /en/rolling/ and #1900 fixed for /en/1.5/. Per-branch differences vs #1899: - sagitta has 210 stems vs current's 254 (sagitta has no vpp pages and fewer current-only features; cli + installation/cloud/aws are still RST-only on sagitta pending the title-level fix follow-up) - otherwise the script/conf.py/test changes are byte-identical with current Generated by robots https://vyos.io --- docs/operation/boot-options.md | 53 +++++++ docs/operation/boot-options.rst | 58 ------- docs/operation/index.md | 12 ++ docs/operation/index.rst | 12 -- docs/operation/information.md | 159 ++++++++++++++++++++ docs/operation/information.rst | 155 ------------------- docs/operation/md-boot-options.md | 53 ------- docs/operation/md-index.md | 12 -- docs/operation/md-information.md | 159 -------------------- docs/operation/md-password-recovery.md | 24 --- docs/operation/md-raid.md | 249 ------------------------------- docs/operation/password-recovery.md | 24 +++ docs/operation/password-recovery.rst | 25 ---- docs/operation/raid.md | 249 +++++++++++++++++++++++++++++++ docs/operation/raid.rst | 245 ------------------------------ docs/operation/rst-boot-options.rst | 58 +++++++ docs/operation/rst-index.rst | 12 ++ docs/operation/rst-information.rst | 155 +++++++++++++++++++ docs/operation/rst-password-recovery.rst | 25 ++++ docs/operation/rst-raid.rst | 245 ++++++++++++++++++++++++++++++ 20 files changed, 992 insertions(+), 992 deletions(-) create mode 100644 docs/operation/boot-options.md delete mode 100644 docs/operation/boot-options.rst create mode 100644 docs/operation/index.md delete mode 100644 docs/operation/index.rst create mode 100644 docs/operation/information.md delete mode 100644 docs/operation/information.rst delete mode 100644 docs/operation/md-boot-options.md delete mode 100644 docs/operation/md-index.md delete mode 100644 docs/operation/md-information.md delete mode 100644 docs/operation/md-password-recovery.md delete mode 100644 docs/operation/md-raid.md create mode 100644 docs/operation/password-recovery.md delete mode 100755 docs/operation/password-recovery.rst create mode 100644 docs/operation/raid.md delete mode 100644 docs/operation/raid.rst create mode 100644 docs/operation/rst-boot-options.rst create mode 100644 docs/operation/rst-index.rst create mode 100644 docs/operation/rst-information.rst create mode 100755 docs/operation/rst-password-recovery.rst create mode 100644 docs/operation/rst-raid.rst (limited to 'docs/operation') diff --git a/docs/operation/boot-options.md b/docs/operation/boot-options.md new file mode 100644 index 00000000..ea077c8a --- /dev/null +++ b/docs/operation/boot-options.md @@ -0,0 +1,53 @@ +(boot-options)= + +# Boot Options + +:::{warning} +This function may be highly disruptive. +It may cause major service interruption, so make sure you really +need it and verify your input carefully. +::: + +VyOS has several kernel command line options to modify the normal boot +process. +To add an option, select the desired image in GRUB menu at load +time, press **e**, edit the first line, and press **Ctrl-x** to boot when +ready. + +```{image} /_static/images/boot-options.png +:align: center +:width: 80% +``` + +## Specify custom config file + +Tells the system to use specified file instead of `/config/config.boot`. +If specified file does not exist or is not readable, fall back to +default config. No additional verification is performed, so make sure +you specify a valid config file. + +```none +vyos-config=/path/to/file +``` + +To load the *factory default* config, use: + +```none +vyos-config=/opt/vyatta/etc/config.boot.default +``` + +## Disable specific boot process steps + +These options disable some boot steps. Make sure you understand the +{ref}`boot process ` well before using them! + +```{eval-rst} +.. glossary:: + + no-vyos-migrate + Do not perform config migration. + + no-vyos-firewall + Do not initialize default firewall chains, renders any firewall + configuration unusable. +``` diff --git a/docs/operation/boot-options.rst b/docs/operation/boot-options.rst deleted file mode 100644 index 70cdc418..00000000 --- a/docs/operation/boot-options.rst +++ /dev/null @@ -1,58 +0,0 @@ -.. _boot-options: - - -############ -Boot Options -############ - -.. warning:: This function may be highly disruptive. - It may cause major service interruption, so make sure you really - need it and verify your input carefully. - - - -VyOS has several kernel command line options to modify the normal boot -process. -To add an option, select the desired image in GRUB menu at load -time, press **e**, edit the first line, and press **Ctrl-x** to boot when -ready. - -.. image:: /_static/images/boot-options.png - :width: 80% - :align: center - - -Specify custom config file -========================== - -Tells the system to use specified file instead of ``/config/config.boot``. -If specified file does not exist or is not readable, fall back to -default config. No additional verification is performed, so make sure -you specify a valid config file. - -.. code-block:: none - - vyos-config=/path/to/file - -To load the *factory default* config, use: - -.. code-block:: none - - vyos-config=/opt/vyatta/etc/config.boot.default - - -Disable specific boot process steps -=================================== - -These options disable some boot steps. Make sure you understand the -:ref:`boot process ` well before using them! - -.. glossary:: - - no-vyos-migrate - Do not perform config migration. - - no-vyos-firewall - Do not initialize default firewall chains, renders any firewall - configuration unusable. - diff --git a/docs/operation/index.md b/docs/operation/index.md new file mode 100644 index 00000000..f4328541 --- /dev/null +++ b/docs/operation/index.md @@ -0,0 +1,12 @@ +# Operation Mode + +```{eval-rst} +.. toctree:: + :maxdepth: 1 + :includehidden: + + information + boot-options + password-recovery + raid +``` diff --git a/docs/operation/index.rst b/docs/operation/index.rst deleted file mode 100644 index 037c9286..00000000 --- a/docs/operation/index.rst +++ /dev/null @@ -1,12 +0,0 @@ -############## -Operation Mode -############## - -.. toctree:: - :maxdepth: 1 - :includehidden: - - information - boot-options - password-recovery - raid \ No newline at end of file diff --git a/docs/operation/information.md b/docs/operation/information.md new file mode 100644 index 00000000..314811ec --- /dev/null +++ b/docs/operation/information.md @@ -0,0 +1,159 @@ +--- +lastproofread: '2021-07-07' +--- + +(information)= + +# Information + +VyOS features a rich set of operational level commands to retrieve arbitrary +information about your running system. + +## Hardware + +(hardware_usb)= + +### USB + +In the past serial interface have been defined as ttySx and ttyUSBx where x was +an instance number of the serial interface. It was discovered that from system +boot to system boot the mapping of USB based serial interfaces will differ, +depending which driver was loaded first by the operating system. This will +become rather painful if you not only have serial interfaces for a console +server connected but in addition also a serial backed {ref}`wwan-interface`. + +To overcome this issue and the fact that in almost 50% of all cheap USB to +serial converters there is no serial number programmed, the USB to serial +interface is now directly identified by the USB root bridge and bus it connects +to. This somehow mimics the new network interface definitions we see in recent +Linux distributions. + +For additional details you can refer to . + +```{eval-rst} +.. opcmd:: show hardware usb + + Retrieve a tree like representation of all connected USB devices. + + .. note:: If a device is unplugged and re-plugged it will receive a new + Port, Dev, If identification. + + .. code-block:: none + + vyos@vyos:~$ show hardware usb + /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M + /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M + /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M + |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + +``` + +```{eval-rst} +.. opcmd:: show hardware usb serial + + Retrieve a list and description of all connected USB serial devices. The + device name displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing + the serial console as console-server device. + + .. code-block:: none + + vyos@vyos$ show hardware usb serial + Device Model Vendor + ------ ------ ------ + usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. + usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. + usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd +``` + +(information-version)= + +## Version + +```{eval-rst} +.. opcmd:: show version + + Return the current running VyOS version and build information. This includes + also the name of the release train which is ``crux`` on VyOS 1.2, ``equuleus`` + on VyOS 1.3 and ``sagitta`` on VyOS 1.4. + + .. code-block:: none + + vyos@vyos:~$ show version + + Version: VyOS 1.4-rolling-202106270801 + Release Train: sagitta + + Built by: autobuild@vyos.net + Built on: Sun 27 Jun 2021 09:50 UTC + Build UUID: ab43e735-edcb-405a-9f51-f16a1b104e52 + Build Commit ID: f544d75eab758f + + Architecture: x86_64 + Boot via: installed image + System type: KVM guest + + Hardware vendor: QEMU + Hardware model: Standard PC (i440FX + PIIX, 1996) + Hardware S/N: + Hardware UUID: Unknown + + Copyright: VyOS maintainers and contributors +``` + +```{eval-rst} +.. opcmd:: show version kernel + + Return version number of the Linux Kernel used in this release. + + .. code-block:: none + + vyos@vyos:~$ show version kernel + 5.10.46-amd64-vyos +``` + +```{eval-rst} +.. opcmd:: show version frr + + Return version number of FRR (Free Range Routing - https://frrouting.org/) + used in this release. This is the routing control plane and a successor to GNU + Zebra and Quagga. + + .. code-block:: none + + vyos@vyos:~$ show version frr + FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos). + Copyright 1996-2005 Kunihiro Ishiguro, et al. +``` diff --git a/docs/operation/information.rst b/docs/operation/information.rst deleted file mode 100644 index e32e55b4..00000000 --- a/docs/operation/information.rst +++ /dev/null @@ -1,155 +0,0 @@ -:lastproofread: 2021-07-07 - -.. _information: - -*********** -Information -*********** - -VyOS features a rich set of operational level commands to retrieve arbitrary -information about your running system. - -######## -Hardware -######## - -.. _hardware_usb: - -USB -=== - -In the past serial interface have been defined as ttySx and ttyUSBx where x was -an instance number of the serial interface. It was discovered that from system -boot to system boot the mapping of USB based serial interfaces will differ, -depending which driver was loaded first by the operating system. This will -become rather painful if you not only have serial interfaces for a console -server connected but in addition also a serial backed :ref:`wwan-interface`. - -To overcome this issue and the fact that in almost 50% of all cheap USB to -serial converters there is no serial number programmed, the USB to serial -interface is now directly identified by the USB root bridge and bus it connects -to. This somehow mimics the new network interface definitions we see in recent -Linux distributions. - -For additional details you can refer to https://vyos.dev/T2490. - -.. opcmd:: show hardware usb - - Retrieve a tree like representation of all connected USB devices. - - .. note:: If a device is unplugged and re-plugged it will receive a new - Port, Dev, If identification. - - .. code-block:: none - - vyos@vyos:~$ show hardware usb - /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M - |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M - /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M - /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M - |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M - |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - - -.. opcmd:: show hardware usb serial - - Retrieve a list and description of all connected USB serial devices. The - device name displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing - the serial console as console-server device. - - .. code-block:: none - - vyos@vyos$ show hardware usb serial - Device Model Vendor - ------ ------ ------ - usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. - usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. - usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. - usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. - usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - -.. _information_version: - -######## -Version -######## - -.. opcmd:: show version - - Return the current running VyOS version and build information. This includes - also the name of the release train which is ``crux`` on VyOS 1.2, ``equuleus`` - on VyOS 1.3 and ``sagitta`` on VyOS 1.4. - - .. code-block:: none - - vyos@vyos:~$ show version - - Version: VyOS 1.4-rolling-202106270801 - Release Train: sagitta - - Built by: autobuild@vyos.net - Built on: Sun 27 Jun 2021 09:50 UTC - Build UUID: ab43e735-edcb-405a-9f51-f16a1b104e52 - Build Commit ID: f544d75eab758f - - Architecture: x86_64 - Boot via: installed image - System type: KVM guest - - Hardware vendor: QEMU - Hardware model: Standard PC (i440FX + PIIX, 1996) - Hardware S/N: - Hardware UUID: Unknown - - Copyright: VyOS maintainers and contributors - -.. opcmd:: show version kernel - - Return version number of the Linux Kernel used in this release. - - .. code-block:: none - - vyos@vyos:~$ show version kernel - 5.10.46-amd64-vyos - -.. opcmd:: show version frr - - Return version number of FRR (Free Range Routing - https://frrouting.org/) - used in this release. This is the routing control plane and a successor to GNU - Zebra and Quagga. - - .. code-block:: none - - vyos@vyos:~$ show version frr - FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos). - Copyright 1996-2005 Kunihiro Ishiguro, et al. - diff --git a/docs/operation/md-boot-options.md b/docs/operation/md-boot-options.md deleted file mode 100644 index ea077c8a..00000000 --- a/docs/operation/md-boot-options.md +++ /dev/null @@ -1,53 +0,0 @@ -(boot-options)= - -# Boot Options - -:::{warning} -This function may be highly disruptive. -It may cause major service interruption, so make sure you really -need it and verify your input carefully. -::: - -VyOS has several kernel command line options to modify the normal boot -process. -To add an option, select the desired image in GRUB menu at load -time, press **e**, edit the first line, and press **Ctrl-x** to boot when -ready. - -```{image} /_static/images/boot-options.png -:align: center -:width: 80% -``` - -## Specify custom config file - -Tells the system to use specified file instead of `/config/config.boot`. -If specified file does not exist or is not readable, fall back to -default config. No additional verification is performed, so make sure -you specify a valid config file. - -```none -vyos-config=/path/to/file -``` - -To load the *factory default* config, use: - -```none -vyos-config=/opt/vyatta/etc/config.boot.default -``` - -## Disable specific boot process steps - -These options disable some boot steps. Make sure you understand the -{ref}`boot process ` well before using them! - -```{eval-rst} -.. glossary:: - - no-vyos-migrate - Do not perform config migration. - - no-vyos-firewall - Do not initialize default firewall chains, renders any firewall - configuration unusable. -``` diff --git a/docs/operation/md-index.md b/docs/operation/md-index.md deleted file mode 100644 index f4328541..00000000 --- a/docs/operation/md-index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Operation Mode - -```{eval-rst} -.. toctree:: - :maxdepth: 1 - :includehidden: - - information - boot-options - password-recovery - raid -``` diff --git a/docs/operation/md-information.md b/docs/operation/md-information.md deleted file mode 100644 index 314811ec..00000000 --- a/docs/operation/md-information.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -lastproofread: '2021-07-07' ---- - -(information)= - -# Information - -VyOS features a rich set of operational level commands to retrieve arbitrary -information about your running system. - -## Hardware - -(hardware_usb)= - -### USB - -In the past serial interface have been defined as ttySx and ttyUSBx where x was -an instance number of the serial interface. It was discovered that from system -boot to system boot the mapping of USB based serial interfaces will differ, -depending which driver was loaded first by the operating system. This will -become rather painful if you not only have serial interfaces for a console -server connected but in addition also a serial backed {ref}`wwan-interface`. - -To overcome this issue and the fact that in almost 50% of all cheap USB to -serial converters there is no serial number programmed, the USB to serial -interface is now directly identified by the USB root bridge and bus it connects -to. This somehow mimics the new network interface definitions we see in recent -Linux distributions. - -For additional details you can refer to . - -```{eval-rst} -.. opcmd:: show hardware usb - - Retrieve a tree like representation of all connected USB devices. - - .. note:: If a device is unplugged and re-plugged it will receive a new - Port, Dev, If identification. - - .. code-block:: none - - vyos@vyos:~$ show hardware usb - /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M - |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M - |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M - /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M - /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M - |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M - |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M - |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M - -``` - -```{eval-rst} -.. opcmd:: show hardware usb serial - - Retrieve a list and description of all connected USB serial devices. The - device name displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing - the serial console as console-server device. - - .. code-block:: none - - vyos@vyos$ show hardware usb serial - Device Model Vendor - ------ ------ ------ - usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. - usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. - usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. - usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. - usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd - usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd -``` - -(information-version)= - -## Version - -```{eval-rst} -.. opcmd:: show version - - Return the current running VyOS version and build information. This includes - also the name of the release train which is ``crux`` on VyOS 1.2, ``equuleus`` - on VyOS 1.3 and ``sagitta`` on VyOS 1.4. - - .. code-block:: none - - vyos@vyos:~$ show version - - Version: VyOS 1.4-rolling-202106270801 - Release Train: sagitta - - Built by: autobuild@vyos.net - Built on: Sun 27 Jun 2021 09:50 UTC - Build UUID: ab43e735-edcb-405a-9f51-f16a1b104e52 - Build Commit ID: f544d75eab758f - - Architecture: x86_64 - Boot via: installed image - System type: KVM guest - - Hardware vendor: QEMU - Hardware model: Standard PC (i440FX + PIIX, 1996) - Hardware S/N: - Hardware UUID: Unknown - - Copyright: VyOS maintainers and contributors -``` - -```{eval-rst} -.. opcmd:: show version kernel - - Return version number of the Linux Kernel used in this release. - - .. code-block:: none - - vyos@vyos:~$ show version kernel - 5.10.46-amd64-vyos -``` - -```{eval-rst} -.. opcmd:: show version frr - - Return version number of FRR (Free Range Routing - https://frrouting.org/) - used in this release. This is the routing control plane and a successor to GNU - Zebra and Quagga. - - .. code-block:: none - - vyos@vyos:~$ show version frr - FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos). - Copyright 1996-2005 Kunihiro Ishiguro, et al. -``` diff --git a/docs/operation/md-password-recovery.md b/docs/operation/md-password-recovery.md deleted file mode 100644 index 91f3d60f..00000000 --- a/docs/operation/md-password-recovery.md +++ /dev/null @@ -1,24 +0,0 @@ -(password-recovery)= - -# Password Recovery - -Using the console, restart the VyOS router. The GRUB menu appears. -Select the relevant option from the GRUB menu and press Enter. -The option must start with “Lost password change.” - -:::{figure} /_static/images/password-recovery-01.png -:width: 600 -::: - -The stand-alone user-password recovery tool starts running and prompts -you to reset the local system user password. - -```console -Do you wish to reset the admin password? (y or n) -y -Which admin account do you want to reset?[vyos] -my_username -Enter my_username password: -Retype my_username password: -System will reboot in 10 seconds... -``` diff --git a/docs/operation/md-raid.md b/docs/operation/md-raid.md deleted file mode 100644 index 71a6ad5e..00000000 --- a/docs/operation/md-raid.md +++ /dev/null @@ -1,249 +0,0 @@ -(raid)= - -# RAID-1 - -A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives -to improve disk speed, store more data, and/or provide fault tolerance. -There are several storage schemes possible in a RAID array, each offering a -different combination of storage, reliability, and/or performance. -The VyOS system supports a “RAID 1” deployment. RAID 1 allows two or more -disks to mirror one another to provide system fault tolerance. In a RAID 1 -solution, every sector of one disk is duplicated onto every sector of all -disks in the array. Provided even one disk in the RAID 1 set is operational, -the system continues to run, even through disk replacement (provided that the -hardware supports in-service replacement of drives). -RAID 1 can be implemented using special hardware or it can be implemented in -software. The VyOS system supports software RAID 1 on two disks. -The VyOS implementation of RAID 1 allows the following: - -- Detection and reporting of disk failure -- The ability to maintain system operation with one failed disk -- The ability to boot the system with one failed disk -- The ability to replace a failed disk and initiate re-mirroring -- The ability to monitor the status of remirroring - -(raid-instalation)= - -## Installation Implications - -The VyOS systems installation utility provides several options for installing -to a RAID 1 set. You can: - -- Use the install system to create the RAID 1 set -- Use the underlying Linux commands to create a RAID 1 set before running the - install system command. -- Use a previously-created RAID 1 set. - -:::{note} -Before a permanent installation, VyOS runs a live installation -::: - -## Configuration - -### Single disk, install as normal - -When the VyOS system is installed, it automatically detects the presence of two -disks not currently part of a RAID array. In these cases, the VyOS -installation utility automatically offers you the option of configuring RAID 1 -mirroring for the drives, with the following prompt. - -```none -Would you like to configure RAID 1 mirroring on them? -``` - -- If you do not want to configure RAID 1 mirroring, enter “No” at the prompt - and continue with installation in the normal way. - -### Empty 2+ Disk - -If VyOS system detect two identical disks that are not currently part of a -RAID-1 set, the VyOS installation utility automatically offers you the option -of configuring RAID 1 mirroring for the drives, with the following prompt. - -```none -Would you like to configure RAID 1 mirroring on them? -``` - -1 - To create a new RAID 1 array, enter “Yes” at the prompt. If the system -detects a filesystem on the partitions being used for RAID 1 it will prompt you -to indicate whether you want to continue creating the RAID 1 array. - -```none -Continue creating array? -``` - -2 - To overwrite the old filesystem, enter “Yes”. - -3 - The system informs you that all data on both drives will be erased. You are -prompted to confirm that you want to continue - -```none -Are you sure you want to do this? -``` - -4 - Enter “Yes” at the prompt to retain the current VyOS configuration once -installation is complete. Enter “No” to delete the current VyOS -configuration. - -```none -Would you like me to save the data on it before I delete it? -``` - -5 - Enter “Yes” at the prompt to retain the current VyOS configuration once -installation is complete. Enter “No” to delete the current VyOS configuration. - -6 - Continue with installation in the normal way. - -### Present RAID-1 - -When the VyOS software on a system with a RAID 1 set already configured, -the installation utility will detect the array and will display the following -prompt: - -```none -Would you like to use this one? -``` - -1 - To break apart the current RAID 1 set, enter “No” at the prompt. The - -installation utility detects that there are two identical disks and offers you -the option of configuring RAID 1 mirroring on them, displaying the following -prompt: - -```none -Would you like to configure RAID 1 mirroring on them? -``` - -2 - To decline to set up a new RAID 1 configuration on the disks, enter “No” -at the prompt. The system prompts you to indicate which partition you would -like the system installed on. - -```none -Which partition should I install the root on? [sda1]: -``` - -3 - Enter the partition where you would like the system installed. The system -then prompts you to indicate whether you want to save the old configuration -data. This represents the current VyOS configuration. - -```none -Would you like me to save the data on it before I delete it? -``` - -4 - Enter “Yes” at the prompt to retain the current VyOS configuration once -installation is complete. Enter “No” to delete the current VyOS configuration. - -5 - Continue with installation in the normal way. - -### Detecting and Replacing a Failed RAID 1 Disk - -The VyOS system automatically detects a disk failure within a RAID 1 set and -reports it to the system console. You can verify the failure by issuing the -show raid command. - -To replace a bad disk within a RAID 1 set, perform the following steps: - -1 - Remove the failed disk from the RAID 1 set by issuing the following -command: - -```{eval-rst} -.. opcmd:: delete raid member - - where RAID-1-device is the name of the RAID 1 device (for example, md0) and - disk-partition is the name of the failed disk partition (for example, sdb2). -``` - -2- Physically remove the failed disk from the system. If the drives are not -hot-swappable, then you must shut down the system before removing the disk. - -3 - Replace the failed drive with a drive of the same size or larger. - -4 - Format the new disk for RAID 1 by issuing the following command: - -```{eval-rst} -.. opcmd:: format disk like - - where disk-device1 is the replacement disk (for example, sdb) and - disk-device2 is the existing healthy disk (for example, sda). -``` - -5-Add the replacement disk to the RAID 1 set by issuing the following command: - -```{eval-rst} -.. opcmd:: add raid member - - where RAID-1-device is the name of the RAID 1 device (for example, md0) and - disk-partition is the name of the replacement disk partition - (for example, sdb2). -``` - -## Operation - -This part introduces how to add a disk partition to a RAID-1 set initiates -mirror synchronization, check and display information. - -```{eval-rst} -.. opcmd:: add raid member - - Use this command to add a member disk partition to the RAID 1 set. Adding a - disk partition to a RAID 1 set initiates mirror synchronization, where all - data on the existing member partition is copied to the new partition. -``` - -```{eval-rst} -.. opcmd:: format disk like - - This command is typically used to prepare a disk to be added to a preexisting - RAID 1 set (of which disk-device2 is already a member). -``` - -```{eval-rst} -.. opcmd:: show raid - - shows output for show raid md0 as sdb1 is being added to the RAID 1 - set and is in the process of being resynchronized. - - .. code-block:: none - - vyos@vyos:~$ show raid md0 - /dev/md0: -       Version : 00.90 - Creation Time : Wed Oct 29 09:19:09 2008 -    Raid Level : raid1 -    Array Size : 1044800 (1020.48 MiB 1069.88 MB) - Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB) -  Raid Devices : 2 - Total Devices : 2 - Preferred Minor : 0 -   Persistence : Superblock is persistent -   Update Time : Wed Oct 29 19:34:23 2008 -         State : active, degraded, recovering - Active Devices : 1 - Working Devices : 2 - Failed Devices : 0 - Spare Devices : 1 - Rebuild Status : 17% complete -          UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f -        Events : 0.103 -   Number   Major   Minor   RaidDevice State -      0       8        1        0      active sync   /dev/sda1 -      2       8       17        1      spare rebuilding   /dev/sdb1 -``` - -```{eval-rst} -.. opcmd:: show raid - - Use this command to display the formatting of a hard disk. - - .. code-block:: none - - vyos@vyos:~$ show disk sda format - Disk /dev/sda: 1073 MB, 1073741824 bytes - 85 heads, 9 sectors/track, 2741 cylinders - Units = cylinders of 765 * 512 = 391680 bytes - Disk identifier: 0x000b7179 -  Device Boot      Start         End      Blocks   Id  System - /dev/sda1               6        2737     1044922+  fd  Linux raid autodetect - - -``` diff --git a/docs/operation/password-recovery.md b/docs/operation/password-recovery.md new file mode 100644 index 00000000..91f3d60f --- /dev/null +++ b/docs/operation/password-recovery.md @@ -0,0 +1,24 @@ +(password-recovery)= + +# Password Recovery + +Using the console, restart the VyOS router. The GRUB menu appears. +Select the relevant option from the GRUB menu and press Enter. +The option must start with “Lost password change.” + +:::{figure} /_static/images/password-recovery-01.png +:width: 600 +::: + +The stand-alone user-password recovery tool starts running and prompts +you to reset the local system user password. + +```console +Do you wish to reset the admin password? (y or n) +y +Which admin account do you want to reset?[vyos] +my_username +Enter my_username password: +Retype my_username password: +System will reboot in 10 seconds... +``` diff --git a/docs/operation/password-recovery.rst b/docs/operation/password-recovery.rst deleted file mode 100755 index 59f4d7c9..00000000 --- a/docs/operation/password-recovery.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _password-recovery: - -################# -Password Recovery -################# - -Using the console, restart the VyOS router. The GRUB menu appears. -Select the relevant option from the GRUB menu and press Enter. -The option must start with “Lost password change.” - -.. figure:: /_static/images/password-recovery-01.png - :width: 600 - -The stand-alone user-password recovery tool starts running and prompts -you to reset the local system user password. - -.. code-block:: console - - Do you wish to reset the admin password? (y or n) - y - Which admin account do you want to reset?[vyos] - my_username - Enter my_username password: - Retype my_username password: - System will reboot in 10 seconds... diff --git a/docs/operation/raid.md b/docs/operation/raid.md new file mode 100644 index 00000000..71a6ad5e --- /dev/null +++ b/docs/operation/raid.md @@ -0,0 +1,249 @@ +(raid)= + +# RAID-1 + +A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives +to improve disk speed, store more data, and/or provide fault tolerance. +There are several storage schemes possible in a RAID array, each offering a +different combination of storage, reliability, and/or performance. +The VyOS system supports a “RAID 1” deployment. RAID 1 allows two or more +disks to mirror one another to provide system fault tolerance. In a RAID 1 +solution, every sector of one disk is duplicated onto every sector of all +disks in the array. Provided even one disk in the RAID 1 set is operational, +the system continues to run, even through disk replacement (provided that the +hardware supports in-service replacement of drives). +RAID 1 can be implemented using special hardware or it can be implemented in +software. The VyOS system supports software RAID 1 on two disks. +The VyOS implementation of RAID 1 allows the following: + +- Detection and reporting of disk failure +- The ability to maintain system operation with one failed disk +- The ability to boot the system with one failed disk +- The ability to replace a failed disk and initiate re-mirroring +- The ability to monitor the status of remirroring + +(raid-instalation)= + +## Installation Implications + +The VyOS systems installation utility provides several options for installing +to a RAID 1 set. You can: + +- Use the install system to create the RAID 1 set +- Use the underlying Linux commands to create a RAID 1 set before running the + install system command. +- Use a previously-created RAID 1 set. + +:::{note} +Before a permanent installation, VyOS runs a live installation +::: + +## Configuration + +### Single disk, install as normal + +When the VyOS system is installed, it automatically detects the presence of two +disks not currently part of a RAID array. In these cases, the VyOS +installation utility automatically offers you the option of configuring RAID 1 +mirroring for the drives, with the following prompt. + +```none +Would you like to configure RAID 1 mirroring on them? +``` + +- If you do not want to configure RAID 1 mirroring, enter “No” at the prompt + and continue with installation in the normal way. + +### Empty 2+ Disk + +If VyOS system detect two identical disks that are not currently part of a +RAID-1 set, the VyOS installation utility automatically offers you the option +of configuring RAID 1 mirroring for the drives, with the following prompt. + +```none +Would you like to configure RAID 1 mirroring on them? +``` + +1 - To create a new RAID 1 array, enter “Yes” at the prompt. If the system +detects a filesystem on the partitions being used for RAID 1 it will prompt you +to indicate whether you want to continue creating the RAID 1 array. + +```none +Continue creating array? +``` + +2 - To overwrite the old filesystem, enter “Yes”. + +3 - The system informs you that all data on both drives will be erased. You are +prompted to confirm that you want to continue + +```none +Are you sure you want to do this? +``` + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS +configuration. + +```none +Would you like me to save the data on it before I delete it? +``` + +5 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +6 - Continue with installation in the normal way. + +### Present RAID-1 + +When the VyOS software on a system with a RAID 1 set already configured, +the installation utility will detect the array and will display the following +prompt: + +```none +Would you like to use this one? +``` + +1 - To break apart the current RAID 1 set, enter “No” at the prompt. The + +installation utility detects that there are two identical disks and offers you +the option of configuring RAID 1 mirroring on them, displaying the following +prompt: + +```none +Would you like to configure RAID 1 mirroring on them? +``` + +2 - To decline to set up a new RAID 1 configuration on the disks, enter “No” +at the prompt. The system prompts you to indicate which partition you would +like the system installed on. + +```none +Which partition should I install the root on? [sda1]: +``` + +3 - Enter the partition where you would like the system installed. The system +then prompts you to indicate whether you want to save the old configuration +data. This represents the current VyOS configuration. + +```none +Would you like me to save the data on it before I delete it? +``` + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +5 - Continue with installation in the normal way. + +### Detecting and Replacing a Failed RAID 1 Disk + +The VyOS system automatically detects a disk failure within a RAID 1 set and +reports it to the system console. You can verify the failure by issuing the +show raid command. + +To replace a bad disk within a RAID 1 set, perform the following steps: + +1 - Remove the failed disk from the RAID 1 set by issuing the following +command: + +```{eval-rst} +.. opcmd:: delete raid member + + where RAID-1-device is the name of the RAID 1 device (for example, md0) and + disk-partition is the name of the failed disk partition (for example, sdb2). +``` + +2- Physically remove the failed disk from the system. If the drives are not +hot-swappable, then you must shut down the system before removing the disk. + +3 - Replace the failed drive with a drive of the same size or larger. + +4 - Format the new disk for RAID 1 by issuing the following command: + +```{eval-rst} +.. opcmd:: format disk like + + where disk-device1 is the replacement disk (for example, sdb) and + disk-device2 is the existing healthy disk (for example, sda). +``` + +5-Add the replacement disk to the RAID 1 set by issuing the following command: + +```{eval-rst} +.. opcmd:: add raid member + + where RAID-1-device is the name of the RAID 1 device (for example, md0) and + disk-partition is the name of the replacement disk partition + (for example, sdb2). +``` + +## Operation + +This part introduces how to add a disk partition to a RAID-1 set initiates +mirror synchronization, check and display information. + +```{eval-rst} +.. opcmd:: add raid member + + Use this command to add a member disk partition to the RAID 1 set. Adding a + disk partition to a RAID 1 set initiates mirror synchronization, where all + data on the existing member partition is copied to the new partition. +``` + +```{eval-rst} +.. opcmd:: format disk like + + This command is typically used to prepare a disk to be added to a preexisting + RAID 1 set (of which disk-device2 is already a member). +``` + +```{eval-rst} +.. opcmd:: show raid + + shows output for show raid md0 as sdb1 is being added to the RAID 1 + set and is in the process of being resynchronized. + + .. code-block:: none + + vyos@vyos:~$ show raid md0 + /dev/md0: +       Version : 00.90 + Creation Time : Wed Oct 29 09:19:09 2008 +    Raid Level : raid1 +    Array Size : 1044800 (1020.48 MiB 1069.88 MB) + Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB) +  Raid Devices : 2 + Total Devices : 2 + Preferred Minor : 0 +   Persistence : Superblock is persistent +   Update Time : Wed Oct 29 19:34:23 2008 +         State : active, degraded, recovering + Active Devices : 1 + Working Devices : 2 + Failed Devices : 0 + Spare Devices : 1 + Rebuild Status : 17% complete +          UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f +        Events : 0.103 +   Number   Major   Minor   RaidDevice State +      0       8        1        0      active sync   /dev/sda1 +      2       8       17        1      spare rebuilding   /dev/sdb1 +``` + +```{eval-rst} +.. opcmd:: show raid + + Use this command to display the formatting of a hard disk. + + .. code-block:: none + + vyos@vyos:~$ show disk sda format + Disk /dev/sda: 1073 MB, 1073741824 bytes + 85 heads, 9 sectors/track, 2741 cylinders + Units = cylinders of 765 * 512 = 391680 bytes + Disk identifier: 0x000b7179 +  Device Boot      Start         End      Blocks   Id  System + /dev/sda1               6        2737     1044922+  fd  Linux raid autodetect + + +``` diff --git a/docs/operation/raid.rst b/docs/operation/raid.rst deleted file mode 100644 index 30407718..00000000 --- a/docs/operation/raid.rst +++ /dev/null @@ -1,245 +0,0 @@ -.. _raid: - -###### -RAID-1 -###### - -A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives -to improve disk speed, store more data, and/or provide fault tolerance. -There are several storage schemes possible in a RAID array, each offering a -different combination of storage, reliability, and/or performance. -The VyOS system supports a “RAID 1” deployment. RAID 1 allows two or more -disks to mirror one another to provide system fault tolerance. In a RAID 1 -solution, every sector of one disk is duplicated onto every sector of all -disks in the array. Provided even one disk in the RAID 1 set is operational, -the system continues to run, even through disk replacement (provided that the -hardware supports in-service replacement of drives). -RAID 1 can be implemented using special hardware or it can be implemented in -software. The VyOS system supports software RAID 1 on two disks. -The VyOS implementation of RAID 1 allows the following: - -* Detection and reporting of disk failure -* The ability to maintain system operation with one failed disk -* The ability to boot the system with one failed disk -* The ability to replace a failed disk and initiate re-mirroring -* The ability to monitor the status of remirroring - -.. _raid_instalation: - -Installation Implications -========================= - -The VyOS systems installation utility provides several options for installing -to a RAID 1 set. You can: - -* Use the install system to create the RAID 1 set -* Use the underlying Linux commands to create a RAID 1 set before running the - install system command. -* Use a previously-created RAID 1 set. - -.. note:: Before a permanent installation, VyOS runs a live installation - -Configuration -============= - -Single disk, install as normal ------------------------------- - -When the VyOS system is installed, it automatically detects the presence of two -disks not currently part of a RAID array. In these cases, the VyOS -installation utility automatically offers you the option of configuring RAID 1 -mirroring for the drives, with the following prompt. - -.. code-block:: none - - Would you like to configure RAID 1 mirroring on them? - -* If you do not want to configure RAID 1 mirroring, enter “No” at the prompt - and continue with installation in the normal way. - -Empty 2+ Disk -------------- - -If VyOS system detect two identical disks that are not currently part of a -RAID-1 set, the VyOS installation utility automatically offers you the option -of configuring RAID 1 mirroring for the drives, with the following prompt. - -.. code-block:: none - - Would you like to configure RAID 1 mirroring on them? - -1 - To create a new RAID 1 array, enter “Yes” at the prompt. If the system -detects a filesystem on the partitions being used for RAID 1 it will prompt you -to indicate whether you want to continue creating the RAID 1 array. - -.. code-block:: none - - Continue creating array? - -2 - To overwrite the old filesystem, enter “Yes”. - -3 - The system informs you that all data on both drives will be erased. You are -prompted to confirm that you want to continue - -.. code-block:: none - - Are you sure you want to do this? - -4 - Enter “Yes” at the prompt to retain the current VyOS configuration once -installation is complete. Enter “No” to delete the current VyOS -configuration. - -.. code-block:: none - - Would you like me to save the data on it before I delete it? - -5 - Enter “Yes” at the prompt to retain the current VyOS configuration once -installation is complete. Enter “No” to delete the current VyOS configuration. - -6 - Continue with installation in the normal way. - - -Present RAID-1 --------------- - -When the VyOS software on a system with a RAID 1 set already configured, -the installation utility will detect the array and will display the following -prompt: - -.. code-block:: none - - Would you like to use this one? - -1 - To break apart the current RAID 1 set, enter “No” at the prompt. The - -installation utility detects that there are two identical disks and offers you -the option of configuring RAID 1 mirroring on them, displaying the following -prompt: - -.. code-block:: none - - Would you like to configure RAID 1 mirroring on them? - -2 - To decline to set up a new RAID 1 configuration on the disks, enter “No” -at the prompt. The system prompts you to indicate which partition you would -like the system installed on. - -.. code-block:: none - - Which partition should I install the root on? [sda1]: - -3 - Enter the partition where you would like the system installed. The system -then prompts you to indicate whether you want to save the old configuration -data. This represents the current VyOS configuration. - -.. code-block:: none - - Would you like me to save the data on it before I delete it? - -4 - Enter “Yes” at the prompt to retain the current VyOS configuration once -installation is complete. Enter “No” to delete the current VyOS configuration. - -5 - Continue with installation in the normal way. - - -Detecting and Replacing a Failed RAID 1 Disk --------------------------------------------- - -The VyOS system automatically detects a disk failure within a RAID 1 set and -reports it to the system console. You can verify the failure by issuing the -show raid command. - -To replace a bad disk within a RAID 1 set, perform the following steps: - -1 - Remove the failed disk from the RAID 1 set by issuing the following -command: - -.. opcmd:: delete raid member - - where RAID-1-device is the name of the RAID 1 device (for example, md0) and - disk-partition is the name of the failed disk partition (for example, sdb2). - -2- Physically remove the failed disk from the system. If the drives are not -hot-swappable, then you must shut down the system before removing the disk. - -3 - Replace the failed drive with a drive of the same size or larger. - -4 - Format the new disk for RAID 1 by issuing the following command: - -.. opcmd:: format disk like - - where disk-device1 is the replacement disk (for example, sdb) and - disk-device2 is the existing healthy disk (for example, sda). - -5-Add the replacement disk to the RAID 1 set by issuing the following command: - -.. opcmd:: add raid member - - where RAID-1-device is the name of the RAID 1 device (for example, md0) and - disk-partition is the name of the replacement disk partition - (for example, sdb2). - -Operation -========= - -This part introduces how to add a disk partition to a RAID-1 set initiates -mirror synchronization, check and display information. - -.. opcmd:: add raid member - - Use this command to add a member disk partition to the RAID 1 set. Adding a - disk partition to a RAID 1 set initiates mirror synchronization, where all - data on the existing member partition is copied to the new partition. - -.. opcmd:: format disk like - - This command is typically used to prepare a disk to be added to a preexisting - RAID 1 set (of which disk-device2 is already a member). - -.. opcmd:: show raid - - shows output for show raid md0 as sdb1 is being added to the RAID 1 - set and is in the process of being resynchronized. - - .. code-block:: none - - vyos@vyos:~$ show raid md0 - /dev/md0: -       Version : 00.90 - Creation Time : Wed Oct 29 09:19:09 2008 -    Raid Level : raid1 -    Array Size : 1044800 (1020.48 MiB 1069.88 MB) - Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB) -  Raid Devices : 2 - Total Devices : 2 - Preferred Minor : 0 -   Persistence : Superblock is persistent -   Update Time : Wed Oct 29 19:34:23 2008 -         State : active, degraded, recovering - Active Devices : 1 - Working Devices : 2 - Failed Devices : 0 - Spare Devices : 1 - Rebuild Status : 17% complete -          UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f -        Events : 0.103 -   Number   Major   Minor   RaidDevice State -      0       8        1        0      active sync   /dev/sda1 -      2       8       17        1      spare rebuilding   /dev/sdb1 - -.. opcmd:: show raid - - Use this command to display the formatting of a hard disk. - - .. code-block:: none - - vyos@vyos:~$ show disk sda format - Disk /dev/sda: 1073 MB, 1073741824 bytes - 85 heads, 9 sectors/track, 2741 cylinders - Units = cylinders of 765 * 512 = 391680 bytes - Disk identifier: 0x000b7179 -  Device Boot      Start         End      Blocks   Id  System - /dev/sda1               6        2737     1044922+  fd  Linux raid autodetect - - - diff --git a/docs/operation/rst-boot-options.rst b/docs/operation/rst-boot-options.rst new file mode 100644 index 00000000..70cdc418 --- /dev/null +++ b/docs/operation/rst-boot-options.rst @@ -0,0 +1,58 @@ +.. _boot-options: + + +############ +Boot Options +############ + +.. warning:: This function may be highly disruptive. + It may cause major service interruption, so make sure you really + need it and verify your input carefully. + + + +VyOS has several kernel command line options to modify the normal boot +process. +To add an option, select the desired image in GRUB menu at load +time, press **e**, edit the first line, and press **Ctrl-x** to boot when +ready. + +.. image:: /_static/images/boot-options.png + :width: 80% + :align: center + + +Specify custom config file +========================== + +Tells the system to use specified file instead of ``/config/config.boot``. +If specified file does not exist or is not readable, fall back to +default config. No additional verification is performed, so make sure +you specify a valid config file. + +.. code-block:: none + + vyos-config=/path/to/file + +To load the *factory default* config, use: + +.. code-block:: none + + vyos-config=/opt/vyatta/etc/config.boot.default + + +Disable specific boot process steps +=================================== + +These options disable some boot steps. Make sure you understand the +:ref:`boot process ` well before using them! + +.. glossary:: + + no-vyos-migrate + Do not perform config migration. + + no-vyos-firewall + Do not initialize default firewall chains, renders any firewall + configuration unusable. + diff --git a/docs/operation/rst-index.rst b/docs/operation/rst-index.rst new file mode 100644 index 00000000..037c9286 --- /dev/null +++ b/docs/operation/rst-index.rst @@ -0,0 +1,12 @@ +############## +Operation Mode +############## + +.. toctree:: + :maxdepth: 1 + :includehidden: + + information + boot-options + password-recovery + raid \ No newline at end of file diff --git a/docs/operation/rst-information.rst b/docs/operation/rst-information.rst new file mode 100644 index 00000000..e32e55b4 --- /dev/null +++ b/docs/operation/rst-information.rst @@ -0,0 +1,155 @@ +:lastproofread: 2021-07-07 + +.. _information: + +*********** +Information +*********** + +VyOS features a rich set of operational level commands to retrieve arbitrary +information about your running system. + +######## +Hardware +######## + +.. _hardware_usb: + +USB +=== + +In the past serial interface have been defined as ttySx and ttyUSBx where x was +an instance number of the serial interface. It was discovered that from system +boot to system boot the mapping of USB based serial interfaces will differ, +depending which driver was loaded first by the operating system. This will +become rather painful if you not only have serial interfaces for a console +server connected but in addition also a serial backed :ref:`wwan-interface`. + +To overcome this issue and the fact that in almost 50% of all cheap USB to +serial converters there is no serial number programmed, the USB to serial +interface is now directly identified by the USB root bridge and bus it connects +to. This somehow mimics the new network interface definitions we see in recent +Linux distributions. + +For additional details you can refer to https://vyos.dev/T2490. + +.. opcmd:: show hardware usb + + Retrieve a tree like representation of all connected USB devices. + + .. note:: If a device is unplugged and re-plugged it will receive a new + Port, Dev, If identification. + + .. code-block:: none + + vyos@vyos:~$ show hardware usb + /: Bus 03.Port 1: Dev 1, Class=root_hub, Driver=ehci-pci/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 4, If 0, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 2, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 3, Class=Vendor Specific Class, Driver=qcserial, 480M + |__ Port 3: Dev 4, If 8, Class=Vendor Specific Class, Driver=qmi_wwan, 480M + /: Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 5000M + /: Bus 01.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/2p, 480M + |__ Port 1: Dev 2, If 0, Class=Vendor Specific Class, Driver=pl2303, 12M + |__ Port 2: Dev 3, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 5, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 5, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 3: Dev 4, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 3: Dev 6, If 0, Class=Hub, Driver=hub/4p, 480M + |__ Port 4: Dev 8, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 8, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 3, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 1, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 2, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + |__ Port 4: Dev 7, If 0, Class=Vendor Specific Class, Driver=ftdi_sio, 480M + + +.. opcmd:: show hardware usb serial + + Retrieve a list and description of all connected USB serial devices. The + device name displayed, e.g. `usb0b2.4p1.0` can be directly used when accessing + the serial console as console-server device. + + .. code-block:: none + + vyos@vyos$ show hardware usb serial + Device Model Vendor + ------ ------ ------ + usb0b1.3p1.0 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.2 MC7710 Sierra Wireless, Inc. + usb0b1.3p1.3 MC7710 Sierra Wireless, Inc. + usb0b1p1.0 USB-Serial_Controller_D Prolific Technology, Inc. + usb0b2.3.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.3.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.0 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.1 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.2 Quad_RS232-HS Future Technology Devices International, Ltd + usb0b2.4p1.3 Quad_RS232-HS Future Technology Devices International, Ltd + +.. _information_version: + +######## +Version +######## + +.. opcmd:: show version + + Return the current running VyOS version and build information. This includes + also the name of the release train which is ``crux`` on VyOS 1.2, ``equuleus`` + on VyOS 1.3 and ``sagitta`` on VyOS 1.4. + + .. code-block:: none + + vyos@vyos:~$ show version + + Version: VyOS 1.4-rolling-202106270801 + Release Train: sagitta + + Built by: autobuild@vyos.net + Built on: Sun 27 Jun 2021 09:50 UTC + Build UUID: ab43e735-edcb-405a-9f51-f16a1b104e52 + Build Commit ID: f544d75eab758f + + Architecture: x86_64 + Boot via: installed image + System type: KVM guest + + Hardware vendor: QEMU + Hardware model: Standard PC (i440FX + PIIX, 1996) + Hardware S/N: + Hardware UUID: Unknown + + Copyright: VyOS maintainers and contributors + +.. opcmd:: show version kernel + + Return version number of the Linux Kernel used in this release. + + .. code-block:: none + + vyos@vyos:~$ show version kernel + 5.10.46-amd64-vyos + +.. opcmd:: show version frr + + Return version number of FRR (Free Range Routing - https://frrouting.org/) + used in this release. This is the routing control plane and a successor to GNU + Zebra and Quagga. + + .. code-block:: none + + vyos@vyos:~$ show version frr + FRRouting 7.5.1-20210625-00-gf07d935a2 (vyos). + Copyright 1996-2005 Kunihiro Ishiguro, et al. + diff --git a/docs/operation/rst-password-recovery.rst b/docs/operation/rst-password-recovery.rst new file mode 100755 index 00000000..59f4d7c9 --- /dev/null +++ b/docs/operation/rst-password-recovery.rst @@ -0,0 +1,25 @@ +.. _password-recovery: + +################# +Password Recovery +################# + +Using the console, restart the VyOS router. The GRUB menu appears. +Select the relevant option from the GRUB menu and press Enter. +The option must start with “Lost password change.” + +.. figure:: /_static/images/password-recovery-01.png + :width: 600 + +The stand-alone user-password recovery tool starts running and prompts +you to reset the local system user password. + +.. code-block:: console + + Do you wish to reset the admin password? (y or n) + y + Which admin account do you want to reset?[vyos] + my_username + Enter my_username password: + Retype my_username password: + System will reboot in 10 seconds... diff --git a/docs/operation/rst-raid.rst b/docs/operation/rst-raid.rst new file mode 100644 index 00000000..30407718 --- /dev/null +++ b/docs/operation/rst-raid.rst @@ -0,0 +1,245 @@ +.. _raid: + +###### +RAID-1 +###### + +A Redundant Array of Independent Disks (RAID) uses two or more hard disk drives +to improve disk speed, store more data, and/or provide fault tolerance. +There are several storage schemes possible in a RAID array, each offering a +different combination of storage, reliability, and/or performance. +The VyOS system supports a “RAID 1” deployment. RAID 1 allows two or more +disks to mirror one another to provide system fault tolerance. In a RAID 1 +solution, every sector of one disk is duplicated onto every sector of all +disks in the array. Provided even one disk in the RAID 1 set is operational, +the system continues to run, even through disk replacement (provided that the +hardware supports in-service replacement of drives). +RAID 1 can be implemented using special hardware or it can be implemented in +software. The VyOS system supports software RAID 1 on two disks. +The VyOS implementation of RAID 1 allows the following: + +* Detection and reporting of disk failure +* The ability to maintain system operation with one failed disk +* The ability to boot the system with one failed disk +* The ability to replace a failed disk and initiate re-mirroring +* The ability to monitor the status of remirroring + +.. _raid_instalation: + +Installation Implications +========================= + +The VyOS systems installation utility provides several options for installing +to a RAID 1 set. You can: + +* Use the install system to create the RAID 1 set +* Use the underlying Linux commands to create a RAID 1 set before running the + install system command. +* Use a previously-created RAID 1 set. + +.. note:: Before a permanent installation, VyOS runs a live installation + +Configuration +============= + +Single disk, install as normal +------------------------------ + +When the VyOS system is installed, it automatically detects the presence of two +disks not currently part of a RAID array. In these cases, the VyOS +installation utility automatically offers you the option of configuring RAID 1 +mirroring for the drives, with the following prompt. + +.. code-block:: none + + Would you like to configure RAID 1 mirroring on them? + +* If you do not want to configure RAID 1 mirroring, enter “No” at the prompt + and continue with installation in the normal way. + +Empty 2+ Disk +------------- + +If VyOS system detect two identical disks that are not currently part of a +RAID-1 set, the VyOS installation utility automatically offers you the option +of configuring RAID 1 mirroring for the drives, with the following prompt. + +.. code-block:: none + + Would you like to configure RAID 1 mirroring on them? + +1 - To create a new RAID 1 array, enter “Yes” at the prompt. If the system +detects a filesystem on the partitions being used for RAID 1 it will prompt you +to indicate whether you want to continue creating the RAID 1 array. + +.. code-block:: none + + Continue creating array? + +2 - To overwrite the old filesystem, enter “Yes”. + +3 - The system informs you that all data on both drives will be erased. You are +prompted to confirm that you want to continue + +.. code-block:: none + + Are you sure you want to do this? + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS +configuration. + +.. code-block:: none + + Would you like me to save the data on it before I delete it? + +5 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +6 - Continue with installation in the normal way. + + +Present RAID-1 +-------------- + +When the VyOS software on a system with a RAID 1 set already configured, +the installation utility will detect the array and will display the following +prompt: + +.. code-block:: none + + Would you like to use this one? + +1 - To break apart the current RAID 1 set, enter “No” at the prompt. The + +installation utility detects that there are two identical disks and offers you +the option of configuring RAID 1 mirroring on them, displaying the following +prompt: + +.. code-block:: none + + Would you like to configure RAID 1 mirroring on them? + +2 - To decline to set up a new RAID 1 configuration on the disks, enter “No” +at the prompt. The system prompts you to indicate which partition you would +like the system installed on. + +.. code-block:: none + + Which partition should I install the root on? [sda1]: + +3 - Enter the partition where you would like the system installed. The system +then prompts you to indicate whether you want to save the old configuration +data. This represents the current VyOS configuration. + +.. code-block:: none + + Would you like me to save the data on it before I delete it? + +4 - Enter “Yes” at the prompt to retain the current VyOS configuration once +installation is complete. Enter “No” to delete the current VyOS configuration. + +5 - Continue with installation in the normal way. + + +Detecting and Replacing a Failed RAID 1 Disk +-------------------------------------------- + +The VyOS system automatically detects a disk failure within a RAID 1 set and +reports it to the system console. You can verify the failure by issuing the +show raid command. + +To replace a bad disk within a RAID 1 set, perform the following steps: + +1 - Remove the failed disk from the RAID 1 set by issuing the following +command: + +.. opcmd:: delete raid member + + where RAID-1-device is the name of the RAID 1 device (for example, md0) and + disk-partition is the name of the failed disk partition (for example, sdb2). + +2- Physically remove the failed disk from the system. If the drives are not +hot-swappable, then you must shut down the system before removing the disk. + +3 - Replace the failed drive with a drive of the same size or larger. + +4 - Format the new disk for RAID 1 by issuing the following command: + +.. opcmd:: format disk like + + where disk-device1 is the replacement disk (for example, sdb) and + disk-device2 is the existing healthy disk (for example, sda). + +5-Add the replacement disk to the RAID 1 set by issuing the following command: + +.. opcmd:: add raid member + + where RAID-1-device is the name of the RAID 1 device (for example, md0) and + disk-partition is the name of the replacement disk partition + (for example, sdb2). + +Operation +========= + +This part introduces how to add a disk partition to a RAID-1 set initiates +mirror synchronization, check and display information. + +.. opcmd:: add raid member + + Use this command to add a member disk partition to the RAID 1 set. Adding a + disk partition to a RAID 1 set initiates mirror synchronization, where all + data on the existing member partition is copied to the new partition. + +.. opcmd:: format disk like + + This command is typically used to prepare a disk to be added to a preexisting + RAID 1 set (of which disk-device2 is already a member). + +.. opcmd:: show raid + + shows output for show raid md0 as sdb1 is being added to the RAID 1 + set and is in the process of being resynchronized. + + .. code-block:: none + + vyos@vyos:~$ show raid md0 + /dev/md0: +       Version : 00.90 + Creation Time : Wed Oct 29 09:19:09 2008 +    Raid Level : raid1 +    Array Size : 1044800 (1020.48 MiB 1069.88 MB) + Used Dev Size : 1044800 (1020.48 MiB 1069.88 MB) +  Raid Devices : 2 + Total Devices : 2 + Preferred Minor : 0 +   Persistence : Superblock is persistent +   Update Time : Wed Oct 29 19:34:23 2008 +         State : active, degraded, recovering + Active Devices : 1 + Working Devices : 2 + Failed Devices : 0 + Spare Devices : 1 + Rebuild Status : 17% complete +          UUID : 981abd77:9f8c8dd8:fdbf4de4:3436c70f +        Events : 0.103 +   Number   Major   Minor   RaidDevice State +      0       8        1        0      active sync   /dev/sda1 +      2       8       17        1      spare rebuilding   /dev/sdb1 + +.. opcmd:: show raid + + Use this command to display the formatting of a hard disk. + + .. code-block:: none + + vyos@vyos:~$ show disk sda format + Disk /dev/sda: 1073 MB, 1073741824 bytes + 85 heads, 9 sectors/track, 2741 cylinders + Units = cylinders of 765 * 512 = 391680 bytes + Disk identifier: 0x000b7179 +  Device Boot      Start         End      Blocks   Id  System + /dev/sda1               6        2737     1044922+  fd  Linux raid autodetect + + + -- cgit v1.2.3