diff options
Diffstat (limited to 'docs/automation')
| -rw-r--r-- | docs/automation/index.rst | 4 | ||||
| -rw-r--r-- | docs/automation/vyos-api.rst | 317 |
2 files changed, 319 insertions, 2 deletions
diff --git a/docs/automation/index.rst b/docs/automation/index.rst index e07dfecc..c19d819b 100644 --- a/docs/automation/index.rst +++ b/docs/automation/index.rst @@ -5,11 +5,11 @@ VyOS Automation * Ansible * Saltstack - * HTTP-API * startup scripts .. toctree:: :maxdepth: 1 - + + vyos-api command-scripting
\ No newline at end of file diff --git a/docs/automation/vyos-api.rst b/docs/automation/vyos-api.rst new file mode 100644 index 00000000..1504a05a --- /dev/null +++ b/docs/automation/vyos-api.rst @@ -0,0 +1,317 @@ +.. _vyosapi: + +######## +VyOS API +######## + +for configuration and enabling the API see :ref:`http-api` + +************** +Authentication +************** + +All Endpoint only listen on HTTP POST requests and the API KEY must set as +``key`` in the formdata. + +Below see one example or curl and one for python. +In the following, the documentation is reduced to curl. + +.. code-block:: none + + curl --location --request POST 'https://vyos/retrieve' \ + --form data='{"op": "showConfig", "path": []}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + +.. code-block:: python + + import requests + url = "https://vyos/retrieve" + payload={'data': '{"op": "showConfig", "path": []}', + 'key': 'MY-HTTPS-API-PLAINTEXT-KEY' + } + headers = {} + response = requests.request("POST", url, headers=headers, data=payload) + print(response.text) + + +************* +API Endpoints +************* + +/retrieve +========= + +With the ``retrieve`` endpoint you get parts or the whole configuration. + +To get the whole configuration, pass an empty list to the ``path`` field + +.. code-block:: none + + curl --location --request POST 'https://vyos/retrieve' \ + --form data='{"op": "showConfig", "path": []}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + + response (shorted) + { + "success": true, + "data": { + "interfaces": { + "ethernet": { + "eth0": { + "address": "dhcp", + "duplex": "auto", + "hw-id": "50:00:00:01:00:00", + "speed": "auto" + }, + "eth1": { + "duplex": "auto", + "hw-id": "50:00:00:01:00:01", + "speed": "auto" + ... + }, + "error": null + } + + +only get a part of the configuration, +for example ``system syslog``. + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/retrieve' \ + --form data='{"op": "showConfig", "path": ["system", "syslog"]}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + + response: + { + "success": true, + "data": { + "global": { + "facility": { + "all": { + "level": "info" + }, + "protocols": { + "level": "debug" + } + } + } + }, + "error": null + } + +if you just want the Value of a multi-valued node, use the ``returnValues`` +operation. + +for example get the addresses of a ``dum0`` interface + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/retrieve' \ + --form data='{"op": "returnValues", "path": ["interfaces","dummy","dum0","address"]}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + respone: + { + "success": true, + "data": [ + "10.10.10.10/24", + "10.10.10.11/24", + "10.10.10.12/24" + ], + "error": null + } + +/image +====== + +To add or delete an image, use the ``/image`` endpoint. + +add an image + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/image' \ + --form data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + respone (shorted): + { + "success": true, + "data": "Trying to fetch ISO file from https://downloads.vyos.io/rolling-latest.iso\n + ... + Setting up grub configuration...\nDone.\n", + "error": null + } + +delete an image, for example ``1.3-rolling-202006070117`` + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/image' \ + --form data='{"op": "delete", "name": "1.3-rolling-202006070117"}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": "Deleting the \"1.3-rolling-202006070117\" image...\nDone\n", + "error": null + } + + +/show +===== + +The ``/show`` endpoint is to show everthing in operational mode + +for example which images are installed + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/show' \ + --form data='{"op": "show", "path": ["system", "image"]}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": "The system currently has the following image(s) installed:\n\n + 1: 1.4-rolling-202102280559 (default boot)\n + 2: 1.4-rolling-202102230218\n + 3: 1.3-beta-202102210443\n\n", + "error": null + } + + +/generate +========= + +to run a ``generate`` command use the + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/generate' \ + --form data='{"op": "generate", "path": ["wireguard", "default-keypair"]}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": "", + "error": null + } + + +/configure +========== + +You can pass a ``set``, ``delete`` or ``comment`` command to the +``/configure`` endpoint. + +``set`` a single command + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/configure' \ + --form data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": null, + "error": null + } + + +``delete`` a single command + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/configure' \ + --form data='{"op": "delete", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": null, + "error": null + } + +The API push every request to a session and commit it. +But some of VyOS components like DHCP and PPPoE Servers, IPSec, VXLAN, and +other tunnels require full configuration for commit. +The Endpoint will process multiple commands when you pass them as a list to +the ``data`` field. + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/configure' \ + --form data='[{"op": "set","path":["interfaces","vxlan","vxlan1","remote","203.0.113.99"]}, {"op": "set","path":["interfaces","vxlan","vxlan1","vni","1"]}]' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": null, + "error": null + } + + +/config-file +============ + +The endpoint ``/config-file`` is to save or load a configuration. + +Save a running configuration to the startup configuration. +When you don't specify the file when saving, it saves to +``/config/config.boot``. + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/config-file' \ + --form data='{"op": "save"}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": "Saving configuration to '/config/config.boot'...\nDone\n", + "error": null + } + + +Save a running configuration to a file. + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/config-file' \ + --form data='{"op": "save", "file": "/config/test.config"}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": "Saving configuration to '/config/test.config'...\nDone\n", + "error": null + } + + +To Load a configuration file. + +.. code-block:: none + + curl -k --location --request POST 'https://vyos/config-file' \ + --form data='{"op": "load", "file": "/config/test.config"}' \ + --form key='MY-HTTPS-API-PLAINTEXT-KEY' + + response: + { + "success": true, + "data": null, + "error": null + }
\ No newline at end of file |