Merge pull request #1884 from vyos/fix/docs-typos-swap-current

docs: fix typos and grammar (ported from #1852 RST → MyST)

6 files changed, 525 insertions, 0 deletions

diff --git a/docs/operation/md-boot-options.md b/docs/operation/md-boot-options.md
new file mode 100644
index 00000000..3c33ee3e
--- /dev/null
+++ b/docs/operation/md-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/md-index.md b/docs/operation/md-index.md
new file mode 100644
index 00000000..b3c02571
--- /dev/null
+++ b/docs/operation/md-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/md-information.md b/docs/operation/md-information.md
new file mode 100644
index 00000000..a6b6de0c
--- /dev/null
+++ b/docs/operation/md-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/md-password-recovery.md b/docs/operation/md-password-recovery.md
new file mode 100644
index 00000000..2f1b93c3
--- /dev/null
+++ b/docs/operation/md-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/md-raid.md b/docs/operation/md-raid.md
new file mode 100644
index 00000000..bd0f9a69
--- /dev/null
+++ b/docs/operation/md-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/md-upgrade-recovery.md b/docs/operation/md-upgrade-recovery.md
new file mode 100644
index 00000000..7c0c428d
--- /dev/null
+++ b/docs/operation/md-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
+```