Configure the optional RESTCONF protocol on Ubuntu/Debian systems


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.


Pre-requisites


You should have completed section on Installing YumaPro SDK of the YumaPro Installation Guide. If you have installed YumaPro SDK with a binary package then RESTCONF is included. If you have installed the SDK from licensed source code then you need to have built and installed using EVERYTHING=1 or WITH_RESTCONF=1 build variables.


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.


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


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

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 additional steps, creating the /var/www/yang-api/ directory if it does not exists and moving the restconf program to /var/www/yang-api as show below:


mydir> sudo mkdir /var/www/yang-api/
mydir> sudo chmod 775 /var/www/yang-api/
mydir> sudo mv /usr/sbin/restconf /var/www/yang-api/


Image17Troubleshooting: check ownership and permissions of restconf program


It is very important that the restconf program is located in the correct place and that it has the correct ownership and permissions.

Please verify that restconf is located in /var/www/yang-api/ and that it is owned by the correct WEB_USER and WEB_GROUP.

For Apache on Debian and Ubuntu the default user:group is www-data:www-data. The restconf program also must be executable with 755 permissions.

You should see this when running ls -al /var/www/yang-api:


mydir> ls -al /var/www/yang-api/
...
-rwxr-xr-x 1 www-data www-data 248176 Mar 19 09:22 restconf


Configuring the Apache Server File


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


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


Enable modules in Apache:


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


Apache module 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:


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


and add to the end of the configuration file:


     ExtendedStatus On


Image17NOTE on mod_status: Enabling ExtendedStatus consumes additional system resources.


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


mydir> sudo service apache2 restart


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


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


OPTIONAL: Set up Apache authentication


To set up username/password based authentication for your restconf site, you will need to uncomment lines 71-74 of your restconf.conf (the four lines that are just below ### DISABLE PASSWORD!!) as shown:


  ...
        #### CHANGE '/var/www/yang-api' to match DocumentRoot if needed 
  <Directory /var/www/yang-api> 
    SetHandler fcgid-script 
    Options Indexes FollowSymLinks ExecCGI 
    AllowOverride all 
    Order allow,deny 
    allow from all 

    ### DISABLE PASSWORD!!
    AuthType Basic 
    AuthName "RESTCONF" 
    AuthUserFile /var/www/passwords/passwd 
    Require valid-user 
  </Directory> 
        ...


You can replace the AuthName value "RESTCONF" with whatever username you prefer. For this guide we will set up Apache authentication for user "RESTCONF":


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


Enable the restconf site:


mydir> sudo a2ensite restconf.conf
  Enabling site restconf.
  To activate the new configuration, you need to run:
    service apache2 reload


Restart the Apache Server


mydir> sudo service apache2 reload
mydir> sudo service apache2 restart


Image17Troubleshooting: If for some reason Apache does not restart, and you are unable to determine why, please undo all of the steps up to this point and start over:

  • Completely uninstall YumaPro SDK:
If YumaPro SDK binary package was installed:

mydir> sudo apt-get purge yumapro-sdk
mydir> sudo rm -rf /var/www/yang-api
mydir> sudo rm  /etc/apache2/sites-available/restconf.conf


If YumaPro SDK was built and installed from sources:

mysourcedir> sudo make <YOUR_BUILD_FLAGS> uninstall
mydir> sudo rm -rf /var/www/yang-api
mydir> sudo rm  /etc/apache2/sites-available/restconf.conf
  • Completely remove your Apache2 WEB Server:
mydir> sudo apt-get purge apache2
  • Start at the beginning of this article


Start netconfd-pro


mydir> netconfd-pro


HTTP Connect


Connect to the server using HTTP by entering in the URL address box of a browser:


http://localhost/restconf/data/system/uname


If you have done the optional Apache authentication steps outlined above then you will be prompted to enter your configured Username and Password. After doing this you should see something like this in your browser:




You can also use other web tools such as “curl” as shown below. Replace <your_user> and <your_password> with the values you configured when setting up password authentication:


mydir> curl -u <your_user>:<your_password> http://localhost/restconf/data/system/uname 
  {
   "uname": {
    "sysname":"Linux",
    "release":"4.10.0-37-generic",
    "version":"#41~16.04.1-Ubuntu SMP Fri Oct 6 22:42:59 UTC 2017",
    "machine":"x86_64",
    "nodename":"u16-vm"
   }


NOTES: