RESTCONF Installation

This section describes how to setup the RESTCONF protocol on your system.

The restconf program is the FastCGI thin client that connects Apache2 (or other WEB server) to the netconfd-pro program. It is similar to the netconf-subsystem-pro program that is used to connect the SSH server to the netconfd-pro program.

If you are using an SELinux system (RHEL. CentOS. Fedora) you will need to set SELinux to permissive mode and start netconfd-pro as root with the --fileloc-fhs parameter set to true in order to use RESTCONF.

Example:

sudo netconfd-pro --fileloc-fhs=true

Please consult your System Administrator for assistance in managing SELinux on your system.

Apache Support

The following steps will show you how to integrate the restconf program into an Apache WEB server.

Note

• Apache2 or lighttpd is required if RESTCONF Notifications are used.

• Refer to the SSE Deployment Limitations section for details.

Required Packages for Apache

To use the RESTCONF protocol a WEB server is required. It must support the FastCGI API which is used by the restconf program for REST access to the netconfd-pro server.

Note

The 'fcgid' module is needed. Do not use the older 'fastcgi' module.

Ubuntu version:

sudo apt-get install apache2 libapache2-mod-fcgid libfcgi-dev

Fedora version:

sudo dnf install httpd mod_fcgid fcgi-devel

If this command fails, then refer to the libfcgi section for details on installing it from sources.

If you have built and installed YumaPro SDK from source code then the restconf program will be installed in the correct location.

If you installed YumaPro SDK from a binary package you will need take an additional steps, show below:

sudo mkdir /var/www/yang-api/
sudo mv /usr/sbin/restconf /var/www/yang-api/
sudo chmod 775 /var/www/yang-api/restconf
sudo chown www-data:www-data /var/www/yang-api/restconf

For Fedora systems you need to change the user and group ownership of restconf:

sudo chown apache:apache /var/www/yang-api/restconf

Configuring the Apache Server

Before making any changes to your Apache configuration, be sure to back up the configuration file:

Ubuntu version:

sudo cp /etc/apache2/apache2.conf /etc/apache2/apache2.conf.backup

Fedora version:

sudo cp /etc/httpd/conf/httpd.conf /etc/httpd/conf/httpd.conf.backup

Enable modules in Apache:

Ubuntu version:

sudo a2enmod fcgid status headers

To activate the new configuration, you need to run:

> sudo service apache2 restart

On Fedora/CentOS systems you do not need to explicitly enable individual Apache modules like mod-fcgid, as these modules are enabled automatically upon installation.

Extended Status

Apache mod_status offers an option called ExtendedStatus, which provides additional information about each request made to Apache and FastCGI. To enable ExtendedStatus edit your Apache configuration file:

Enabling ExtendedStatus consumes additional system resources.

The default Apache configuration file is /etc/apache2/apache2.conf. Edit the "apache2.conf" file and add the following line:

ExtendedStatus On

Module Headers

Apache mod_headers is used to provide support for the RESTCONF client discovery of the root of the RESTCONF API. The client discovers this by getting the /.well-known/host-meta resource and using the <Link> element containing the "restconf" attribute. Refer to Virtual Host configuration file below for more details.

Restart Apache:

Ubuntu version:

sudo service apache2 restart

You need a restconf configuration file. One has been provided in the /usr/share/yumapro/util directory. To place the configuration file in the correct location for Apache:

Ubuntu version:

sudo cp /usr/share/yumapro/util/restconf.conf /etc/apache2/sites-available/

Fedora version:

sudo cp /usr/share/yumapro/util/restconf.conf /etc/httpd/conf.d/

Fedora version:

In the /etc/httpd/conf.d/restconf.conf file you need to comment out the sections for logging.

#### CHANGE to preferred logging location if desired
#### MUST Change if not Apache2!!!
#ErrorLog ${APACHE_LOG_DIR}/error.log

# Possible values include: debug, info, notice, warn, error, crit,
# alert, emerg.
#LogLevel warn

#### CHANGE to preferred logging location if desired
#### MUST Change if not Apache2!!!
#CustomLog ${APACHE_LOG_DIR}/access.log combined

