diff options
Diffstat (limited to 'docs/automation/md-command-scripting.md')
| -rw-r--r-- | docs/automation/md-command-scripting.md | 216 |
1 files changed, 0 insertions, 216 deletions
diff --git a/docs/automation/md-command-scripting.md b/docs/automation/md-command-scripting.md deleted file mode 100644 index c1e1c239..00000000 --- a/docs/automation/md-command-scripting.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -lastproofread: '2026-03-16' ---- - -(command-scripting)= - -# Command scripting - -VyOS supports executing configuration and operational commands non-interactively -from shell scripts. - -To include VyOS-specific functions and aliases, source the -`/opt/vyatta/etc/functions/script-template` file at the beginning of your -script. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -exit -``` - -## Script execute permissions - -Simply placing script files in `/config/scripts/` does not mean the system -can execute them. - -To make your scripts executable, grant them **execute permissions**. Use the -following command: - -```none -chmod +x /config/scripts/script-name.sh -``` - -## Run configuration commands - -In scripts, present configuration commands as in a standard configuration -session. - -For example, to disable a BGP peer during a VRRP transition to the backup -state, use the following syntax: - -```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 - -In scripts, **always** prefix operational commands with `run`. - -```none -#!/bin/vbash -source /opt/vyatta/etc/functions/script-template -run show interfaces -exit -``` - -## Run commands remotely - -You can execute multiple **operational commands** on a remote VyOS system by -passing a script block over SSH. - -```none -ssh 192.0.2.1 'vbash -s' <<EOF -source /opt/vyatta/etc/functions/script-template -run show interfaces -exit -EOF -``` - -Example output: - -```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 use a scripting language other than bash, configure your script to -output the relevant commands, and then source that output into a bash script. - -The following example demonstrates this two-step process: - -```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 -``` - -## Execute configuration scripts - -In Linux, it is common practice to prefix system commands with `sudo`. - -In VyOS, if you prefix a script that modifies the configuration with `sudo` -(see the code snippet below), subsequent manual configuration changes fail with -the `Set failed` error. Recovery requires a system reboot. - -```none -sudo ./myscript.sh # Modifies config -configure -set ... # Any configuration parameter -``` - -To avoid this issue, run scripts under the `vyattacfg` group using the `sg` -command: - -```none -sg vyattacfg -c ./myscript.sh -``` - -To ensure the script is executed under the `vyattacfg` group, safeguard it as -follows: - -```none -if [ "$(id -g -n)" != 'vyattacfg' ] ; then - exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" -fi -``` - -## Executing pre-hooks/post-hooks scripts - -VyOS allows you to run custom scripts **before** and **after** each commit. - -Place your custom scripts in the following default directories: - -```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 run in alphabetical order. Filenames must consist only of ASCII letters -(upper and lowercase), digits (0-9), underscores (\_), and hyphens (-). No other -characters are allowed. - -:::{note} -Custom scripts are executed **without** root privileges. Prefix -specific commands with `sudo` in your script when required. -::: - -The following example shows the output after executing a post-hook script -that runs the `show interfaces` command: - -```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 script on boot - -VyOS runs `/config/scripts/vyos-preconfig-bootup.script` at boot, **before** -the system configuration is applied. - -Use this script to apply **pre-configuration** workarounds for unresolved bugs -or enhancements not yet available in VyOS. - -The default script contains the following: - -```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 script on boot - -VyOS runs `/config/scripts/vyos-postconfig-bootup.script` at boot, **after** -the system configuration is applied. - -Use this script to apply **post-configuration** workarounds for unresolved bugs -or enhancements not yet available in VyOS. - -The default script contains the following: - -```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. -``` - -:::{warning} -For configuration or upgrade management issues, modify this script -only as a last resort. Always try CLI-based solutions first. -::: |