Skip to content

Commit

Permalink
Merge pull request #1228 from vyos/https
Browse files Browse the repository at this point in the history
https: add latest CLI changes
  • Loading branch information
c-po authored Jan 11, 2024
2 parents 88410db + cecc0f3 commit 9ccf801
Showing 1 changed file with 37 additions and 41 deletions.
78 changes: 37 additions & 41 deletions docs/configuration/service/https.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. _http-api:

########
HTTP-API
HTTP API
########

VyOS provide an HTTP API. You can use it to execute op-mode commands,
Expand All @@ -13,75 +13,71 @@ Please take a look at the :ref:`vyosapi` page for an detailed how-to.
Configuration
*************

.. cfgcmd:: set service https api keys id <name> key <apikey>
.. cfgcmd:: set service https allow-client address <address>

Set a named api key. Every key has the same, full permissions
on the system.
Only allow certain IP addresses or prefixes to access the https
webserver.

.. cfgcmd:: set service https api debug
.. cfgcmd:: set service https certificates ca-certificate <name>

To enable debug messages. Available via :opcmd:`show log` or
:opcmd:`monitor log`
Use CA certificate from PKI subsystem

.. cfgcmd:: set service https api strict
.. cfgcmd:: set service https certificates certificate <name>

Enforce strict path checking
Use certificate from PKI subsystem

.. cfgcmd:: set service https virtual-host <vhost> listen-address
<ipv4 or ipv6 address>
.. cfgcmd:: set service https certificates dh-params <name>

Address to listen for HTTPS requests
Use :abbr:`DH (Diffie–Hellman)` parameters from PKI subsystem.
Must be at least 2048 bits in length.

.. cfgcmd:: set service https virtual-host <vhost> port <1-65535>
.. cfgcmd:: set service https listen-address <address>

Port to listen for HTTPS requests; default 443
Webserver should only listen on specified IP address

.. cfgcmd:: set service https virtual-host <vhost> server-name <text>
.. cfgcmd:: set service https port <number>

Server names for virtual hosts it can be exact, wildcard or regex.
Webserver should listen on specified port.

.. cfgcmd:: set service https api-restrict virtual-host <vhost>
Default: 443

By default, nginx exposes the local API on all virtual servers.
Use this to restrict nginx to one or more virtual hosts.
.. cfgcmd:: set service https enable-http-redirect

.. cfgcmd:: set service https certificates certbot domain-name <text>
Enable automatic redirect from http to https.

Domain name(s) for which to obtain certificate
.. cfgcmd:: set service https tls-version <1.2 | 1.3>

.. cfgcmd:: set service https certificates certbot email
Select TLS version used.

Email address to associate with certificate
This defaults to both 1.2 and 1.3.

.. cfgcmd:: set service https certificates system-generated-certificate
.. cfgcmd:: set service https vrf <name>

Use an automatically generated self-signed certificate
Start Webserver in given VRF.

.. cfgcmd:: set service https certificates system-generated-certificate
lifetime <days>
API
===

Lifetime in days; default is 365
.. cfgcmd:: set service https api keys id <name> key <apikey>

Set a named api key. Every key has the same, full permissions
on the system.

*********************
Example Configuration
*********************
.. cfgcmd:: set service https api debug

Set an API-KEY is the minimal configuration to get a working API Endpoint.
To enable debug messages. Available via :opcmd:`show log` or
:opcmd:`monitor log`

.. code-block:: none
.. cfgcmd:: set service https api strict

set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY
Enforce strict path checking

*********************
Example Configuration
*********************

To use this full configuration we asume a public accessible hostname.
Set an API-KEY is the minimal configuration to get a working API Endpoint.

.. code-block:: none
set service https api keys id MY-HTTPS-API-ID key MY-HTTPS-API-PLAINTEXT-KEY
set service https certificates certbot domain-name rtr01.example.com
set service https certificates certbot email mail@example.com
set service https virtual-host rtr01 listen-address 198.51.100.2
set service https virtual-host rtr01 port 11443
set service https virtual-host rtr01 server-name rtr01.example.com
set service https api-restrict virtual-host rtr01

0 comments on commit 9ccf801

Please sign in to comment.