Enable the "restconf" site:

Ubuntu version:

sudo a2ensite restconf.conf

Example output:

Enabling site restconf.
To activate the new configuration, you need to run:
  service apache2 reload

Set up Apache authentication for a user 'admin':

Using password authentication in the way shown below is considered DEPRECATED. This is a relic of yang-api, a pre-standard implementation of the RESTCONF protocol. To set up security for your restconf site please configure your own TLS certificates and keys to suit your installation, as described in the Configure TLS section.

sudo mkdir /var/www/passwords
cd /var/www/passwords
sudo htpasswd -c passwd admin

Example output:

New password:
Re-type new password:
Adding password for user admin

Handle Multiple WEB Servers for RESTCONF

It is possible to use more than one WEB server on a host. It is also possible that an existing WEB server needs to be removed or reconfigured.

Note

If your system already has another WEB server installed, such as Apache, you must do at least one of the following (A, B, or C) prior to using another WEB server.

A) Disable the existing WEB server process.

Ubuntu Example:

sudo systemctl stop apache2
sudo systemctl disable apache2

Fedora Example:

sudo systemctl stop httpd.service
sudo systemctl disable httpd.service

B) Remove the existing WEB server entirely.

Ubuntu Example:

sudo apt-get remove apache2

Fedora Example:

sudo dnf remove httpd

C) Configure the existing WEB server to listen on a port other than 80.

Ubuntu example of Apache's /etc/apache2/ports.conf file configured to listen on 8080:

# If you just change the port or add more ports here, you will likely also
# have to change the VirtualHost statement in
# /etc/apache2/sites-enabled/000-default.conf

Listen 8080

<IfModule ssl_module>
  Listen 443
</IfModule>

<IfModule mod_gnutls.c>
  Listen 443
</IfModule>

# vim: syntax=apache ts=4 sw=4 sts=4 sr noet

Fedora example of Apache's /etc/httpd/conf/httpd.conf file configured to listen on 8080:

...
#
# Listen: Allows you to bind Apache to specific IP addresses and/or
# ports, instead of the default. See also the <VirtualHost>
# directive.
#
# Change this to Listen on specific IP addresses as shown below to
# prevent Apache from glomming onto all bound IP addresses.
#
#Listen 12.34.56.78:80
Listen 8080

#
...

NGINX Support

The following steps will show you how to integrate the restconf program into an NGINX WEB server.

Note

• NGINX is not supported if RESTCONF Notifications are used.

• Refer to the SSE Deployment Limitations section for details.

Installing the NGINX Server

Refer to the Handle Multiple WEB Servers for RESTCONF section to prepare the system for the NGINX server.

Install the Packages

Example instructions to install NGINX on Ubuntu:

sudo apt-get install nginx fcgiwrap nginx-doc spawn-fcgi
sudo systemctl enable nginx

Example instructions to install NGINX on Fedora:

sudo dnf install nginx fcgiwrap spawn-fcgi fcgi-devel
sudo systemctl enable nginx

Configuring the NGINX Server

Confirm the location of the "restconf" program, which is needed to set the FASTCGI_FILENAME variable below.

• If the server is built from sources the program should be installed as /var/www/yang-api/restconf

• If the server is installed from a package, the program should be installed as /usr/sbin/restconf

Make sure to disable default site before using the newly created restconf site.

sudo rm /etc/nginx/sites-enabled/default

Copy or Create the NGINX Config File for the RESTCONF Server

There is an example config file that can be used from the YumaPro SDK installation. To copy this file for use in NGINX:

sudo cp /usr/share/yumapro/util/restconf-nginx /etc/nginx/sites-available/restconf

Modify the example NGINX configuration file:

nano /etc/nginx/sites-available/restconf

