Tip
This is the documentation for the 22.02 version. Looking for the documentation of the latest version? Have a look here.
RESTCONF Server¶
TNSR includes a RESTCONF server which can respond to RESTCONF API requests over HTTP or HTTPS.
The RESTCONF server can run in the host
or dataplane
namespace
(Networking Namespaces), and may be active in both namespaces at the same
time.
Warning
Though the RESTCONF service is capable of running in the dataplane
namespace, the sensitive nature of its content means it should not be exposed
to insecure networks. The best practice is to only run the RESTCONF service
in the host
namespace.
See also
For a complete RESTCONF service configuration example, see RESTCONF Service Setup with Certificate-Based Authentication and NACM.
RESTCONF Server Configuration¶
The server is configured using the restconf
command to enter restconf
mode:
tnsr# configure
tnsr(config)# restconf
tnsr(config-restconf)#
Enable or Disable the RESTCONF Service¶
The RESTCONF server is enabled and disabled by the enable (true|false)
command from within restconf
mode.
To enable the RESTCONF service:
tnsr(config-restconf)# enable true
To disable the RESTCONF service:
tnsr(config-restconf)# enable false
RESTCONF Server Parameters¶
The RESTCONF server must be configured with specific details for where and how the service will run using the following command:
tnsr(config-restconf)# server <namespace> <ip-address> <port> <tls>
- <namespace>:
The namespace in which the RESTCONF service will be exposed, either
host
ordataplane
.- <ip-address>:
The IP address of an interface in the chosen namespace upon which the RESTCONF server can be accessed.
- <port>:
The port number upon which the RESTCONF server will listen for incoming connections. This is typically
443
for TLS (HTTPS) connections and80
for plain HTTP, but may be any available port.- <tls>:
Either
true
orfalse
to indicate whether or not the RESTCONF service will utilize TLS when communicating with clients. If enabled, the RESTCONF server must have a server certificate and key available, see TLS Encryption.
For example, to start the RESTCONF service in the host
namespace on
198.51.100.2
, port 443
with TLS enabled, run:
tnsr(config-restconf)# server host 198.51.100.2 443 true
TLS Encryption¶
The RESTCONF server utilizes TLS (HTTPS) to secure communications between the client and server. When configured with a certificate, the RESTCONF server supports both HTTP/1 (TLS) and HTTP/2 (TLS-ALPN) connections.
Warning
Though HTTPS is technically optional, the best practice is to always use encryption in production deployments.
Additionally, the RESTCONF server does not support HTTP/2 without encryption.
TLS requires a server certificate on the TNSR device. This server certificate and its corresponding key must be configured in the RESTCONF server:
tnsr(config)# restconf
tnsr(config-restconf)# global server-certificate <cert-name>
tnsr(config-restconf)# global server-key <key-name>
See also
For more information on managing certificates on TNSR, see Public Key Infrastructure.
Additionally, the RESTCONF server definition must also be set to use TLS. See RESTCONF Server Parameters for details.
Authentication¶
The RESTCONF server supports two types of client authentication to protect access to its resources: Client certificate authentication and password authentication:
tnsr(config-restconf)# global authentication-type (client-certificate|user)
Client Certificate¶
The most secure means of protecting access to the RESTCONF server is via client certificates:
tnsr(config-restconf)# global authentication-type client-certificate
tnsr(config-restconf)# global server-ca-cert-path <ca-name>
To verify client certificates, a Certificate Authority (CA) is configured in TNSR and all client certificates must be signed by this CA. The client certificate must be used by the client when attempting to connect to the RESTCONF server. Clients without a certificate are rejected.
See also
For more information on managing certificates on TNSR, see Public Key Infrastructure.
When using client certificates the Common Name (cn=
parameter) of the client
certificate is taken as the username. That username is then processed through
NACM to determine group access privileges for the RESTCONF
API.
Password¶
Password authentication for the RESTCONF server is handled via Pluggable Authentication Modules (PAM) support:
tnsr(config-restconf)# global authentication-type user
Users can be authenticated against any source supported by PAM modules in the operating system.
Once authenticated, the username is processed through NACM to determine group access privileges for the RESTCONF API.
Managing the RESTCONF Server Process¶
The RESTCONF server process can be managed using the service
command:
tnsr# configure
tnsr(config)# service restconf <command>
Where <command>
can be any of:
- start:
Start the RESTCONF server
- stop:
Stop the RESTCONF server
- restart:
Restart (stop and then start) the RESTCONF server
- status:
Print the status of the RESTCONF server process