From 695a88c7e40719e4befe2b3a5559822fe3043b8d Mon Sep 17 00:00:00 2001 From: Christian Poessinger Date: Fri, 20 Dec 2019 19:46:03 +0100 Subject: task-scheduler: rewrite with new cfgcmd syntax --- docs/command-scripting.rst | 127 +++++++++++++++++++++++++++++++++++++++++ docs/commandscripting.rst | 127 ----------------------------------------- docs/index.rst | 2 +- docs/system/serial-console.rst | 4 +- docs/system/task-scheduler.rst | 70 ++++++++--------------- 5 files changed, 155 insertions(+), 175 deletions(-) create mode 100644 docs/command-scripting.rst delete mode 100644 docs/commandscripting.rst (limited to 'docs') diff --git a/docs/command-scripting.rst b/docs/command-scripting.rst new file mode 100644 index 00000000..7d0ab6c5 --- /dev/null +++ b/docs/command-scripting.rst @@ -0,0 +1,127 @@ +.. _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. + +.. code-block:: 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: + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + configure + set protocols bgp 65536 neighbor 192.168.2.1 shutdown + commit + exit + +Run operational commands +------------------------ + +Unlike a normal configuration sessions, all operational commands must be +prepended with ``run``, even if you haven't created a session with configure. + +.. code-block:: none + + #!/bin/vbash + source /opt/vyatta/etc/functions/script-template + run show interfaces + exit + +Other script language +--------------------- + +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: + +.. code-block:: python + + #!/usr/bin/env python + 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 + + +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: + +.. code-block:: 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: + +.. code-block:: 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: + +.. code-block:: none + + if [ "$(id -g -n)" != 'vyattacfg' ] ; then + exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" + fi + +Postconfig on boot +------------------ + +The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot +after the VyOS configuration is fully applied. + +Any modifications done to work around unfixed bugs and implement enhancements +which are not complete in the VyOS system can be placed here. + +The default file looks like this: + +.. 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. + +.. 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. diff --git a/docs/commandscripting.rst b/docs/commandscripting.rst deleted file mode 100644 index 3c437fb0..00000000 --- a/docs/commandscripting.rst +++ /dev/null @@ -1,127 +0,0 @@ -.. _commandscripting: - -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. - -.. code-block:: 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: - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - configure - set protocols bgp 65536 neighbor 192.168.2.1 shutdown - commit - exit - -Run operational commands ------------------------- - -Unlike a normal configuration sessions, all operational commands must be -prepended with ``run``, even if you haven't created a session with configure. - -.. code-block:: none - - #!/bin/vbash - source /opt/vyatta/etc/functions/script-template - run show interfaces - exit - -Other script language ---------------------- - -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: - -.. code-block:: python - - #!/usr/bin/env python - 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 - - -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: - -.. code-block:: 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: - -.. code-block:: 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: - -.. code-block:: none - - if [ "$(id -g -n)" != 'vyattacfg' ] ; then - exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@" - fi - -Postconfig on boot ------------------- - -The ``/config/scripts/vyos-postconfig-bootup.script`` script is called on boot -after the VyOS configuration is fully applied. - -Any modifications done to work around unfixed bugs and implement enhancements -which are not complete in the VyOS system can be placed here. - -The default file looks like this: - -.. 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. - -.. 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. diff --git a/docs/index.rst b/docs/index.rst index 14ba9e71..4d25bb09 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -42,7 +42,7 @@ VyOS User Guide high-availability vpn/index load-balancing - commandscripting + command-scripting troubleshooting diff --git a/docs/system/serial-console.rst b/docs/system/serial-console.rst index 53322f53..cd27fa21 100644 --- a/docs/system/serial-console.rst +++ b/docs/system/serial-console.rst @@ -38,9 +38,9 @@ Major upgrades to the installed distribution may also require console access. * ``57600`` - 57,600 bps * ``115200`` - 115,200 bps (default for serial console) -############## +############### Network Console -############## +############### TBD. diff --git a/docs/system/task-scheduler.rst b/docs/system/task-scheduler.rst index 7fe49988..869a0600 100644 --- a/docs/system/task-scheduler.rst +++ b/docs/system/task-scheduler.rst @@ -1,60 +1,40 @@ .. _task-scheduler: +############## +Task Scheduler +############## -Task scheduler --------------- +The task scheduler allows you to execute tasks on a given schedule. It makes +use of UNIX cron_. -| Task scheduler — allows scheduled task execution. Note that scripts excecuted this way are executed as root user - this may be dangerous. -| Together with :ref:`commandscripting` this can be used for automating configuration. +.. note:: All scripts excecuted this way are executed as root user - this may + be dangerous. Together with :ref:`command-scripting` this can be used for + automating (re-)configuration. -.. code-block:: none +.. cfgcmd:: set system task-scheduler task '' interval '' - system - task-scheduler - task - cron-spec - executable - arguments - path - interval - [mhd] + Specify the time interval when `` should be executed. The interval + is specified as number with one of the following suffixes: -Interval -******** + * ``none`` - Execution interval in minutes + * ``m`` - Execution interval in minutes + * ``h`` - Execution interval in hours + * ``d`` - Execution interval in days -You are able to set the time as an time interval. + .. note:: If suffix is omitted, minutes are implied. -.. code-block:: none +.. cfgcmd:: set system task-scheduler task '' crontab-spec '' - set system task-scheduler task interval + Set execution time in common cron_ time format. A cron `` of + ``30 */6 * * *`` would execute the `` at minute 30 past every 6th hour. -Sets the task to execute every N minutes, hours, or days. Suffixes: +.. cfgcmd:: set system task-scheduler task '' executable path '' - * m — minutes - * h — hours - * d — days + Specify absolute `` to script which will be run when `` is + executed. -If suffix is omitted, minutes are implied. +.. cfgcmd:: set system task-scheduler task '' executable arguments '' -Or set the execution time in common cron time. + Arguments which will be passed to the executable. -.. code-block:: none - - set system task-scheduler task TEST crontab-spec "* * * 1 *" - -Example -******* - -.. code-block:: none - - system - task-scheduler - task mytask - interval 2h - executable - path /config/scripts/mytask - arguments "arg1 arg2 arg3" - task anothertask - cron-spec "* * * 1 *" - executable - path /config/scripts/anothertask \ No newline at end of file +.. _cron: https://en.wikipedia.org/wiki/Cron -- cgit v1.2.3