diff options
Diffstat (limited to 'docs/automation/command-scripting.rst')
| -rw-r--r-- | docs/automation/command-scripting.rst | 224 |
1 files changed, 0 insertions, 224 deletions
diff --git a/docs/automation/command-scripting.rst b/docs/automation/command-scripting.rst deleted file mode 100644 index 91086b42..00000000 --- a/docs/automation/command-scripting.rst +++ /dev/null @@ -1,224 +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. - -.. 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. |