diff options
Diffstat (limited to 'docs/operation')
| -rw-r--r-- | docs/operation/md-boot-options.md | 56 | ||||
| -rw-r--r-- | docs/operation/md-index.md | 12 | ||||
| -rw-r--r-- | docs/operation/md-information.md | 163 | ||||
| -rw-r--r-- | docs/operation/md-password-recovery.md | 46 | ||||
| -rw-r--r-- | docs/operation/md-raid.md | 236 | ||||
| -rw-r--r-- | docs/operation/md-upgrade-recovery.md | 70 |
6 files changed, 0 insertions, 583 deletions
diff --git a/docs/operation/md-boot-options.md b/docs/operation/md-boot-options.md deleted file mode 100644 index d42f6b2e..00000000 --- a/docs/operation/md-boot-options.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -lastproofread: '2025-11-14' ---- - -(boot-options)= - -# Boot Options - -:::{warning} -This function can disrupt services. -Run it only when necessary, and verify all input values before proceeding. -::: - -VyOS provides several kernel command-line options to modify the normal boot -process. -To add an option, select the desired image in the GRUB menu at load time. -Type **e** to edit the first line, then type **Ctrl+X** to boot. - -```{image} /_static/images/boot-options.webp -:align: center -:width: 80% -``` - -## Specify custom config file - -You can use a configuration file instead of the default `/config/config.boot` -file. -If the specified file doesn't exist or isn't readable, the system uses the -default configuration file. -No additional verification is performed, so specify a valid configuration file. - -```none -vyos-config=/path/to/file -``` - -To load the *factory default* configuration, use: - -```none -vyos-config=/opt/vyatta/etc/config.boot.default -``` - -## Disable specific boot process steps - -These options disable certain steps in the boot process. Understand the -{ref}`boot process <boot-steps>` 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 b3c02571..00000000 --- a/docs/operation/md-index.md +++ /dev/null @@ -1,12 +0,0 @@ -# Operation Mode - -```{toctree} -:includehidden: true -:maxdepth: 1 - -information -boot-options -upgrade-recovery -password-recovery -raid -``` diff --git a/docs/operation/md-information.md b/docs/operation/md-information.md deleted file mode 100644 index 1ff0748e..00000000 --- a/docs/operation/md-information.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -lastproofread: '2025-11-19' ---- - -(information)= - -# System Information - -VyOS features a rich set of operational level commands to retrieve arbitrary -information about your running system. For more information on the VyOS command -line interface (CLI), see {ref}`cli`. - -# Hardware - -(hardware_usb)= - -## USB - -In the past, serial interfaces were defined as `ttySx` and `ttyUSBx` where -`x` was the instance number. However, the mapping of USB-based -serial interfaces can change from one system boot to another, depending on -which driver the operating system loads first. -This inconsistency can be problematic when you -use multiple serial interfaces. -For example, both console-server connections and a serial-backed -{ref}`wwan-interface`. - -To address this issue, and because many low-cost USB-to-serial converters -do not have a programmed serial number, VyOS now identifies USB-to-serial -interfaces by the USB root bridge and the bus they connect to. -This approach is similar to the network interface naming conventions used in -recent Linux distributions. - -```{eval-rst} -.. opcmd:: show hardware usb - - Retrieve a tree-like representation of all connected USB devices. - - .. note:: If a device is unplugged and plugged in again, it is assigned a new - ``Port``, ``Dev``, and ``If``. -``` - -% -% .. 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, (for example ``usb0b2.4p1.0``), can be used - directly 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 currently running VyOS version and build information. This - includes the name of the release train, e.g., ``sagitta`` on VyOS 1.4, - and ``circinus`` on VyOS 1.5. - - .. 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 the version number of the currently running Linux kernel. - - .. code-block:: none - - vyos@vyos:~$ show version kernel - 5.10.46-amd64-vyos -``` - -```{eval-rst} -.. opcmd:: show version frr - - Return the 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 2f1b93c3..00000000 --- a/docs/operation/md-password-recovery.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -lastproofread: '2026-02-04' ---- - -(password-recovery)= - -# Password Recovery - -Restart VyOS from the console. The GRUB menu appears. -Select **Boot options**. - -:::{figure} /_static/images/reset-password-step-1.webp -:width: 600 -::: - -Next, select **Select boot mode**. - -:::{figure} /_static/images/reset-password-step-2.webp -:width: 600 -::: - -Select **Password reset**. - -:::{figure} /_static/images/reset-password-step-3.webp -:width: 600 -::: - -Boot the desired VyOS version. - -:::{figure} /_static/images/reset-password-step-4.webp -:width: 600 -::: - -The standalone user password recovery tool runs and prompts you to reset the -local system user password. VyOS automatically reboots after you reset your -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 bd0f9a69..00000000 --- a/docs/operation/md-raid.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -lastproofread: '2025-11-20' ---- - -(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 performance. -VyOS supports **RAID 1** deployments. RAID 1 uses two or more -disks that mirror one another to provide system fault tolerance. In a RAID 1 -configuration, every sector on one disk is duplicated on 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. VyOS supports software RAID 1 on two disks. -The VyOS implementation of RAID 1 features the following: - -- Detection and reporting of disk failure. -- Maintain system operation with one failed disk. -- Boot the system with one failed disk. -- Replace a failed disk and initiate re-mirroring. -- Monitor the status of re-mirroring. - -(raid-installation)= - -## Installation implications - -The VyOS 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 built-in 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 - -### Standard installation on a single disk - -VyOS automatically detects the presence of two or more -disks that are not currently part of a RAID array when installed. The VyOS -installation utility automatically offers you the option to configure RAID 1 -mirroring for eligible 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. - -### Empty 2+ disk - -If VyOS detects two identical disks that are not currently part of a -RAID 1 set, the VyOS installation utility automatically offers the option -to configure 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 VyOS -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. -Confirm 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. -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. -Enter **No** to delete the current VyOS configuration. - -6. Continue installing VyOS. - -### Preexisting RAID 1 configuration - -When VyOS detects a previously configured RAID 1 set, -the installation utility displays the following prompt: - -```none -Would you like to use this one? -``` - -1\. To break up 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 with 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. VyOS 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 installing VyOS. - -### Detecting and replacing a failed RAID 1 disk - -VyOS system detects disk failures within a RAID 1 set and -reports them to the system console. You can verify the failure by running the -`show raid` command. - -To replace a bad disk within a RAID 1 set: - -1. Remove the failed disk from the RAID 1 set: - - ```{opcmd} delete raid \<RAID‐1‐device\> member \<disk‐partition\> - ``` - 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 running the following command: - - ```{opcmd} format disk \<disk‐device1\> like \<disk‐device2\> - ``` - 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 running the following command: - - ```{opcmd} add raid \<RAID‐1‐device\> member \<disk‐partition\> - ``` - 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 - -Learn how to add a disk partition to a RAID 1 set, initiate -mirror synchronization, and check and display information. - -```{opcmd} add raid \<RAID‐1‐device\> member \<disk‐partition\> - - 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 \<disk‐device1\> like \<disk‐device2\> - -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 \<RAID‐1‐device\> - -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 disk sda format - -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 -::: -```
\ No newline at end of file diff --git a/docs/operation/md-upgrade-recovery.md b/docs/operation/md-upgrade-recovery.md deleted file mode 100644 index 7c0c428d..00000000 --- a/docs/operation/md-upgrade-recovery.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -lastproofread: '2025-11-20' ---- - -(upgrade-recovery)= - -# Recovery after Failed Upgrades - -Use **VyOS upgrade recovery** to restore the system to the last working -version after a failed upgrade. - -- {ref}`Configuration: <configuration>` How to enable upgrade recovery -- {ref}`How it works: <how-it-works>` Overview of the recovery process -- {ref}`Cancelling recovery: <cancelling-recovery>` Overview of the recovery - process - -(configuration)= - -## Configuration - -:::{warning} -Upgrade recovery is disabled by default. To use it, -**enable it first**. -::: - -To enable upgrade recovery, run the following command: - -```{cfgcmd} set system option reboot-on-upgrade-failure [timeout \<min\>] -``` - -- `timeout <min>:` The time in minutes (5 - 30) to cancel upgrade - recovery before VyOS reboots. - See {ref}`Cancelling Recovery <cancelling-recovery>`. -(how-it-works)= - -## How it works - -After a VyOS upgrade, the system monitors the boot process. Upon detecting a -boot failure, VyOS initiates a revert to the last working version and displays -the following warning: - -```none -Booting failed, reverting to previous image -Automatic reboot in xx minutes -Use "reboot cancel" to cancel -``` - -If no action is taken, the reboot happens automatically after the configured -timeout. Upon successful recovery and reboot, the following message appears: - -```none -WARNING: Image update to "VyOS 1.5.xxxx" failed -Please check the logs: -/usr/lib/live/mount/persistence/boot/NAME/rw/var/log -Message is cleared on next reboot! -``` - -(cancelling-recovery)= - -## Cancelling recovery - -Upon detecting a boot failure, you have the predefined timeout to cancel -upgrade recovery. This is useful if you want to troubleshoot the faulty VyOS -version on your own. - -To cancel upgrade recovery, run the following command: - -```none -reboot cancel -``` |