#
# RESTCONF server configuration
#
server {
    listen 80;
    listen [::]:80;

    ### CHANGE ServerName TO YOUR DOMAIN NAME!!!
    server_name localhost;

    ### Set the root to /var/www/yang-api for all locations
    root /var/www/yang-api;

    ### need to install fcgiwrap to use RESTCONF
    ### set SCRIPT_FILENAME to the location of the restconf program
    location /restconf {

        ### Disable gzip (it makes scripts slower since they have to complete
        ### before getting gzipped)
        gzip                    off;

        ### Fastcgi socket
        fastcgi_pass            unix:/var/run/fcgiwrap.socket;

        ### Fastcgi parameters, include the standard ones
        include                 /etc/nginx/fastcgi_params;

        ### Actual executable
        fastcgi_param           SCRIPT_NAME restconf;

        ### Complete path to the script.
        ### When set, overrides DOCUMENT_ROOT and SCRIPT_NAME
        fastcgi_param           SCRIPT_FILENAME /var/www/yang-api/restconf;

        ### When set (e.g., to ""), disables fastcgiwrap output buffering.
        ### MUST be set if SSE used!
        ### Only available in fcgiwrap version 1.1.0-11 and higher!
        ### Only available on Debian maintained version of fcgiwrap!
        ### RPM users may choose to patch their fcgiwrap.c file to add
        ### NO_BUFFERING functionality.
        ### https://github.com/gnosek/fcgiwrap/pull/48/files
        fastcgi_param           NO_BUFFERING "";

        ### RESTCONF SSE keepalive timeout in seconds
        ### type uint16 { range "0 | 5..3600"; }
        ### Server sends SSE comment ':SSE keepalive' at timeout
	### 0 = do not use (default)
	### suggest 30 - 120 (must be less than fastcgi_read_timeout)
        #fastcgi_param          SSE_KEEPALIVE 30;

        ### When buffering is disabled, the response is passed to a
        ### client synchronously, immediately as it is received.
        ### Nginx will not try to read the whole response from the
        ### FastCGI server.
        ### MUST be set if SSE used
        fastcgi_buffering       off;

        ### This is the maximum time limit for request handling.
        ### If a FastCGI request does not complete within this timeout
        ### seconds, it will be subject to termination.
        ### Set to big number if SSE used
        fastcgi_read_timeout    120s;
    }

    location /.well-known {
        default_type application/xrd+xml;
        etag off;
        add_header Last-Modified "";
    }

}

Enable the RESTCONF Server

The 'restconf' site must be enabled before it can be used:

sudo ln -s /etc/nginx/sites-available/restconf /etc/nginx/sites-enabled/restconf

Restart the NGINX Server

The NGINX server should be started or restarted at this point to activate the configuration changes:

sudo systemctl restart nginx

Troubleshooting:

• Make sure that the "restconf" program is installed in proper place:

fastcgi_param SCRIPT_FILENAME /var/www/yang-api/restconf;

• Check permissions and ownership.

• If the restconf exists in /usr/sbin/restconf location, try to run the server with "sudo" and --fileloc-fhs=true:

sudo netconfd-pro --fileloc-fhs=true

Note

If you use yangcli-pro and connect it using RESTCONF protocol, by default the session will be terminated after 65 seconds since the default value for keepalive_timeout parameter is 65s

In order to allow yangcli-pro to be connected for a longer period of time edit the /etc/nginx/nginx.conf file and add or update the following parameters:

http {

    ## The number of requests a client can make over a single
    ## keepalive connection. The default is 100, but a much higher
    ## value can be especially useful for testing with a
    ## load‑generation tool, which generally sends a large number
    ## of requests from a single client.
    keepalive_requests 200;

    ## How long to allow each connection to stay idle; longer values are better
    ## for each individual client, particularly for SSL, but means that worker
    ## connections are tied up longer. (Default: 65)
    ## Set to big number to maintain yangcli-pro RESTCONF session alive
    keepalive_timeout 1000;
}

After that the RESTCONF session in the yangcli-pro will not be terminated after 65 seconds.

Configuring NGINX with Multiple FastCGI Workers

NGINX commonly forwards RESTCONF requests to fcgiwrap through a Unix-domain socket. The default operating-system configuration may use systemd socket activation and start only one fcgiwrap process.

A single worker is insufficient when an SSE subscription and additional RESTCONF requests must be processed concurrently. An SSE request is a long-lived HTTP request and can occupy the only available worker.

