HTTP-API

Enabling HTTP-API

VyOS HTTP API can be enabled through the set service https api command.

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>.

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:

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:

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:

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:

# 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:

{"success": true, "data": {"dummy": {"dum1": {"address": "203.0.113.76/32"}}}, "error": null}

Passing an empty path will return the full config:

# 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:

# 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

Operational mode commands

It is possible to run show and generate commands:

Request:

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:

{"success": true, "data": "", "error": null}

Request:

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:

{"success": true, "data": "<some pubkey>=\n", "error": null}

Request:

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:

{"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}