From fdf235905c0fb13591078e9b0b065dacfdd801fc Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Wed, 3 Apr 2019 21:58:58 +0200
Subject: add commandscripting docu

---
 docs/commandscripting.rst | 51 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)
 create mode 100644 docs/commandscripting.rst

(limited to 'docs/commandscripting.rst')

diff --git a/docs/commandscripting.rst b/docs/commandscripting.rst
new file mode 100644
index 00000000..918a51a6
--- /dev/null
+++ b/docs/commandscripting.rst
@@ -0,0 +1,51 @@
+.. _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:: sh
+
+  #!/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:: sh
+
+  #!/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:: sh
+
+  #!/bin/vbash
+  source /opt/vyatta/etc/functions/script-template
+
+  run show interfaces
+
+  exit
\ No newline at end of file
-- 
cgit v1.2.3


From 7dcc6966b449c8d1e370809b8015b54fa2dde96b Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Thu, 4 Apr 2019 21:25:45 +0200
Subject: improve commandscripting docu

---
 docs/commandscripting.rst | 58 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

(limited to 'docs/commandscripting.rst')

diff --git a/docs/commandscripting.rst b/docs/commandscripting.rst
index 918a51a6..273f3d4b 100644
--- a/docs/commandscripting.rst
+++ b/docs/commandscripting.rst
@@ -48,4 +48,60 @@ Unlike a normal configuration sessions, all operational commands must be prepend
 
   run show interfaces
 
-  exit
\ No newline at end of file
+  exit
+
+Ohter 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 '1.1.1.1'"
+  print "set firewall group address-group somehosts address '1.1.1.2'"
+
+
+.. code-block:: sh
+
+  #!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:: sh
+
+  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:: sh
+
+  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:: sh
+
+  if [ "$(id -g -n)" != 'vyattacfg' ] ; then
+      exec sg vyattacfg -c "/bin/vbash $(readlink -f $0) $@"
+  fi
\ No newline at end of file
-- 
cgit v1.2.3


From ba3e5d2bacef898cc855026b0ef65e108545510e Mon Sep 17 00:00:00 2001
From: rebortg <github@ghlr.de>
Date: Thu, 4 Apr 2019 21:31:02 +0200
Subject: fix typo

---
 docs/commandscripting.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

(limited to 'docs/commandscripting.rst')

diff --git a/docs/commandscripting.rst b/docs/commandscripting.rst
index 273f3d4b..cfdbae44 100644
--- a/docs/commandscripting.rst
+++ b/docs/commandscripting.rst
@@ -50,7 +50,7 @@ Unlike a normal configuration sessions, all operational commands must be prepend
 
   exit
 
-Ohter script language
+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.
-- 
cgit v1.2.3