The following procedure replaces the default single-worker, socket-activated fcgiwrap service with a spawn-fcgi service that starts multiple fcgiwrap workers.

The examples in this section use eight workers and the following Unix socket:

/run/fcgiwrap.socket

The socket path and service names may differ between operating systems. The NGINX fastcgi_pass configuration and the spawn-fcgi service must reference the same socket.

Inspecting the Existing FastCGI Configuration

Before changing the service configuration, identify the currently running FastCGI process and the socket used by NGINX.

Display the current FastCGI-related processes:

ps -ef | grep -E 'spawn-fcgi|fcgiwrap|restconf' | grep -v grep

A default single-worker configuration may appear as follows:

www-data  1234  1  0  ?  00:00:00 /usr/sbin/fcgiwrap -f

Display the installed fcgiwrap service and socket definitions:

systemctl cat fcgiwrap.service
systemctl cat fcgiwrap.socket

A default socket definition may contain:

[Socket]
ListenStream=/run/fcgiwrap.socket

Inspect the NGINX configuration to determine which FastCGI socket is used:

grep -R "fastcgi_pass" /etc/nginx 2>/dev/null

For example:

fastcgi_pass unix:/var/run/fcgiwrap.socket;

On systems where /var/run is a symbolic link to /run, the following paths refer to the same socket:

/var/run/fcgiwrap.socket
/run/fcgiwrap.socket

The path configured by NGINX must match the path used by the new spawn-fcgi service.

Verifying That spawn-fcgi Is Installed

The spawn-fcgi utility manages multiple FastCGI worker processes. Verify that the executable is installed:

command -v spawn-fcgi

A typical result is:

/usr/bin/spawn-fcgi

If the command is not installed on a Debian or Ubuntu system, install the corresponding package:

sudo apt update
sudo apt install spawn-fcgi

Package names and installation commands may differ on other operating systems.

Stopping the Single-Worker Socket Service

The default fcgiwrap service and socket must be stopped before the new service is started. Both configurations cannot own the same Unix socket simultaneously.

Stop the existing service and socket:

sudo systemctl stop fcgiwrap.service fcgiwrap.socket

Disable automatic startup of the original socket-activated service:

sudo systemctl disable fcgiwrap.service fcgiwrap.socket

Remove any stale socket file:

sudo rm -f /run/fcgiwrap.socket

The socket path must be adjusted if a different path is configured by fcgiwrap.socket or NGINX.

Creating the Multi-Worker Service

Create a dedicated systemd service for spawn-fcgi:

sudo vi /etc/systemd/system/fcgiwrap-multi.service

Add the following configuration:

[Unit]
Description=FastCGI Wrapper with Multiple Workers
After=network.target
Before=nginx.service

[Service]
Type=forking

ExecStartPre=/usr/bin/rm -f /run/fcgiwrap.socket

ExecStart=/usr/bin/spawn-fcgi \
    -F 8 \
    -s /run/fcgiwrap.socket \
    -U www-data \
    -G www-data \
    -u www-data \
    -g www-data \
    -- /usr/sbin/fcgiwrap

ExecStop=/usr/bin/pkill -TERM -x fcgiwrap

Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target

The options have the following purposes:

-F 8

Starts eight fcgiwrap worker processes.

-s /run/fcgiwrap.socket

Creates the Unix-domain FastCGI socket.

-U www-data and -G www-data

Set the user and group ownership of the socket.

-u www-data and -g www-data

Run the worker processes as the www-data user and group.

The service account should match the account expected by the local NGINX and FastCGI configuration.

The worker count can be changed by replacing 8 with another positive value. The selected value should allow for both long-lived SSE connections and ordinary RESTCONF requests.

Reloading systemd and Starting the Service

Reload the systemd configuration after creating the service file:

sudo systemctl daemon-reload

Enable the service at system startup and start it immediately:

sudo systemctl enable --now fcgiwrap-multi.service

Display the service status:

systemctl status fcgiwrap-multi.service

The service should report an active state. If startup fails, inspect the system journal:

journalctl -u fcgiwrap-multi.service

