Tip

This is the documentation for the 23.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 or dataplane.

<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 and 80 for plain HTTP, but may be any available port.

<tls>:

Either true or false 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.

Note

Currently the certificate used by the RESTCONF daemon cannot contain subject alternative name (SAN) entries. This will be corrected in a future release.

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