VyOS API
For configuration and enabling the API see HTTP API
Authentication
All endpoints except one listen on HTTP POST requests and the API KEY must set
as key
in the formdata. The only public endpoint listens to HTTP GET request
and takes optional query parameters.
Below see one example for curl and one for python. The rest of the documentation is reduced to curl.
curl --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "showConfig", "path": []}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
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
/info
This is the only endpoint provided by the API service that does not require
authentication and can be queried by anonymous users. Requesting the info
endpoint you obtain general information about the system, namely the VyOS
version, the system host name and a welcome banner for anonymous users.
This endpoint responds only to HTTP GET requests.
curl --location --request GET 'https://vyos/info'
response
{
"success": true,
"data": {
"version": "1.5-rolling",
"hostname: "vyos"
"banner": "Welcome to VyOS"
},
"error": null
}
This endpoint can take two optional query parameters - version
and
hostname
. These parameters accept all values that can be converted to
Boolean - e.g. yes/no
, 1/0
, true/false
etc, and they dictate whether
to include the respective values into the response.
If request is sent without any query parameters, the endpoints treats them as
if they are set to true
by default:
curl --location --request GET 'https://vyos/info?version=1&hostname=1'
response {
"success": true,
"data": {
"version": "1.5-rolling",
"hostname": "vyos",
"banner": "Welcome to VyOS"
},
"error": null
}
If any of the parameters is set to a value that corresponds to false
, the
response object will have an empty string instead of the respective value:
curl --location --request GET 'https://vyos/info?version=0&hostname=1'
response {
"success": true,
"data": {
"version": "",
"hostname": "vyos",
"banner": "Welcome to VyOS"
},
"error": null
}
Please note, that there is no need to specify both parameters if you want to
hide just one of the fields - a missing query parameter is treated as true
:
curl --location --request GET 'https://vyos/info?hostname=no'
response {
"success": true,
"data": {
"version": "1.5-rolling",
"hostname": "",
"banner": "Welcome to VyOS"
},
"error": null
}
Please note, that while you can disable output for both hostname
and
version
, the banner
is included into the response in any case.
Important: The endpoint accepts ONLY hostname
and version
query
parameters. Including any other besides them, or instead of them, will respond
with HTTP 400 Bad Request:
curl --location --request GET \
'https://192.168.56.119/info?hostname=1&url=https://evilsite.com'
response {
"success": false,
"error": "{'type': 'extra_forbidden', 'loc': ('query', 'url'), 'msg': 'Extra inputs are not permitted', 'input': 'https://evilsite.com'}",
"data": null
}
As well as the values passed to the query string are validated to ensure they are strictly Boolean and won’t accept any other data type:
curl --location --request GET 'https://vyos/info?hostname=1; eval"sudo rm -rf /"
response
{
"success": false,
"error": "{'type': 'bool_parsing', 'loc': ('query', 'hostname'), 'msg': 'Input should be a valid boolean, unable to interpret input', 'input': '1; eval \"sudo rm -rf /\"'}",
"data": null
}
/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
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
}
To only get a part of the configuration, for example system syslog
.
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.
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
}
To check existence of a configuration path, use the exists
operation.
For example, check an existing path:
curl -k --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "exists", "path": ["service","https","api"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
response:
{
"success": true,
"data": true,
"error": null
}
versus a non-existent path:
curl -k --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "exists", "path": ["service","non","existent","path"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
response:
{
"success": true,
"data": false,
"error": null
}
/reset
The reset
endpoint run a reset
command.
curl --location --request POST 'https://vyos/reset' \
--form data='{"op": "reset", "path": ["ip", "bgp", "192.0.2.11"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
respone:
{
"success": true,
"data": "",
"error": null
}
/reboot
To initiate a reboot use the reboot
endpoint.
curl --location --request POST 'https://vyos/reboot' \
--form data='{"op": "reboot", "path": ["now"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
respone:
{
"success": true,
"data": "",
"error": null
}
/poweroff
To power off the system use the poweroff
endpoint.
curl --location --request POST 'https://vyos/poweroff' \
--form data='{"op": "poweroff", "path": ["now"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
respone:
{
"success": true,
"data": "",
"error": null
}
/image
To add or delete an image, use the /image
endpoint.
add an image
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
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 everything in the operational mode.
For example, show which images are installed.
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
The generate
endpoint run a generate
command.
curl -k --location --request POST 'https://vyos/generate' \
--form data='{"op": "generate", "path": ["pki", "wireguard", "key-pair"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
response:
{
"success": true,
"data": "Private key: CFZR2eyhoVZwk4n3JFPMJx3E145f1EYgDM+ubytXYVY=\n
Public key: jjtpPT8ycI1Q0bNtrWuxAkO4k88Xwzg5VHV9xGZ58lU=\n\n",
"error": null
}
/configure
You can pass a set
, delete
or comment
command to the
/configure
endpoint.
set
a single command
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
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 pushes 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.
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
.
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.
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.
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
}
To Merge a configuration file.
curl -k --location --request POST 'https://vyos/config-file' \
--form data='{"op": "merge", "file": "/config/test.config"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
response:
{
"success": true,
"data": null,
"error": null
}
In either of the last two cases, one can pass a string in the body of the request, for example:
curl -k --location --request POST 'https://vyos/config-file' \
--form data='{"op": "merge", "string": "interfaces {\nethernet eth1 {\naddress "192.168.2.137/24"\ndescription "test"\n}\n}\n"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'
response:
{
"success": true,
"data": null,
"error": null
}
Commit-confirm
For the previous two endpoints discussed, a commit
command is implicit
following a succesful request operation (set | delete | load | merge
, or
a list of set
and delete
operations). One can instead request a
commit-confirm
command by including the field confirm_time
of type
int > 0. An example follows, in the alternative JSON format, for brevity,
although the standard form-data format is fine:
curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "merge", "string": "interfaces {\nethernet eth1 {\naddress '192.168.137.1/24'\ndescription 'internal'\n}\n}\n", "confirm_time": 1}' https://vyos/config-file
response:
{
"success": true,
"data": "Initialized commit-confirm; 1 minutes to confirm before reload\n",
"error": null
}
The committed changes will be reverted at the timeout unless confirmed. To confirm and keep the changes:
curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "confirm"}' https://vyos/config-file
response:
{
"success": true,
"data": "Reload timer stopped\n",
"error": null
}
If allowed to revert to the previous configuration, the manner in which changes are reverted is governed by:
vyos@vyos# set system config-management commit-confirm action
Possible completions:
reload Reload previous configuration if not confirmed
reboot Reboot to saved configuration if not confirmed (default)