YumaPro Installation Guide¶

YumaPro SDK provides a complete YANG Software Development Kit to build servers and clients that support multi-protocol interfaces to device or virtual service configuration and operational data.

../_images/Install_YumaPro_02-02-2022.png

The following lessons provide an introduction to YumaPro SDK including:

Basics of installation
Network connection
Installing optional features
Working with YANG modules
Creating and testing server instrumentation

Supported Distributions and Architectures¶

To start using YumaPro SDK it first needs to be installed along with some support libraries on a Linux system. The following platforms are supported and maintained for the YumaPro SDK binary packages:

Distribution	Architecture	Directory
Debian 9	64-bit AMD	deb9
Debian 10	64-bit AMD and AARCH64 64-bit ARM	deb10
Debian 11	64-bit AMD and AARCH64 64-bit ARM	deb11
Redhat Enterprise Linux 7 and CentOS 7	x86_64	el7
Redhat Enterprise Linux 8 and CentOS Stream 8	x86_64	el8
Redhat Enterprise Linux 9 and CentOS Stream 9	x86_64	el9
Oracle Linux 7	x86_64 and AARCH64 64-bit ARM	el7
Oracle Linux 8	x86_64 and AARCH64 64-bit ARM	el8
Fedora 34	x86_64 and AARCH64 64-bit ARM	fc34
Fedora 35	x86_64 and AARCH64 64-bit ARM	fc35
Fedora 36	x86_64 and AARCH64 64-bit ARM	fc36
Raspberry Pi OS 8	ARMv7 32-bit	rpi3
Ubuntu 16.04 LTS	64-bit AMD	u1604
Ubuntu 18.04 LTS	64-bit AMD and AARCH64 64-bit ARM	u1804
Ubuntu 20.04 LTS	64-bit AMD and AARCH64 64-bit ARM	u2004
Ubuntu 22.04 LTS	64-bit AMD and AARCH64 64-bit ARM	u2204

Architecture refers to the supported CPU architectures for a distribution.

Directory refers to the location of the binaries on the YumaWorks /dld site.

Package Pre-requisites¶

YumaPro SDK installs on most modern Linux systems with very few requirements. You will need:

$HOME needs to be set on your system or you need to run netconfd-pro with the option --home=/home/<YOUR-USER-NAME>. To set your $HOME environment variable see: https://help.ubuntu.com/community/EnvironmentVariables
a current version of one of the supported Linux systems
access to the External Open Source packages listed below
root access to your Linux system to install packages

Also, either:

access to YumaWorks dld site: https://www.yumaworks.com/dld (account needed)

or:

access to YumaPro SDK Basic

For YumaPro SDK licensees:

You should have received a username and password for access to YumaWorks download site that provides access to the YumaWorks products you have licensed. If you have not received access please contact sales@yumaworks.com.

External Package Needed by the Server and Client¶

libxml2¶

libxml2: is needed by some of the XML parsing functions This is usually installed by default on most Linux systems. If you are building YumaPro from source you will also need the associated developer package called libxml2-devon DEB based systems and libxml2-develon RPM based systems.

Ubuntu version:

mydir> sudo apt-get install libxml2-dev

Fedora version:

mydir> sudo dnf install libxml2-devel

External Packages Needed by the Server¶

OpenSSH¶

openssh-server: is needed by the netconfd-pro server for NETCONF over Secure Shell (SSH) support. This package may not be installed on some Linux systems.

The /etc/ssh/sshd_config file must be properly configured and the SSH server restarted before the netconfd-pro server will work. The configuration is covered in a section below.

Ubuntu version:

mydir> sudo apt-get install openssh-server

Fedora version:

mydir> sudo dnf install openssh-server

OpenSSL¶

openssl: is needed to enable netconfd-pro server and yangcli-pro client to communicate using Transport Layer Security (TLS). This package may not be installed on some Linux systems.

Certificates, /etc/yumapro/netconfd-pro.conf and /etc/yumapro/yangcli-pro.conf must be properly configured to use TLS. The configuration is covered in a section below.

Ubuntu version:

mydir> sudo apt-get install openssl-dev

Fedora version:

mydir> sudo dnf install openssl-devel

libcurl¶

libcurl: is needed by the netconfd-pro server to support <copy-config> to/from an FTP or TFTP URL. This package may not be installed on some Linux systems. If you are building the software from source code, this library is only required if the WITH_CURL=1 or EVERYTHING=1 make parameter is used. There are several Ubuntu variants of the libcurl4 package. The “gnutls” variant is shown below:

Ubuntu version:

mydir> sudo apt-get install libcurl4-gnutls-dev

Fedora version:

mydir> sudo dnf install libcurl-devel

libfcgi¶

libfcgi: is needed by the netconfd-pro server to support the RESTCONF protocol. This package may not be installed on some Linux systems. If you are building the software from source code, this library is only required if the WITH_RESTCONF=1 or EVERYTHING=1 make parameter is used.

Ubuntu version:

mydir> sudo apt-get install libfcgi-dev

Fedora version:

mydir> sudo dnf install fcgi-devel

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

The archived WEB site for FastCGI: FastCGI Archives

Download latest libfcgi: libfcgi 2.4.1

Build and install from the source (configure, make, make install)

External Packages Needed by the Client¶

The following packages are needed for the yangcli-pro client to function. If you are building YumaPro from source you will also need the associated developer packages.

libssh2¶

libssh2: is needed in order to connect to NETCONF servers using the SSH protocol. The developer version of this package. It is called libssh2-1-dev on DEB based systems and libssh2-devel on RPM based systems.

Ubuntu version:

mydir> sudo apt-get install libssh2-1-dev

Fedora version:

mydir> sudo dnf install libssh2-devel

