Configure the optional RESTCONF protocol on Fedora/CentOS 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.


Image17NOTE: If you are using SELinux 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. Please note that you will have to reboot your system for the SELinux configuration change to take effect if you made one. Please reboot before continuing.


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 yum install httpd
mydir> sudo yum install fcgi-devel
mydir> sudo yum install 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, which is the /var/www/yang-api/ directory. 


Image17NOTE: When building from sources on CentOS and Fedora, you will want to set the WEB_USER and WEB_GROUP build flags to match your WEB Server configuration. These flags determine the user/group ownership of the restconf program. The default user/group for httpd on Centos and Fedora is "apache" though these values may be different on your system, depending on your WEB server configuration. Here is an example setting the WEB_USER and WEB_GROUP to apache when compiling YumaPro SDK from source:


mydir> make EVERYTHING=1 DEBUG=1 USE_WERROR=1 WEB_USER=apache WEB_GROUP=apache


If you installed YumaPro SDK from a binary package you will need take additional steps, first creating the /var/www/yang-api/ directory if it does not exist, and then 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/
mydir> sudo chown apache:apache /var/www/yang-api/restconf
  



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 (httpd) on Fedora and CentOS the default user:group is apache:apache. 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 apache apache 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/httpd/conf/httpd.conf /etc/httpd/conf/httpd.conf.backup


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/httpd/conf/httpd.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 httpd 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/httpd/conf.d/


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


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> 


Restart the Apache Server


mydir> sudo service httpd reload
mydir> sudo service httpd 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 rpm -e yumapro-sdk
mydir> sudo rm -rf /var/www/yang-api
mydir> sudo rm  /etc/httpd/conf.d/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/httpd/conf.d/restconf.conf
  • Completely remove your Apache2 WEB Server:
mydir> sudo yum remove httpd
  • Start at the beginning of this article

Start netconfd-pro as root with the fileloc-fhs parameter set to true


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


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: