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 netconf-subsystem-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:

mydir> 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.

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:

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

Fedora version:

mydir> 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:

mydir> sudo mkdir /var/www/yang-api/
mydir> sudo mv /usr/sbin/restconf /var/www/yang-api/
mydir> sudo chmod 775 /var/www/yang-api/restconf
mydir> 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:

mydir> 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:

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

Fedora version:

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

Enable modules in Apache:

Ubuntu version:

mydir> 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 lineL

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:

mydir> 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:

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

Fedora version:

mydir> 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:

mydir> sudo a2ensite restconf.conf
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.

mydir> sudo mkdir /var/www/passwords
mydir> cd /var/www/passwords
passwords> sudo htpasswd -c passwd admin
New password:
Re-type new password:
Adding password for user admin

NGINX Support

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

Installing the NGINX Server

Install the Packages

Example instructions to install NGINX on Ubuntu:

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

Example instructions to install NGINX on Fedora:

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

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 NGINX:

A) Stop the existing WEB server process.

Ubuntu Example:

mydir> sudo service apache2 stop

Fedora Example:

mydir> sudo service httpd stop

B) Remove the existing WEB server entirely.

Ubuntu Example:

mydir> sudo apt-get remove apache2

Fedora Example:

mydir> 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

#
...

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.

mydir> sudo rm /etc/nginx/sites-available/default
mydir> 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:

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

Modify the example NGINX configuration file:

mydir> 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 feel 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 "";

                ### 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:

mydir> 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:

mydir> 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:

mydir> 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.

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:

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

Fedora Example:

mydir> sudo mkdir -p /var/www/yang-api/.well-known
mydir> 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.

 user1$ 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$