Verifying the Worker Processes

Display the active fcgiwrap processes:

pgrep -a fcgiwrap

Count the number of workers:

pgrep -c fcgiwrap

For the example configuration, the expected count is 8.

Verify that the FastCGI socket exists:

ls -l /run/fcgiwrap.socket

The socket should normally be owned by the account configured with the -U and -G options, for example:

srwxr-xr-x 1 www-data www-data ... /run/fcgiwrap.socket

The active process list can also be inspected with:

ps -ef | grep -E 'spawn-fcgi|fcgiwrap' | grep -v grep

The output should show the spawn-fcgi launcher and multiple fcgiwrap worker processes.

Restarting NGINX

Validate the NGINX configuration before restarting the service:

sudo nginx -t

Restart NGINX after the FastCGI socket and workers are available:

sudo systemctl restart nginx

Display the NGINX status if the restart fails:

systemctl status nginx

The NGINX fastcgi_pass directive must reference the socket created by spawn-fcgi. For example:

fastcgi_pass unix:/var/run/fcgiwrap.socket;

If /var/run links to /run, this directive is compatible with a service that creates:

/run/fcgiwrap.socket

Testing RESTCONF Concurrency

First, verify that the RESTCONF root is reachable:

curl --max-time 5 http://localhost/restconf

Next, establish a dynamic subscription to the NETCONF event stream:

curl -sS \
    -X POST \
    http://localhost/restconf/operations/ietf-subscribed-notifications:establish-subscription \
    -H "Content-Type: application/yang-data+json" \
    -H "Accept: application/yang-data+json" \
    -d '{"input":{"stream":"NETCONF"}}'

The response contains a subscription identifier and URI, for example:

{
  "ietf-subscribed-notifications:output": {
    "id": 1,
    "ietf-restconf-subscribed-notifications:uri":
      "http://restconf-dev/restconf/subscriptions/1"
  }
}

Open the returned subscription path as an SSE stream:

curl -N \
    -H "Accept: text/event-stream" \
    http://localhost/restconf/subscriptions/1

Leave the SSE request running.

From another terminal, send an additional RESTCONF request:

curl -v \
    --max-time 5 \
    http://localhost/restconf

With multiple fcgiwrap workers, the second request should be processed while the SSE stream remains active.

If the second request remains blocked, verify all of the following:

• Multiple fcgiwrap processes are running.

• NGINX is using the same Unix socket created by spawn-fcgi.

• The original fcgiwrap.socket service is not active.

• The new multi-worker service is active.

• The number of active SSE subscriptions has not consumed all available workers.

The active services can be checked with:

systemctl status fcgiwrap-multi.service
systemctl status fcgiwrap.socket
systemctl status nginx

The original socket service should be inactive, and the multi-worker service should be active.

Restoring the Default Socket-Activated Service

To restore the original single-worker configuration, stop and disable the multi-worker service:

sudo systemctl disable --now fcgiwrap-multi.service

Remove the custom service file:

sudo rm -f /etc/systemd/system/fcgiwrap-multi.service

Reload systemd:

sudo systemctl daemon-reload

Enable and start the original socket-activated service:

sudo systemctl enable --now fcgiwrap.socket

Restart NGINX:

sudo systemctl restart nginx

Verify the restored configuration:

systemctl status fcgiwrap.socket
systemctl status fcgiwrap.service

lighttpd Support

The following steps will show you how to integrate the restconf program into a lighttpd WEB server.

Installing the lighttpd Server

Refer to the Handle Multiple WEB Servers for RESTCONF section to prepare the system for the lighttpd server.

• lighttpd is the WEB server used in the Yocto 'netconfd-pro-sdn' recipe

• RESTCONF Notifications are fully supported

Install the Packages

Example instructions to install lighttpd on Ubuntu:

sudo apt-get install lighttpd

Example instructions to install lighttpd on Fedora:

sudo dnf install lighttpd

Configuring the lighttpd Server

Confirm the location of the "restconf" program, which is needed in the lighttpd configuration file for the RESTCONF server.

• If the server is built from sources the program should be installed as /var/www/yang-api/restconf

