HTTP API
VyOS provides an HTTP API. You can use it to run operational-mode commands or to change or delete configuration. The API is available as both a REST API and a GraphQL API.
For REST API request examples, endpoints, and authentication details, see VyOS API.
Note
If no PKI certificate is configured for the service, VyOS automatically generates a self-signed certificate. This is not recommended for production use.
Configuration
HTTPS listener
Configure a local IPv4 or IPv6 address on which the HTTPS listener accepts incoming connections.
The IP address must already be assigned to a local interface. Repeat the command to configure multiple IP addresses.
When unset, the listener accepts incoming connections on all local IP addresses.
Example:
set service https listen-address 192.0.2.1
set service https listen-address 2001:db8::1
Configure the TCP port on which the HTTPS listener accepts incoming connections.
The default is 443.
Note
If the chosen port is already in use by another service, the commit fails.
Example:
set service https port 8443
Bind the HTTPS listener to the specified VRF instance.
The VRF must already be configured under set vrf name <name>.
Example:
set service https vrf mgmt
Restrict access to the HTTPS API endpoints to the specified IPv4 or IPv6 address or prefix.
Repeat the command to allow multiple IP addresses or prefixes.
When unset, the API accepts connections from any IP address.
Example:
set service https allow-client address 192.0.2.0/24
set service https allow-client address 2001:db8::/32
Enable redirection of incoming HTTP requests (port 80) to HTTPS.
The redirect sends traffic to the default HTTPS port (443). If you have changed the HTTPS port, the redirect will not work.
Example:
set service https enable-http-redirect
Configure the maximum size, in megabytes, of an HTTP request body accepted by the listener.
Requests exceeding this limit are rejected.
The default is 1.
Example:
set service https request-body-size-limit 10
TLS
Enable a specific TLS protocol version for the HTTPS listener.
Repeat the command to enable multiple protocol versions.
By default, both TLS 1.2 and TLS 1.3 are enabled.
Example:
set service https tls-version 1.3
Bind a TLS certificate from the PKI subsystem to the HTTPS listener.
The certificate must already be defined under
set pki certificate <name> with both a certificate and a private
key.
Example:
set service https certificates certificate my-server-cert
Bind a CA certificate from the PKI subsystem to the HTTPS listener.
The CA must already be defined under set pki ca <name>. The CA
certificate is appended to the TLS certificate to form a full chain
presented to clients during the TLS handshake.
Example:
set service https certificates ca-certificate my-internal-ca
Choose Diffie-Hellman parameters from the PKI subsystem for the HTTPS listener.
The parameters must already be defined under set pki dh <name> with
a key size of at least 2048 bits. The parameters are used by DHE
cipher suites in TLS 1.2. TLS 1.3 does not use them.
Example:
set service https certificates dh-params my-dh-2048
API authentication
Configure an HTTP API key to authenticate REST requests, and GraphQL requests unless GraphQL is switched to JWT token authentication.
The key is specified in plaintext and grants full access to the API.
At least one key must be configured to use the REST API. GraphQL can run without keys if JWT token authentication is enabled.
Example:
set service https api keys id MY-HTTPS-API-ID key 'MY-HTTPS-API-PLAINTEXT-KEY'
REST
Example:
set service https api rest
Reject delete requests on the /configure endpoint when the target
configuration path does not exist.
Without this flag, such requests succeed silently.
Example:
set service https api rest strict
Log detailed error messages to the systemd journal when API configuration requests fail.
Without this flag, only short error messages are logged.
Example:
set service https api rest debug
GraphQL
Enable GraphQL schema introspection.
Authenticated clients can then query the endpoint for the full schema. Disabled by default, and typically kept disabled in production due to security concerns.
Example:
set service https api graphql introspection
Configure the authentication type for GraphQL requests:
key: Uses the API keys configured inservice https api keys.token: Uses JWT tokens.
The default is key.
Example:
set service https api graphql authentication type token
Configure the lifetime, in seconds, of JWT tokens.
The default is 3600.
Example:
set service https api graphql authentication expiration 86400
Configure the length, in bytes, of the shared secret used to sign JWT tokens.
The default is 32.
Example:
set service https api graphql authentication secret-length 64
Configure which websites (origins) can read responses from the GraphQL API in a browser, using CORS.
Repeat the command to allow multiple origins.
Example:
set service https api graphql cors allow-origin https://app.example.com
Example
The minimal configuration for a working REST API requires enabling REST and configuring at least one API key:
set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY
set service https api rest