CentOS 5 users may need to use the RPMForge repository to download libssh2 and libssh2-devel. For help with acquiring RPMForge please refer to the Centos Wiki

Users of Red Hat and CentOS version 8 and above may find libssh2 is not provided. Please refer this solution in this case.

ncurses¶

ncurses: is needed for some terminal support. This package is installed by the default Linux installation process. The developer version of this package is called libncurses5-dev on DEB based systems and ncurses-devel on RPM based systems.

Ubuntu version:

mydir> sudo apt-get install libncurses5-dev

Fedora version:

mydir> sudo dnf install ncurses-devel

zlib1g¶

zlib1g: is needed for data compression support, used by other libraries that YumaPro imports. This package is installed by the default Linux installation process. The developer version of this package. It is called zlib1g-dev on DEB based systems.

Ubuntu version:

mydir> sudo apt-get install zlib1g-dev

Fedora version:

mydir> sudo dnf install zlib-devel

YumaPro Packages¶

There are several variants of YumaPro SDK in binary form. The installation is similar for all packages.

Packages are organized by release train (e.g., 19.10, 20.10, 21.10).

The <version#> below is the release train version and release number of the package you choose.

In most cases the latest version of the SDK should be used.

For more information on choosing a package see: Which YumaPro Release Train Should I Use?

yumapro-sdk-<version#>
- This package contains the full SDK without POSIX pthreads supported
yumapro-pthreads-<version#>
- This package contains the full SDK with POSIX pthreads supported
yumapro-snmp-<version#>
- This package contains the full SDK with the Simple Network Management Protocol (SNMP) supported

There is also a package to install the YumaPro SDK documentation.

yumapro-doc-<version#>
- This package contains the YumaPro SDK documentation (except Linux “man” files).

Debian Packages¶

The Debian Packaging system is supported. Files with the ".deb" extension are Debian packages.

RPM Packages¶

The RPM Packaging system is supported. RPM packages are provided for selected platforms that do not support Debian Packages. Files with the ".rpm" extension are RPM packages.

Supported Linux Platforms and CPU Architectures

Each Linux-specific binary package (except yumapro-docs) is specific to a Linux distribution and CPU type.

The list of supported distributions and CPUs change over time. The current support is listed above, refer to Supported Distributions and Architectures

Installing YumaPro SDK Basic Binary Packages¶

Download the Correct YumaPro SDK Basic Package

In your browser navigate to Download YumaPro SDK Basic where you will find the list of currently available YumaPro SDK Basic Binary Packages.

Select the correct package for the operating system you are using. A new page will display the attributes of the package you have selected.

There is an option to sign up for the YumaPro User Newsletter that will provide you with ongoing information about YumaPro SDK Basic.

Select the Download button to begin the process of downloading your package. A license window will pop-up. Read the license to the end and an Accept Button will appear. Select the Accept Button and then select the new Download button. The standard Linux dialogue will then guide you to download the package.

Install the YumaPro SDK Basic Package¶

Navigate to the location where you saved the package. This will normally be in your ~/Downloads directory.

On Debian systems:

mydir> sudo dpkg -i yumapro-sdk-basic-20.10-12.2.u2004.amd64.deb

On RPM systems:

mydir> sudo dnf install yumapro-sdk-basic-20.10-12.2.fc34.x86_64.rpm

To quickly test the install run the server to just display its version:

> /usr/sbin/netconfd-pro --version

 Starting netconfd-pro...
 Copyright (c) 2008-2012, Andy Bierman, All Rights Reserved.
 Copyright (c) 2012-2021, YumaWorks, Inc., All Rights Reserved.

 netconfd-pro version 20.10-12.2-1fcb

 >

To see which files are installed in more detail refer to Appendix: Installed Files at the end of this document.

YumaPro SDK Basic Documentation¶

If you need to install the documentation go to the YumaPro SDK Basic Documentation section of Download YumaPro SDK Basic and download the documentation package that matches the operating system you are using.

Ubuntu version:

mydir> sudo dpkg -i yumapro-doc_20.10-12_all.deb

Fedora version:

mydir> sudo dnf install yumapro-doc-20.10-12.noarch.rpm

Installing YumaPro SDK Binary Packages¶

Download the Correct YumaPro Package

In your browser navigate to https://www.yumaworks.com/dld and login with the credentials YumaWorks provided to you.

Select a Package To Download

The root directory contains a number of directories, depending on your YumaPro license.

Documentation¶

docs

Contains the YumaPro SDK Documentation set for the latest release in each release train. The HTML and PDF files are provided here for WEB access. Use the yumapro-doc package to install the complete document set.

There is a sub-directory here for each release train, back to 17.10. Choose the directory that matches the release train you need. There are "html" and "pdf" directories In each release-train directory.

training

Contains some NETCONF and YANG tutorial information.

yumapro-doc

Contains an archive of YumaPro SDK Documentation packages. There is a directory for each release (e.g. 21.10-2). There are RPM and Debian packages in each folder.

Binary SDK Variants¶

There are several yumapro folders with the same structure.

There is a directory for each release (e.g. 21.10-3). There is a directory for each platform in this directory (e.g., u1804). Select the package based on the required CPU architecture (e.g. amd64).

The following packages are available:

yumapro-gnmi
- Contains the yp-gnmi server distribution
yumapro-pthreads
- Contains YumaPro SDK packages. This version is multi-threaded and requires POSIX Threads. Contains the yp-client Programming Libraries.
yumapro-sdk
- Contains the YumaPro SDK packages. This version is single threaded and does not use POSIX Threads.
yumapro-sdk-basic
- Contains the YumaPro SDK Basic packages. This version is single threaded and does not use POSIX Threads.
yumapro-snmp
- Contains the yp-snmp server distribution
yumapro-tools
- Contains the YumaPro SDK tools package This version is multi-threaded and requires POSIX Threads. Contains the yp-client Programming Libraries.

