diff options
Diffstat (limited to 'docs/automation/rst-command-scripting.rst')
| -rw-r--r-- | docs/automation/rst-command-scripting.rst | 224 |
1 files changed, 224 insertions, 0 deletions
diff --git a/docs/automation/rst-command-scripting.rst b/docs/automation/rst-command-scripting.rst new file mode 100644 index 00000000..91086b42 --- /dev/null +++ b/docs/automation/rst-command-scripting.rst @@ -0,0 +1,224 @@ +: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. + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: 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``. + +.. code-block:: 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. + +.. code-block:: none + + ssh 192.0.2.1 'vbash -s' <<EOF + source /opt/vyatta/etc/functions/script-template + run show interfaces + exit + EOF + +Example output: + +.. code-block:: 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: + +.. code-block:: 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'") + + +.. code-block:: 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. + +.. code-block:: 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: + +.. code-block:: none + + sg vyattacfg -c ./myscript.sh + +To ensure the script is executed under the ``vyattacfg`` group, safeguard it as +follows: + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: 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. |