• If the server is installed from a package, the program should be installed as /usr/sbin/restconf

There should not be any default site configured that would conflict with the /restconf URI.

Copy or Create the lighttpd Config File for the RESTCONF Server

There is an example config file that can be used from the YumaPro SDK installation. To copy this file for use in lighttpd:

• Ubuntu example uses new location

sudo cp /usr/share/yumapro/util/restconf-lighttpd.conf /etc/lighttpd/conf-available/20-restconf.conf

• Yocto example uses old location NOTE: Automatically installed by netconfd-pro-sdn recipe

sudo cp /usr/share/yumapro/util/restconf-lighttpd.conf /etc/lighttpd.d/20-restconf.conf

Modify the example lighttpd configuration file:

nano /etc/lighttpd/conf-available/20-restconf.conf

server.modules += (
    "mod_fastcgi"
)

fastcgi.debug = 1

server.stream-response-body = 2

fastcgi.server += (
  "/restconf" =>
   (( "host" => "0.0.0.0",
      "port" => 1026,
      "bin-path" => "/usr/sbin/restconf",
      "check-local" => "disable",
      "bin-environment" => (
         "SSE_KEEPALIVE" => "30"
      ),
      "idle-timeout" => 3600,
      "max-procs" => 16
   ))
)

Refer to the official FastCGI Configuration guide for more details on this configuration file.

Enable the RESTCONF Server

The '20-restconf' site must be enabled on Ubuntu before it can be used.

• This step is not required if the older /etc/lighttpd.d location is used instead.

cd /etc/lighttpd/conf-enabled
sudo ln -s ../conf-available/20-restconf.conf 20-restconf.conf

Restart the lighttpd Server

The lighttpd server should be started or restarted at this point to activate the configuration changes:

sudo systemctl restart lighttpd

RESTCONF 'well-known' Directory

The RESTCONF protocol supports Root Resource Discovery, as defined in RFC 8040 Section 3.1.

From Package Installation

Since the location of the WEB server root is not known at installation time, this directory is not setup automatically, unless the server is built from sources.

The .well-known directory needs to be installed in the same directory that the 'restconf' binary program is installed.

For example, if the suggested location /var/www/yang-api/ is used:

Ubuntu Example:

sudo mkdir -p /var/www/yang-api/.well-known
sudo install --owner=www-data --group=www-data /usr/share/yumapro/util/host-meta /var/www/yang-api/.well-known

Fedora Example:

sudo mkdir -p /var/www/yang-api/.well-known
sudo install --owner=root --group=root /usr/share/yumapro/util/host-meta /var/www/yang-api/.well-known

From Source Installation

The '.well-known' directory is setup during the 'make install' step of the build process. There are 3 make variables that can be set to control where the 'restconf' program and this directory will be installed.

• WEB_DIR:

• The directory where the files will be installed

• This directory will be created if it does not exist

• Default: /var/www/yang-api

• WEB_GROUP:

• The group name for ownership of the directory and files

• Should set to root on Fedora since group www-data does not exist.

• Default: www-data

• WEB_USER:

• The user name for ownership of the directory and files

• Should set to root on Fedora since group www-data does not exist.

• Default: www-data

The following log snippet shows the default installation:

 make[3]: Entering directory '/home/andy/swdev/ypwork/netconf/src/restconf'
 Compiling in C++11 mode
 mkdir -p /var/www/yang-api
 mkdir -p /var/www/yang-api/.well-known
 install --owner=www-data --group=www-data \
 ../../target/bin/restconf /var/www/yang-api/
 install --owner=www-data --group=www-data \
 ../../util/host-meta /var/www/yang-api/.well-known/
 make[3]: Leaving directory '/home/andy/swdev/ypwork/netconf/src/restconf'

Test the Installation

The 'curl' command can be used in this example to retrieve the 'host-meta' file:

• Note that no end-of-line is sent after the last closing tag.

 curl http://localhost/.well-known/host-meta
 <?xml version='1.0' encoding='UTF-8'?>
 <XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
   <Link rel='restconf' href='/restconf' />
 </XRD>user1$