Install the Package¶

On Debian systems:

mydir> sudo dpkg -i yumapro-sdk-21.10-3.u1804.amd64.deb

On RPM systems:

mydir> sudo dnf install yumapro-sdk-21.10-3.fc34.x86_64.rpm

To quickly test the install run the server to just display its version:

> /usr/sbin/netconfd-pro --version

 Starting netconfd-pro...
 Copyright (c) 2008-2012, Andy Bierman, All Rights Reserved.
 Copyright (c) 2012-2021, YumaWorks, Inc., All Rights Reserved.

 netconfd-pro version 21.10-3-3fcf

 >

To see which files are installed in more detail refer to Appendix: Installed Files at the end of this document.

If you need to install the documentation go to yumapro-doc and download the documentation that matches the version and release number of the SDK package you installed.

Ubuntu version:

mydir> sudo dpkg -i yumapro-doc_17.10-1_all.deb

Fedora version:

mydir> sudo dnf install yumapro-doc-17.10-1.noarch.rpm

Installing YumaPro SDK from Source Code¶

To install YumaPro SDK from source files make sure you have installed the developer versions of the External Packages listed previously. Navigate to the YumaPro top level directory. You will find the file "README" that describes how to build YumaPro SDK and the build variables available. Below is an example. It is best to build, install, and if needed uninstall using the same build variables.

mydir> make EVERYTHING=1 USE_WERROR=1 DEBUG=1

mydir> sudo make install EVERYTHING=1 USE_WERROR=1 DEBUG=1

Note

If you have Server source code (e.g., yumapro-server2) you will not have access to the yangcli-pro/yp-shell source code and as such EVERYTHING=1 will not work.

You should: substitute EVERYTHING=1 for the features you want to include such as WITH_RESTCONF=1.

Refer to the YumaPro Source Code Guide for more details.

Uninstalling YumaPro SDK¶

If you need to uninstall YumaPro SDK see the article: How do I remove YumaPro SDK from my system?

Removing Files Not Needed By The Server¶

Installing yumapro-sdk and yumapro-pthreads SDK packages includes host platform developer tools that are not used by the server on a runtime platform. To remove these files see the article: Removing Files Not Needed by the Server

Configure SSH¶

To use the server you must modify the /etc/ssh/sshd_config file and add the netconf subsystem to the file. From a terminal edit the file:

Use any text editor. In this example 'emacs' is used.

mydir> sudo emacs /etc/ssh/sshd_config

Add the following commands to this file (Port 22 will probably already exist in the file though it may be commented out).

Port 22

Port 830

Subsystem netconf /usr/sbin/netconf-subsystem-pro

Installing SSH keys¶

YumaPro SDK provides support for SSH keys. If you do not have SSH keys installed already the easiest way to install these is as follows:

mydir> ssh-keygen

