arange http-api and command-scripting

3 files changed, 301 insertions, 1 deletions

diff --git a/docs/automation/command-scripting.rst b/docs/automation/command-scripting.rst
new file mode 100644
index 00000000..7d0ab6c5
--- /dev/null
+++ b/docs/automation/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/automation/http-api.rst b/docs/automation/http-api.rst
new file mode 100644
index 00000000..49f2dbd9
--- /dev/null
+++ b/docs/automation/http-api.rst
@@ -0,0 +1,166 @@
+.. _http-api:
+
+########
+HTTP-API
+########
+
+Enabling HTTP-API
+-----------------
+
+VyOS HTTP API can be enabled through the ``set service https api`` command.
+
+.. code-block:: none
+
+  set service https api debug
+  set service https api keys id MY-HTTP-API-ID key MY-HTTP-API-PLAINTEXT-KEY
+
+The local API process listens on localhost:8080, and nginx exposes it on all
+virtual servers, by default. For the purpose of illustration below, we will
+assume nginx is running at https://192.168.122.127.
+
+One can limit proxying to specific listen addresses/ports/server-names by
+defining a ``service https virtual-host <id>``, and setting ``service https
+api-restrict virtual-host <id>``.
+
+.. code-block:: none
+
+  set service https virtual-host example listen-address 192.168.122.127
+  set service https virtual-host example listen-port 44302
+  set service https virtual-host example server-name example.net
+
+  set service https api-restrict virtual-host example
+
+In this example, nginx will proxy only those requests to
+192.168.122.127:44302 or example.net:44302 (assuming the DNS record is
+viable). Omitting any of listen-address, listen-port, or server-name, will
+leave appropriate defaults in the nginx directive. Multiple instances of
+``service https api-restrict virtual-host`` may be set.
+
+Configuration mode requests
+---------------------------
+
+In our example, we are creating a dummy interface and assigning an address to it:
+
+.. code-block:: none
+
+  curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address"], "value": "203.0.113.76/32"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure
+
+The ``/configure`` endpoint takes a request serialized in JSON. The only HTTP method it uses is POST. Request data is passed in the ``data=`` field and the API key is passed in the ``key=`` field. Key identifiers from the config are purely informational and the application doesn't need to know them, they only appear in the server logs to avoid exposing keys in log files, you only need the key itself.
+
+Since internally there is no distinction between a path and a value, you can omit the value field and include the value in the path like it's done in the shell commands:
+
+.. code-block:: none
+
+  curl -k -X POST -F data='{"op": "set", "path": ["interfaces", "dummy", "dum10", "address", "203.0.113.99/32"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/configure
+
+Separate value field make the semantics more clear though, and also makes it easier to create a command template once and update it with different values as needed.
+
+You can pass the ``set``, ``delete`` or ``comment`` command to it. The API will push the command to the session and commit.
+
+To retrieve a value:
+
+.. code-block:: none
+
+  curl -k -X POST -F data='{"op": "returnValue", "path": ["interfaces", "dummy", "dum1", "address"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve
+
+Use ``returnValues`` for multi-valued nodes.
+
+
+Show config
+"""""""""""
+
+To retrieve the full config under a path:
+
+.. code-block:: none
+
+  # curl -k -X POST -F data='{"op": "showConfig", "path": ["interfaces", "dummy"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve
+
+It will return:
+
+.. code-block:: none
+
+  {"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null}
+
+Passing an empty path will return the full config:
+
+.. code-block:: none
+
+  # curl -k -X POST -F data='{"op": "showConfig", "path": []}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/retrieve
+
+
+Configuration management requests
+---------------------------------
+
+When saving or loading a configuration, the endpoint is ``/config-file`` and you can pass the ``save`` or ``load`` command.
+
+If you don't specify the file when saving, it saves to ``/config/config.boot``. Here's an example:
+
+.. code-block:: none
+
+  # curl -k -X POST -F key=MY-HTTP-API-PLAINTEXT-KEY -Fdata='{"op": "save", "file": "/config/config.boot"}' https://192.168.122.127/config-file
+
+Image management requests
+-------------------------
+
+One may ``add`` or ``delete`` a system image using the endpoint ``/image``. Here are the respective examples:
+
+``add`` from ``url``. Here we use the URL of the latest rolling release:
+
+.. code-block:: none
+
+  # curl -k -X POST -F data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image
+
+``delete`` by image ``name``. For example:
+
+.. code-block:: none
+
+  # curl -k -X POST -F data='{"op": "delete", "name": "1.3-rolling-202006070117"}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/image
+
+To list the available system images by name, one may use the operational mode request ``show`` discussed in the next section; in this setting it would be:
+
+.. code-block:: none
+
+  # curl -k -X POST -F data='{"op": "show", "path": ["system", "image"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show
+
+Operational mode requests
+-------------------------
+
+It is possible to run ``show`` and ``generate`` commands:
+
+
+Request:
+
+.. code-block:: none
+
+  curl -k -X POST -F data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/generate
+
+Response:
+
+.. code-block:: none
+
+  {"success": true, "data": "", "error": null}
+
+Request:
+
+.. code-block:: none
+
+  curl -k -X POST -F data='{"op": "show", "path": ["wireguard", "keypairs", "pubkey", "default"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show
+
+Response:
+
+.. code-block:: none
+
+  {"success": true, "data": "<some pubkey>=\n", "error": null}
+
+Request:
+
+.. code-block:: none
+
+  curl -k -X POST -F data='{"op": "show", "path": ["ip", "route"]}' -F key=MY-HTTP-API-PLAINTEXT-KEY https://192.168.122.127/show
+
+Response:
+
+.. code-block:: none
+
+  {"success": true, "data": "Codes: K - kernel route, C - connected, S - static, R - RIP,\n       O - OSPF, I - IS-IS, B - BGP, E - EIGRP, N - NHRP,\n       T - Table, v - VNC, V - VNC-Direct, A - Babel, D - SHARP,\n       F - PBR, f - OpenFabric,\n       > - selected route, * - FIB route, q - queued route, r - rejected route\n\nS>* 0.0.0.0/0 [210/0] via 192.168.100.1, eth0, 01:41:05\nC>* 192.168.0.0/24 is directly connected, eth1, 01:41:09\nC>* 192.168.100.0/24 is directly connected, eth0, 01:41:05\nC>* 203.0.113.76/32 is directly connected, dum1, 01:38:40\n", "error": null}
+
diff --git a/docs/automation/index.rst b/docs/automation/index.rst
index a3df9bc0..1f2b40b1 100644
--- a/docs/automation/index.rst
+++ b/docs/automation/index.rst
@@ -6,4 +6,11 @@ VyOS Automation
   * Ansible
   * Saltstack
   * HTTP-API
-  * startup scripts
\ No newline at end of file
+  * startup scripts
+
+
+.. toctree::
+   :maxdepth: 1
+
+   command-scripting
+   http-api
\ No newline at end of file