From b8b3044d3c3515d91de0f44785bfd965174867df Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
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-<stem>.md to docs/**/<stem>.md (drop md- prefix) for
  all 210 stems previously listed in docs/_swap.txt
- Rename docs/**/<stem>.rst to docs/**/rst-<stem>.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/automation/command-scripting.md | 207 +++++++++++++++++++++++++++++++++++
 1 file changed, 207 insertions(+)
 create mode 100644 docs/automation/command-scripting.md

(limited to 'docs/automation/command-scripting.md')

diff --git a/docs/automation/command-scripting.md b/docs/automation/command-scripting.md
new file mode 100644
index 00000000..941ba744
--- /dev/null
+++ b/docs/automation/command-scripting.md
@@ -0,0 +1,207 @@
+---
+lastproofread: '2023-01-16'
+---
+
+(command-scripting)=
+
+# Command Scripting
+
+VyOS supports executing configuration and operational commands non-interactively
+from shell scripts.
+
+To include VyOS specific functions and aliases you need to `source
+/opt/vyatta/etc/functions/script-template` files at the top of your script.
+
+```none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+exit
+```
+
+## Run configuration commands
+
+Configuration commands are executed just like from a normal config session. For
+example, if you want to disable a BGP peer on VRRP transition to backup:
+
+```none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+configure
+set protocols bgp system-as 65536
+set protocols bgp neighbor 192.168.2.1 shutdown
+commit
+exit
+```
+
+## Run operational commands
+
+Unlike a normal configuration session, all operational commands must be
+prepended with `run`, even if you haven't created a session with configure.
+
+```none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+run show interfaces
+exit
+```
+
+## Run commands remotely
+
+Sometimes you simply want to execute a bunch of op-mode commands via SSH on
+a remote VyOS system.
+
+```none
+ssh 192.0.2.1 'vbash -s' <<EOF
+source /opt/vyatta/etc/functions/script-template
+run show interfaces
+exit
+EOF
+```
+
+Will return:
+
+```none
+Welcome to VyOS
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+eth0             192.0.2.1/24                      u/u
+lo               127.0.0.1/8                       u/u
+                ::1/128
+```
+
+## Other script languages
+
+If you want to script the configs in a language other than bash you can have
+your script output commands and then source them in a bash script.
+
+Here is a simple example:
+
+```python
+#!/usr/bin/env python3
+print("delete firewall group address-group somehosts")
+print("set firewall group address-group somehosts address '192.0.2.3'")
+print("set firewall group address-group somehosts address '203.0.113.55'")
+```
+
+```none
+#!/bin/vbash
+source /opt/vyatta/etc/functions/script-template
+configure
+source < /config/scripts/setfirewallgroup.py
+commit
+```
+
+## Executing Configuration Scripts
+
+There is a pitfall when working with configuration scripts. It is tempting to
+call configuration scripts with "sudo" (i.e., temporary root permissions),
+because that's the common way on most Linux platforms to call system commands.
+
+On VyOS this will cause the following problem: After modifying the configuration
+via script like this once, it is not possible to manually modify the config
+anymore:
+
+```none
+sudo ./myscript.sh # Modifies config
+configure
+set ... # Any configuration parameter
+```
+
+This will result in the following error message: `Set failed` If this happens,
+a reboot is required to be able to edit the config manually again.
+
+To avoid these problems, the proper way is to call a script with the
+`vyattacfg` group, e.g., by using the `sg` (switch group) command:
+
+```none
+sg vyattacfg -c ./myscript.sh
+```
+
+To make sure that a script is not accidentally called without the `vyattacfg`
+group, the script can be safeguarded like this:
+
+```none
+if [ "$(id -g -n)" != 'vyattacfg' ] ; then
+    exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@"
+fi
+```
+
+## Executing pre-hooks/post-hooks Scripts
+
+VyOS has the ability to run custom scripts before and after each commit
+
+The default directories where your custom Scripts should be located are:
+
+```none
+/config/scripts/commit/pre-hooks.d   - Directory with scripts that run before
+                                       each commit.
+
+/config/scripts/commit/post-hooks.d  - Directory with scripts that run after
+                                       each commit.
+```
+
+Scripts are run in alphabetical order. Their names must consist entirely of
+ASCII upper- and lower-case letters,ASCII digits, ASCII underscores, and
+ASCII minus-hyphens.No other characters are allowed.
+
+:::{note}
+Custom scripts are not executed with root privileges
+(Use sudo inside if this is necessary).
+:::
+
+A simple example is shown below, where the ops command executed in
+the post-hook script is "show interfaces".
+
+```none
+vyos@vyos# set interfaces ethernet eth1  address 192.0.2.3/24
+vyos@vyos# commit
+Codes: S - State, L - Link, u - Up, D - Down, A - Admin Down
+Interface        IP Address                        S/L  Description
+---------        ----------                        ---  -----------
+eth0             198.51.100.10/24                  u/u
+eth1             192.0.2.3/24                      u/u
+eth2             -                                 u/u
+eth3             -                                 u/u
+lo               203.0.113.5/24                    u/u
+```
+
+## Preconfig on boot
+
+The `/config/scripts/vyos-preconfig-bootup.script` script is called on boot
+before the VyOS configuration during boot process.
+
+Any modifications were done to work around unfixed bugs and implement
+enhancements that are not complete in the VyOS system can be placed here.
+
+The default file looks like this:
+
+```none
+#!/bin/sh
+# This script is executed at boot time before VyOS configuration is applied.
+# Any modifications required to work around unfixed bugs or use
+# services not available through the VyOS CLI system can be placed here.
+```
+
+## Postconfig on boot
+
+The `/config/scripts/vyos-postconfig-bootup.script` script is called on boot
+after the VyOS configuration is fully applied.
+
+Any modifications were done to work around unfixed bugs and implement
+enhancements that are not complete in the VyOS system can be placed here.
+
+The default file looks like this:
+
+```none
+#!/bin/sh
+# This script is executed at boot time after VyOS configuration is fully
+# applied. Any modifications required to work around unfixed bugs or use
+# services not available through the VyOS CLI system can be placed here.
+```
+
+:::{hint}
+For configuration/upgrade management issues, modification of this
+script should be the last option. Always try to find solutions based on CLI
+commands first.
+:::
-- 
cgit v1.2.3