4  RESTCONF Installation

Configure the optional RESTCONF protocol.

 

Image40

NOTE: RESTCONF is not available with YumaPro SDK Basic.

 

 

The restconf program is the FastCGI thin client that connects Apache2 (or other WEB server) to the netconf-subsystem-pro program. This lesson describes how to setup the restconf program as a WEB site on your system.

 

Image17

NOTE: 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 if you wish to use restconf:

 

mydir> sudo netconfd-pro --fileloc-fhs=true

 

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

 

 

 

Image39

NOTE: if you are using Ubuntu 18.04, then the “restconf” FGCI program called from the WEB server will not be permitted to access local sockets in the /tmp directory such as /tmp/ncxserver.sock. The fileloc-fhs parameter must be set to true for RESTCONF to function in Ubuntu 18.04.

 

mydir> sudo netconfd-pro --fileloc-fhs=true

 

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

 

 

 

4.1  Pre-requisites

You should have completed “3 Installing YumaPro SDK”. If you have installed YumaPro SDK with a binary package then RESTCONF is included. If you have installed the SDK from source code then you need to have built and installed using EVERYTHING=1 or WITH_RESTCONF=1 build variables.

 

4.1.1  NGINX Support

The following steps will show you how to integrate the restconf program into an Apache WEB server. If you would would rather integrate restconf into an NGINX WEB server then please review our FAQ: Setting up RESTCONF on the NGINX WEB server.

 

 

4.1.2  External Packages Needed by the Server

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.

 

Image18

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

 

 

 

Ubuntu version:

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

 

 

 

Fedora version:

mydir> sudo dnf install httpd

mydir> sudo dnf install fcgi-devel

mydir> sudo dnf install mod_fcgid

 

 

Image19

If commands shown above are not successful, install and build FastCGI developer kit from the source:

The archived WEB site for FastCGI:

https://fastcgi-archives.github.io/

 

Download latest libfcgi:

https://github.com/FastCGI-Archives/FastCGI.com/blob/master/original_snapshot/fcgi-2.4.1-SNAP-0910052249.tar.gz

 

Build and install from the source

 

 

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, creating sudo mkdir /var/www/yang-api/ if it does not exists and moving the restconf program as 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:

 

 

Fedora version:

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

 

 

 

4.2  Configuring the Apache Server File

 

Image20

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

Module fcgid already enabled

Module status already enabled

Enabling module headers.

To activate the new configuration, you need to run:

 service apache2 restart

 

 

Image35

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

 

 

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:

 

 

Ubuntu version:

mydir> sudo <your_editor>  /etc/apache2/apache2.conf

 

 

and add to the end of the configuration file:

 

 

ExtendedStatus On

 

 

Image23

NOTE: Enabling ExtendedStatus consumes additional system resources.

 

 

 

Image24

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 /usr/share/yumapro/util. 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.

 

 

mydir> sudo <your_editor> /etc/httpd/conf.d/restconf.conf

 

  ...

 

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

 

Image34

NOTE: 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. Refer to Section 3.8 “Configure TLS” of this document.

 

 

 

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

 

 

4.2.1  Setup TLS Certificates for Your RESTCONF Site

To use TLS Certificates with your restconf site you will first need to be sure your WEB server has the mod_ssl module installed and enabled. The SSL module will be installed by default if you have followed this guide to this point. You will have to enable the SSL module explicitly on Ubuntu/Debian systems:

 

 

Ubuntu version:

mydir> sudo a2enmod ssl

mydir> sudo service apache2 reload

 

 

Next you will need to edit your etc/apache2/sites-available/restconf.conf site configuration file and uncomment the optional TLS configuration block shown below:

 

Image36

NOTE: Be sure to insert your path to server.crt and server.key for the SSLCertificateFile and SSLCertificateKeyFile parameters instead of /home/<user-name>/certs/...

 

 

 

 

 

#

# Uncomment this block to enable RESTCONF over TLS

#

#
####    CHANGE /home/user/certs/... to your username or the location of the

####      certificates, e.g./home/fred/certs/... (in two locations below)
#
####

####

#<IfModule mod_ssl.c>

 

    ...

 

 

#        SSLCertificateFile /home/<user-name>/certs/server.crt

#        SSLCertificateKeyFile /home/<user-name>/certs/server.key

#

 

 

    ...

 

 

#</IfModule>

#

####

 

 

 

4.3  Restart the Apache Server

To restart the Apache Server follows the steps:

 

 

Ubuntu version:

mydir> sudo service apache2 reload

mydir> sudo service apache2 restart

 

 

 

Fedora version:

 

You need to reboot the system:

mydir> sudo reboot

 

When the system is back up:

 

mydir> sudo service sshd start

mydir> sudo service httpd start

 

 

Start the netconfd-pro as root using the fileloc-fhs=true parameter:

 

 

mydir> sudo netconfd-pro --fileloc-fhs=true

 

 

 

4.4  HTTP Connect

After WEB server reboot you can verify that the configuration are correct by using “curl” tool, for example. Send the following request to the RESTCONF server to verify that it is running and configured properly:

 

 

mydir> curl -u admin:<your-password> \ http://localhost/restconf/data/netconf-state/sessions

{

"sessions": {

 "session": [

  {

   "session-id":5,

   "transport":"yumaworks-ids:netconf-http",

   "username":"restconf",

   "source-host":"127.0.0.1",

   "login-time":"2018-11-20T07:39:14Z",

   "in-rpcs":0,

   "in-bad-rpcs":0,

   "out-rpc-errors":0,

   "out-notifications":0

  }

 ]

}

 

 

Image22

For more web requests using curl see the article: How can I execute web requests with tools like curl?

 

For more information on using RESTCONF see the articles in the section: RESTCONF