diff options
Diffstat (limited to 'docs/operation')
| -rw-r--r-- | docs/operation/boot-options.md | 55 | ||||
| -rw-r--r-- | docs/operation/index.md | 12 | ||||
| -rw-r--r-- | docs/operation/information.md | 106 | ||||
| -rw-r--r-- | docs/operation/password-recovery.md | 46 | ||||
| -rw-r--r-- | docs/operation/raid.md | 236 | ||||
| -rw-r--r-- | docs/operation/upgrade-recovery.md | 70 |
6 files changed, 525 insertions, 0 deletions
diff --git a/docs/operation/boot-options.md b/docs/operation/boot-options.md new file mode 100644 index 00000000..3c33ee3e --- /dev/null +++ b/docs/operation/boot-options.md @@ -0,0 +1,55 @@ +--- +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. + +:::{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..b3c02571 --- /dev/null +++ b/docs/operation/index.md @@ -0,0 +1,12 @@ +# Operation Mode + +```{toctree} +:includehidden: true +:maxdepth: 1 + +information +boot-options +upgrade-recovery +password-recovery +raid +``` diff --git a/docs/operation/information.md b/docs/operation/information.md new file mode 100644 index 00000000..a6b6de0c --- /dev/null +++ b/docs/operation/information.md @@ -0,0 +1,106 @@ +--- +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. + +```{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``. +::: +``` + +```{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. +``` + +(information-version)= + +# Version + +```{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 +::: +``` + +```{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 +::: +``` + +```{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/password-recovery.md b/docs/operation/password-recovery.md new file mode 100644 index 00000000..2f1b93c3 --- /dev/null +++ b/docs/operation/password-recovery.md @@ -0,0 +1,46 @@ +--- +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/raid.md b/docs/operation/raid.md new file mode 100644 index 00000000..bd0f9a69 --- /dev/null +++ b/docs/operation/raid.md @@ -0,0 +1,236 @@ +--- +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/upgrade-recovery.md b/docs/operation/upgrade-recovery.md new file mode 100644 index 00000000..7c0c428d --- /dev/null +++ b/docs/operation/upgrade-recovery.md @@ -0,0 +1,70 @@ +--- +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 +``` |