Generating public/private rsa key pair.
Enter file in which to save the key (/<your_$HOME>/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /<your_$HOME>/.ssh/id_rsa.
Your public key has been saved in /<your_$HOME>/.ssh/id_rsa.pub.
The key fingerprint is:
...

Note

You will be asked if you want to store the keys somewhere other than the standard location.

You will also be asked if you want to enter a passphrase. If you enter a passphrase you will need to provide that passphrase each time you connect to the server.

This process creates a public and a private key. The public key needs to be placed on the server. The easiest way to do this is with ssh-copy-id. The output should look something like this:

mydir> ssh-copy-id <your_username>@<server’s_IP_address>

/usr/bin/ssh-copy-id: INFO: attempting to log in with the new key(s), to
filter out any that are already installed

/usr/bin/ssh-copy-id: INFO: 1 key(s) remain to be installed -- if you
are prompted now it is to install the new keys

Number of key(s) added: 1

Now try logging into the machine, with: "ssh '<username>@<server>'" and check to make sure that only the key(s) you wanted were added.

If you have not connected to the server before you may be asked to confirm it is OK to connect to the server.

You should validate that everything worked by using ssh to connect to the server as the output from ssh-copy-id suggests.

If you do not have ssh-copy-id on your system there are other ways to put the public key on the server. Consult with your sys-admin the preferred way to do this.

SELinux Security Configuration¶

For SELinux systems like CentOS and Fedora you must configure SELinux to allow the port and subsystem changes. Edit the SELinux configuration file, show below, and change SELINUX from "enforcing" to “permissive”. Then reboot the system.

Fedora version:
mydir> sudo <your_editor> /etc/selinux/config

SELINUX=permissive

mydir> sudo reboot

Note

Check with your system administrator for the network security policies that are required for the server. A “permissive” SELinux level could be too lax for your network policy.

Restart the SSH Server¶

Restart the SSH Server with the following commands:

Ubuntu version:

mydir> sudo service ssh restart

Fedora version:

mydir> sudo service sshd restart

Note

SELinux systems usually do not start sshd on reboot so you will need to restart it each time you reboot your system or have it started with your system initialization.

Start netconfd-pro¶

Next start the netconfd-pro server:

mydir> netconfd-pro --log-level=debug4 --access-control=off

There are many parameters you can use to tune the server to perform the way you desire. The two parameters shown above start the server with the most verbose debug message level to let you monitor what the server is doing and disabling the access-control so you can manipulate the YANG data without having to setup NETCONF Access Control.

For more information of log-level see: What is the--log-level parameter and how is it used?

For more information on the netconfd-pro server command line parameters refer to the YumaPro CLI Reference.

Server Startup Issues¶

If you have previously run the netconfd-pro server and you see the message below the server is either still running in another process or was not shut down cleanly the last time it ran. Either stop the other server running or follow the instructions in the message to clean up the files left by the previous run.

Error: program netconfd-pro appears to be running as PID 5125
Error: Cannot create PID file
*** If no other instances of netconfd-pro are running,
*** try deleting /tmp/ncxserver.sock and $HOME/.yumapro/netconfd-pro.pid
***   > rm /tmp/ncxserver.sock
***   > rm $HOME/.yumapro/netconfd-pro.pid

netconfd-pro: init returned (operation failed)
Server Cleanup Starting...

mydir> sudo rm /tmp/ncxserver.sock
rm: cannot remove '/tmp/ncxserver.sock': No such file or directory
mydir> sudo rm $HOME/.yumapro/netconfd-pro.pid

yangcli-pro Connect¶

In a separate terminal window start the yangcli-pro client:

mydir> yangcli-pro

The login message from yangcli-pro will be displayed followed by the command prompt “>”. Part of the login message displays some of the help and command completion options available:

  yangcli-pro version 21.10-3
  libssh2 version 1.8.0

  Copyright (c) 2008-2012, Andy Bierman, All Rights Reserved.
  Copyright (c) 2012-2021, YumaWorks, Inc., All Rights Reserved.

  Type 'help' or 'help <command-name>' to get started
  Use the <tab> key for command and value completion
  Use the <enter> key to accept the default value in brackets

  These escape sequences are available when filling parameter values:

        ?        help
        ??        full help
        ?s        skip current parameter
        ?se        skip rest of optional parameters
        ?c        cancel current command

  These assignment statements are available when entering commands:

        $<varname> = <expr>        Local user variable assignment
        $$<varname> = <expr>        Global user variable assignment
        @<filespec> = <expr>        File assignment

>

Connect to the server:

E.g., for user 'admin' and password 'mypassword' (substitute your system login credentials as necessary):

> connect server=localhost user=admin password=mypassword

If the connection is successful, the session capabilities from the server will be reported. This information can be shown at any time with the show session command.

This example shows a successful session startup:

NETCONF 1.1 session established for andy on localhost

Client Session Id: 1
Server Session Id: 3

Server Protocol Capabilities
   base:1.0
   base:1.1
   candidate:1.0
   confirmed-commit:1.0
   confirmed-commit:1.1
   interleave:1.0
   notification:1.0
   partial-lock:1.0
   rollback-on-error:1.0
   url:1.0
   validate:1.0
   validate:1.1
   with-defaults:1.0
   xpath:1.0
   yang-library:1.0

Server Module Capabilities
   ietf-netconf@2011-06-01
      Features:
         candidate
         confirmed-commit
         rollback-on-error
         validate
         url
         xpath
   iana-crypt-hash@2014-08-06
      Features:
         crypt-hash-md5
         crypt-hash-sha-256
         crypt-hash-sha-512
   ietf-inet-types@2013-07-15
   ietf-netconf-acm@2018-02-14
   ietf-netconf-monitoring@2010-10-04
   ietf-netconf-notifications@2012-02-06
   ietf-netconf-partial-lock@2009-10-19
   ietf-netconf-with-defaults@2011-06-01
   ietf-restconf@2017-01-26
   ietf-restconf-monitoring@2017-01-26
   ietf-yang-library@2016-06-21
   ietf-yang-patch@2017-02-22
   ietf-yang-structure-ext@2020-06-17
   ietf-yang-types@2013-07-15
   nc-notifications@2008-07-14
   notifications@2013-03-15
   yang-data-ext@2017-07-03
   yuma-app-common@2017-07-25
   yuma-ncx@2015-10-16
   yuma-system@2013-07-15
   yuma-time-filter@2012-11-15
   yuma-types@2019-11-29
   yumaworks-app-common@2021-08-24
   yumaworks-event-filter@2014-02-09
   yumaworks-event-stream@2021-05-15
   yumaworks-extensions@2021-12-14
   yumaworks-getbulk@2021-08-07
   yumaworks-ids@2014-07-12
   yumaworks-restconf@2017-07-03
   yumaworks-support-save@2017-07-27
   yumaworks-system@2021-08-24
   yumaworks-templates@2017-02-20
   yumaworks-term-msg@2019-05-05
   yumaworks-types@2021-05-15

Server Enterprise Capabilities
   urn:yumaworks:params:xml:ns:netconf:config-id?id=69221

Protocol version set to: RFC 6241 (base:1.1)
Default target set to: <candidate>
Save operation mapped to: commit
Default with-defaults behavior: explicit
Additional with-defaults behavior: trim,report-all,report-all-tagged
YANG library set to: 1.0 (RFC 7895)
module-set-id: 4430

andy@localhost>

If you experience problems connecting to the server see the article: Cannot Connect to the Server

You can now issue some commands to display YANG data, such as:

> sget /netconf-state/sessions

   Filling container /netconf-state/sessions:
RPC Data Reply 5 for session 3 [default]:

rpc-reply {
  data {
    netconf-state {
      sessions {
        session  3 {
          session-id 3
          transport ncm:netconf-ssh
          username <your-username>
          source-host 127.0.0.1
          login-time 2018-11-20T07:00:17Z
          in-rpcs 4
          in-bad-rpcs 0
          out-rpc-errors 0
          out-notifications 0
        }
      }
    }
  }
}

With each command issued from yangcli-pro you will be able to see the corresponding debug information displayed from the server in the terminal window in which the server is running.

For more information on yangcli-pro and the commands available see yumapro-yangcli-manual.pdf or the HTML version of the manual located at: YumaPro yangcli-pro Manual

To exit yangcli-pro type "quit":

To exit the server type <Ctrl>-c in the window it is ruining in.

Configure TLS¶

To enable Transport Layer Security (TLS) between the server and client you need to setup both the server and the client with appropriate certificates and configuration. The following instructions walk you through the setup process.

Server TLS Setup¶

On the server create 2 directories for working with the certificates and copy the generate-keys.sh script to the buildcerts directory that was just created:

mydir> mkdir $HOME/buildcerts
mydir> mkdir $HOME/certs
mydir> cp /usr/share/yumapro/util/generate-keys.sh $HOME/buildcerts

Change directory to the buildcerts directory, run the key generation script and check the files were created:

mydir> cd buildcerts
buildcerts> ./generate-keys.sh

buildcerts> ls -l

-rw-rw-r-- 1 andy andy  956 Mar 16 15:05 ca.crt
-rw-rw-r-- 1 andy andy  883 Mar 16 15:05 ca.csr
-rw-rw-r-- 1 andy andy 1708 Mar 16 15:05 ca.key
-rw-rw-r-- 1 andy andy   17 Mar 16 15:05 ca.srl
-rw-rw-r-- 1 andy andy  969 Mar 16 15:05 client.crt
-rw-rw-r-- 1 andy andy  891 Mar 16 15:05 client.csr
-rw-rw-r-- 1 andy andy 1708 Mar 16 15:05 client.key
-rwxrwxr-x 1 andy andy 1513 Feb 23 16:29 generate-keys.sh
-rw-rw-r-- 1 andy andy  969 Mar 16 15:05 server.crt
-rw-rw-r-- 1 andy andy  891 Mar 16 15:05 server.csr
-rw-rw-r-- 1 andy andy 1704 Mar 16 15:05 server.key

Generating Client Certificates with a SAN¶

A Subject Alternative Name (SAN) can be configured into a TLS X.509 certificate if the OpenSSL version supports X509v3. Customize the parameters within the script as needed. There are 2 example scripts for generating keys. The only difference is that the client.crt certificate is generated.

generate-keys.sh : plain client cert
generate-san-keys.sh : SAN client cert with IP, DNS, or Email type

The generate-keys.sh script will generate keys and certs for the “restconf” site. You can use the keys created by this script to setup TLS for your restconf site as described in Section 4 of this document.

Copy the certificates to their proper places:

buildcerts> sudo cp ca.crt /usr/local/share/ca-certificates/
buildcerts> cp server.crt ../certs/
buildcerts> cp server.key ../certs/
buildcerts> sudo update-ca-certificates
buildcerts> ls /etc/ssl/certs -l | grep ca.crt
lrwxrwxrwx 1 root root     39 Mar 16 15:52 ca.pem -> /usr/local/share/ca-certificates/ca.crt

The script update-ca-certificates uses the ca-certificates package. If you do not have this package on your system, then use the following steps, instead of the section above This could be the case if you are building a minimal footprint system.

This will create the required certificate links:

buildcerts> mkdir temp
buildcerts> sudo ln -s /usr/local/share/ca-certificates/ca.crt temp/ca.pem
buildcerts> sudo c_rehash temp
 Doing temp
buildcerts> sudo mv temp/* /etc/ssl/certs
buildcerts> ls -l /etc/ssl/certs | grep ca.pem
 lrwxrwxrwx 1 root root      6 Mar 16 08:00 56c899cd.0 -> ca.pem
 lrwxrwxrwx 1 root root      6 Mar 16 08:00 b2457b50.0 -> ca.pem
 lrwxrwxrwx 1 root root     39 Mar 16 08:00 ca.pem -> /usr/local/share/ca-certificates/ca.crt
buildcerts>

Generate the Client Fingerprint:

certs> cd $HOME/buildcerts
buildcerts> openssl x509 -noout -fingerprint -sha1 -inform pem -in client.crt

SHA1         Fingerprint=4B:A7:05:1E:12:F7:BC:FF:2D:9E:48:66:0A:8B:CC:D7:A5:65:E5:97

Check the Client Subject Alternate Name:

If the generate-san-keys.sh script is used then the SAN field should be set in the client.crt file. Use the following command the check it. For example, if the email address 'fred@example.com' was configured:

buildcerts> openssl x509 -noout -ext subjectAltName -in client.crt
X509v3 Subject Alternative Name:
   email:fred@example.com
buildcerts>

Create the --cert-usermap Parameter

Note

The yumaworks-cert-usermap.yang module can now be used to configure Certificate to User Identity Mappings defined in RFC 7589. Refer to NETCONF Over TLS for additional details on using this module.

The --cert-usermap parameter is supported by netconfd-pro to map a user-name to a client fingerprint.

The parameter has the form:

<YOUR_USERNAME>@<SHA1_Fingerprint>

For example if user=andy creates the SHA1 Fingerprint then the cert-usermap parameter line should be:

cert-usermap andy@4B:A7:05:1E:12:F7:BC:FF:2D:9E:48:66:0A:8B:CC:D7:A5:65:E5:97

Note

Even though the CLI parameter will accept as few as 6 pairs of digits, the full fingerprint value should be used.

Add the --cert-usermap Parameter to the Server Configuration File

The default server configuration file is /etc/yumapro/netconfd-pro.conf. It can be different on some platforms, It can also be changed with the --config CLI parameter.

netconfd-pro {

    with-netconf-tls true
    netconf-tls-certificate ~/certs/server.crt
    netconf-tls-key ~/certs/server.key

    # use the parameter you created in the previous step, not this string
    cert-usermap andy@4B:A7:05:1E:12:F7:BC:FF:2D:9E:48:66:0A:8B:CC:D7:A5:65:E5:97
}

Client TLS Setup¶

Generate Keys

On the client create 2 directories for working with the certificates:

CLIENT:

mydir> mkdir $HOME/buildcerts

mydir>mkdir $HOME/certs

Copy Keys to Server

On the server copy the files you created to the client machine using sftp:

SERVER:

mydir> cd $HOME/buildcerts
buildcerts> sftp CLIENT_USERNAME@CLIENT
sftp> cd buildcerts
sftp> put *
sftp> bye

Now copy the certificates on the client to their proper places:

CLIENT:

mydir> cd $HOME/buildcerts
buildcerts> sudo cp ca.crt /usr/local/share/ca-certificates
buildcerts> cp client.crt $HOME/certs/
buildcerts> cp client.key $HOME/certs/

Go to the /etc/ssl/certs directory, run updates and check the results:

CLIENT:

buildcerts> cd /etc/ssl/certs
certs> sudo update-ca-certificates

certs> ls -l | grep ca.crt

lrwxrwxrwx 1 root root     39 Mar 16 16:25 ca.pem -> /usr/local/share/ca-certificates/ca.crt

Add yangcli-pro CLI Parameters for TLS

The parameters needed to use TLS must be added to the yangcli-pro.conf file.

If you have an existing yangcli-pro.conf then add the two parameter lines to the existing file. If you do not have an existing yangcli-pro.conf file then one needs to be created. The default is /etc/yumapro/yangcli-pro.conf but this can be changed with the --config CLI parameter.

yangcli-pro {

    ssl-certificate ~/certs/client.crt
    ssl-key ~/certs/client.key
}

Test the TLS Connection¶

Use the yangcli-pro Connect procedure to test the TLS connection run the server as you would normally.

If the client TLS keys are configured so no password is required, then the "no-password" parameter can be used in the "connect" command:

Example connect command (for user 'andy' connecting to 192.168.1.20):

> connect user=andy server=192.168.1.20 no-password transport=tls

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.

Required Packages for NGINX¶

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 prior to installing NGINX:

Stop the existing WEB server process.

Ubuntu Example:

mydir> sudo service apache2 stop

Fedora Example:

mydir> sudo service httpd stop

OR remove the existing WEB server entirely.

Ubuntu Example:

mydir> sudo apt-get remove apache2

Fedora Example:

mydir> sudo dnf remove httpd

OR 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

Example NGINX configuration file:

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

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

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

The following config file is installed as /usr/share/yumapro/util/restconf-nginx. Copy this file to the /etc/nginx/sites-available/restconf, or to whichever location you choose to serve NGINX sites from.

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

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.

Setup TLS Certificates for the 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 edit the /etc/apache2/sites-available/restconf.conf site configuration file and uncomment the optional TLS configuration block shown below:

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

#

# Uncomment this block to enable RESTCONF over TLS

#

Restart the WEB Server¶

To restart the Apache Server follows the steps:

Ubuntu version:

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

To restart the NGINX Server follows the steps:

Ubuntu version:

mydir> sudo service nginx 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 nginx start

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

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

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
   }
  ]
 }

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

yp-shell – adding a CLI¶

Configure the optional yp-shell Command Line Interface (CLI).

Note

yp-shell is not available with YumaPro SDK Basic.

Pre-Requisites for Using yp-shell¶

You should have completed “3 Installing YumaPro SDK”. If you have installed YumaPro SDK with a binary package then the CLI is included.

If the SDK is installed from source code then the EVERYTHING=1 or WITH_CLI=1 build variables need to be used.

Add yp-shell to the /etc/shells File¶

The file /etc/shells must be edited with root access. The line /usr/bin/yp-shell needs to be added anywhere.

mydir> sudo <your_editor> /etc/shells

The following example file shows yp-shell added at the end:

mydir> cat /etc/shells
# /etc/shells: valid login shells
/bin/sh
/bin/dash
/bin/bash
/bin/rbash
/usr/bin/yp-shell

Change the Shell for the Login User to yp-shell¶

The user(s) that will be used to login to the OpenSSH server need to be created. In this example the user 'cli' is being created (the -m option creates a home folder for the new user):

mydir> sudo useradd -m --shell /usr/bin/yp-shell cli

Next create a password for the new user:

mydir> sudo passwd cli

Enter new UNIX password:

Retype new UNIX password:

passwd: password updated successfully

If the user account already exists, then use the chsh command instead:

Ubuntu version:

mydir> sudo chsh --shell /usr/bin/yp-shell cli

Fedora version:

mydir> sudo usermod -s /usr/bin/yp-shell cli

Note

"chsh" dictates that the user can ONLY use the specified shell. Therefore DO NOT perform this command on a user that needs to access a bash terminal or any other type of shell other than yp-shell.

Client Connect to yp-shell¶

The system may need to be rebooted to activate the new shell.

Start the netconfd-pro server, the CLI must be enabled (it is by default).

A normal SSH login will invoke the yp-shell program when the user logs into the system. The "motd" program may generate a welcome screen, or there may just be a prompt present. By default, no information is generated.

extdir> ssh  cli@192.168.1.9

cli@u16-vm>

At this point only yp-shell command are allowed. The user does not have access to any system commands.

The "tab" key will show all the commands available from both yp-shell and the server.

cli@lu16-vm>
action                exit                  lock*                 show
alias                 gc                    merge                 shutdown*
aliases               get*                  mgrload               terminal
backup*               get-bulk*             no-op*                unload*
cancel-commit*        get-config*           nvsave                unload-bundle*
clear                 get-ha-status*        quit                  unlock*
clear-eventlog*       get-module-tags*      recall                unset
commit*               get-schema*           refresh-backup-dir*   update-config
config                get-support-save*     remove                validate*
copy-config*          get-walk              remove-all            xget
create                get2                  replace               xget-config
delete                gr                    restart*              xget-data
delete-all            help                  restore*              ypsys:load*
delete-backup*        history               save                  ypsys:set-log-level*
delete-config*        insert                sget                  ysys:load*
discard-changes*      kill-session*         sget-config           ysys:set-log-level*
edit-config*          load-bundle*          sget-data
cli@lu16-vm>

Many yangcli-pro commands such as "sget" are available in yp-shell:

cli@lu16-vm> sget /netconf-state/sessions

Filling container /netconf-state/sessions:
RPC Data Reply 3 for session 3 [default]:

rpc-reply {
  data {
    netconf-state {
      sessions {
        session  3 {
          session-id 3
          transport yid:netconf-cli
          username cli
          source-host 127.0.0.1
          login-time 2018-11-20T07:27:30Z
          in-rpcs 2
          in-bad-rpcs 0
          out-rpc-errors 0
          out-notifications 0
        }
      }
    }
  }
}

The two CLIs are very similar, the main difference is yp-shell is connected directly to the server it runs on and so does not have commands to create sessions to multiple servers.

To see the differences between yp-shell and yangcli-pro CLIs see the article: What is the difference between yp-shell in netconfd-pro and yangcli-pro?

Appendix: Installed Files¶

This section describes all the files and/or directories installed by the YumaPro packages.

Release Notes¶

/usr/share/yumapro/ReleaseNotes directory contains all the detailed release notes for the entire release train.

YANG Modules¶

/usr/share/yumapro/modules directory contains all the YANG modules:
- ietf/
- mib/
- netconfcentral/
- test/
- yumaworks/

Shared Libraries¶

This section describes the shared libraries needed for the server to operate.

/usr/lib/ directory contains the NCX and AGT libraries.

/usr/lib64/ is used for Fedora and CentOS 64-bit systems.
- libyumapro_ncx.so.
- libyumapro_agt.so.
- libyumapro_db-api.so.
- libyumapro_sil-sa.so.
- libyumapro_ycontrol.so.
- libyumapro_mgr.so.
- libyumapro_subsys-pro.so.
- libyumapro_ycli.so.
/usr/lib/yumapro directory contains the following files:

/usr/lib64/yumapro for Fedora and CentOS 64-bit systems
- libget2-test.so
- libhooks-test.so
- libietf-interfaces.so
- libietf-restconf-monitoring.so
- libietf-yang-library.so
- libif-linux.so
- libsil-error.so
- libtoaster.so
- libyp_system-example.so
- libyuma-arp.so
- libyuma-interfaces.so
- libyuma-mysession.so
- libyuma-proc.so
- libyumaworks-server.so

Binary Programs¶

This section describes the binary programs installed.

/usr/bin directory contains the following programs:
- db-api-app
- make_sil_bundle
- make_sil_dir_pro
- make_sil_sa_bundle
- make_sil_sa_dir
- sil-sa-app
- support-save-app
- yangcli-pro
- yangdiff-pro
- yangdump-pro
- yangdump-sdk
- ypcontrol
- yp-ha-app
- yp-shell
- ypwatcher
/usr/sbin directory contains the following server programs:
- netconfd-pro
- netconf-subsystem-pro
- restconf

User Manual Pages¶

/usr/share/man/man1 directory contains the following files:
- db-api-app.1.gz
- make_sil_bundle.1.gz
- make_sil_dir_pro.1.gz
- make_sil_sa_bundle.1.gz
- make_sil_sa_dir.1.gz
- netconfd-pro.1.gz
- netconf-subsystem-pro.1.gz
- restconf.1.gz
- sil-sa-app.1.gz
- support-save-app.1.gz
- yangcli-pro.1.gz
- yangdiff-pro.1.gz
- yangdump-pro.1.gz
- yangdump-sdk.1.gz
- ypcontrol.1.gz
- yp-ha-app.1.gz
- yp-shell.1.gz
- ypwatcher.1.gz

User Documentation¶

/usr/share/doc/yumapro directory contains the following files:
- index.html
/usr/share/doc/yumapro/pdf directory containing the following files:
- yumapro-installation-guide.pdf
- yumapro-quickstart-guide.pdf
- yumapro-user-cmn-manual.pdf
- yumapro-netconfd-manual.pdf
- yumapro-yangcli-manual.pdf
- yumapro-ypclient-manual.pdf
- yumapro-yangdiff-manual.pdf
- yumapro-yangdump-manual.pdf
- yumapro-dev-manual.pdf
- yumapro-api-quickstart-guide.pdf
- yumapro-ypsystem-api-guide.pdf
- yumapro-ypshow-api-guide.pdf
- yumapro-yocto-quickstart-guide.pdf
- yumapro-ypsnmp-manual.pdf
/usr/share/doc/yumapro/html directory containing the HTML files for all the manuals

Sample Configuration Files¶

/etc/yumapro directory contains the following sample configuration files:
- yangcli-pro-sample.conf
- yangdiff-pro-sample.conf
- yangdump-pro-sample.conf
- netconfd-pro-sample.conf
- snmpd.conf

Developer Files¶

/usr/include/yumapro directory contains H files needed to compile SIL code so it can be loaded into the server at runtime.
- ncx/*.h
- agt/*.h
- db-api/*.h
- mgr/*.h
- platform/procdefs.h
- sil-sa/*.h
- ycli/*.h
- ycontrol/*.h
/usr/share/yumapro/src/libtoaster directory is an example of a SIL implementation, with the following contents:
- Makefile
- src directory
  - Makefile
  - toaster.c
  - toaster.c.start
  - toaster.h
  - toaster.h.start
- bin directory
- lib directory
/usr/share/yumapro/src/libsystem directory is an example of a user external system API (yp-system) library with the following contents:
- Makefile
- src directory
  - Makefile
  - example-system.c
  - example-system.h
- bin directory
- lib directory
/usr/share/yumapro/src/sil-error directory in an example of a SIL library that can be used to force errors during editing transactions to help test corner-case error handling. It has the following contents:
- Makefile
- src directory
  - Makefile
  - sil-error.c
  - sil-error.h
- bin directory
- lib directory
/usr/share/yumapro/src/get2-test directory in an example of a SIL-SA library that shows examples of “get2” callback functions for the module get2-test.yang. It has the following contents:
- Makefile
- src directory
  - Makefile
  - get2-test.c
  - get2-test.h
- bin directory
- lib directory
/usr/share/yumapro/src/libif-mib directory is an example of the IF-MIB converted to YANG library that includes SIL code with the following contents:
- Makefile
- src directory
  - Makefile
  - IF-MIB.c
  - IF-MIB.h
- bin directory
- lib directory
/usr/share/yumapro/src/sil-sa-app directory is an example of Server Instrumentation Library for Sub-Agent (SIL-SA) application. A SIL-SA application runs as a separate sub-agent process within the same system as the netconfd-pro server. It is used for asynchronous server callbacks.
- Makefile
- main.c
/usr/share/yumapro/util directory contains the following files and directories.
- errmsg-lang/
- errmsg-tr.py
- generate-keys.sh
- host-meta
- makefile.sil
- makefile.sil-sa
- makefile-top.sil
- restconf.conf
- restconf-nginx.conf
/usr/share/yumapro/src/yp-client

Note

This directory will only be present if you are using a PTHREADS version of YumaPro SDK, either a binary containing the name yumapro-pthreads- or built from source with PTHREADS=1 as a parameter supplied to make.

If present the directory will contain the following yp-client C++ client library examples, each in their own directory:

c-toaster directory

c-toaster.c

Makefile

README

capabilities directory

capabilities.cpp

Makefile

README

libtest directory

libtest.cpp

Makefile

README

sget-system directory

sget-system.cpp

Makefile

README

toaster directory

toaster.cpp

Makefile

README

README

License and Packaging Information¶

/usr/share/doc/yumapro directory containing the following files:
- AUTHORS
- README
- yumapro-legal-notices.pdf
- <package-license-file>.pdf
/usr/share/doc/<package-name> directory containing the following files.
- copyright
- changelog.Debian

Note

This directory is only created by Ubuntu:

Appendix: Next Steps¶

After Installation you can start learning more about YumaPro SDK with a set of lessons can be found on the YumaWorks Knowledge Base: Server Developer – Getting Started

KnowledgeBase¶

YumaWorks hosts a Knowledge Base with solutions to many Frequently Asked Questions (FAQs) located at: KnowledgeBase

The Knowledge Base has the following sections:

General
netconfd-pro
yangcli-pro
YANG
Server Developer

Unix ‘man’ pages¶

The unix 'man' program can be used to get documentation about each program. For example:

man yangcli-pro
man yangdump-pro
man yangdump-sdk
man yangdiff-pro
man netconfd-pro
man netconf-subsystem-pro
man make_sil_dir_pro
man make_sil_bundle
man make_sil_sa_dir
man make_sil_sa_bundle
man ypcontrol
man yp-shell
man ypwatcher
man yang-api
man restconf
man ypgnmi-app
man ypgrpc-go-app
man yp-ha-app
man db-api-app
man sil-sa-app

Program --help option¶

Each program also has extensive help information available with the --help CLI parameter. For example:

yangcli-pro --help
yangdump-pro --help
yangdiff-pro --help
netconfd-pro --help

YumaPro Installation Guide¶

Supported Distributions and Architectures¶

Package Pre-requisites¶

External Package Needed by the Server and Client¶

libxml2¶

External Packages Needed by the Server¶

OpenSSH¶

OpenSSL¶

libcurl¶

libfcgi¶

External Packages Needed by the Client¶

libssh2¶

ncurses¶

zlib1g¶

YumaPro Packages¶

Debian Packages¶

RPM Packages¶

Installing YumaPro SDK Basic Binary Packages¶

Install the YumaPro SDK Basic Package¶

YumaPro SDK Basic Documentation¶

Installing YumaPro SDK Binary Packages¶

Documentation¶

Binary SDK Variants¶

Install the Package¶

Installing YumaPro SDK from Source Code¶

Uninstalling YumaPro SDK¶

Removing Files Not Needed By The Server¶

Configure SSH¶

Installing SSH keys¶

SELinux Security Configuration¶

Restart the SSH Server¶

Start netconfd-pro¶

Server Startup Issues¶

yangcli-pro Connect¶

Configure TLS¶

Server TLS Setup¶

Generating Client Certificates with a SAN¶

Client TLS Setup¶

Test the TLS Connection¶

RESTCONF Installation¶

Apache Support¶

Required Packages for Apache¶

Configuring the Apache Server¶

NGINX Support¶

Required Packages for NGINX¶

Configuring the NGINX Server¶

Setup TLS Certificates for the RESTCONF Site¶

Restart the WEB Server¶

HTTP Connect¶

yp-shell – adding a CLI¶

Pre-Requisites for Using yp-shell¶

Add yp-shell to the /etc/shells File¶

Change the Shell for the Login User to yp-shell¶

Client Connect to yp-shell¶

Appendix: Installed Files¶

Release Notes¶

YANG Modules¶

Shared Libraries¶

Binary Programs¶

User Manual Pages¶

User Documentation¶

Sample Configuration Files¶

Developer Files¶

License and Packaging Information¶

Appendix: Next Steps¶

KnowledgeBase¶

More Documentation¶

Unix ‘man’ pages¶

Program --help option¶