YumaWorks

The NGINX WEB server can be used to support the RESTCONF protocol within netconfd-pro.

The 17.10-4 release (or later) must be used.

Example instructions to install NGINX on Ubuntu:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

sudo apt-get install nginx fcgiwrap nginx-doc spawn-fcgi
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 prior to installing NGINX:

        Stop the existing WEB server process. Example:

sudo service apache2 stop

        OR Remove the existing WEB server entirely. Example:

sudo apt-get remove apache2

        OR Configure the existing WEB server to listen on a port other than 80. 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

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

Example NGINX configuration file: 

> nano /etc/nginx/sites-available/restconf

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

> rm /etc/nginx/sites-available/default

The following config file is installed as /usr/share/yumapro/util/restconf-nginx

#
# 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 "";
	}
}

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

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 nginx.conf file and add 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;
}