../_images/logo.png

YumaPro Docker User Guide

YumaPro Dockers contain ready-to-use YumaPro applications pre-installed and configured in a Docker container running Ubuntu.

Warning

YumaPro Docker containers are provided for users to quickly start using, and become familiar with, YumaPro applications in a preinstalled environment. They are NOT intended for production deployment.

YumaPro SDK Eval Docker provides a full Software Development Kit for developing and testing YANG models. It features:

  • netconfd-pro: a professional-grade server that provides NETCONF, RESTCONF, and Call Home protocols along with TLS and SSH support. It has multiple datastore capabilities, is NETCONF v1.0 and v1.1, as well as YANG v1.0 and v1.1 compliant.

  • yangcli-pro: a CLI-based client that can connect to multiple NETCONF and RESTCONF servers. It features automatic edit testing on specified objects, customized command line behavior, validation of YANG content, and NETCONF notification support.

  • yangdump-pro: a YANG compiler for automatic code generation from YANG modules, either standards-based or ones you have created. All other YumaPro SDK development tools are also included.

Diagram of YumaPro SDK Docker in a Host System

../_images/YumaPro-Docker.png

Prerequisites for Using YumaPro Docker

Installation of the Docker environment is required on your host system to enable the use of YumaPro Docker images. The links below, based on the operating system you will be using, provide Docker installation instructions. There are many other examples that can be found on the Internet:

Installing YumaPro Docker

To access to the YumaPro SDK Eval Docker image from our secure download site, please contact us today.

Once the image is downloaded and placed in your desired directory, run the command below from that directory to place the YumaPro Docker in your system’s Docker environment:

> sudo docker load -i yumapro-sdk-eval-docker.tar
Loaded image: yumapro-sdk-eval-docker:latest

How to Use YumaPro Docker

Once Docker completes its load operation of the YumaPro SDK Eval Docker image, the user can start the Docker container using the command shown below and should see the output

> sudo docker run -it yumapro-sdk-eval-docker


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

netconfd-pro version 23.10-6-EVAL-13fcf (23.6.0)

Starting netconfd-pro server in the background with basic parameters..
Refer to docker-logs/netconfd-docker.log file for logging information.
user-1@d49158b992f5:~$

A few system services are started when the Docker container starts, including ssh, Apache2, etc. The user may install and start more system services or load additional files into the Docker.

The NETCONF server, netconfd-pro, is started at the container run-time with the following parameters:

To change these parameters or any other configuration parameters, the default --config file needs to be created. This is located at /etc/yumapro/netconfd-pro.conf.

However, there is no default config file initially. You need to first copy the sample config file to the real config file name.

> sudo cp /etc/yumapro/netconfd-pro-sample.conf /etc/yumapro/netconfd-pro.conf

For more details and examples on how to use 'netconfd-pro', refer to the YumaPro netconfd-pro Manual.

Warning

YumaPro Docker images, like any other Docker images, are a snapshot of a running system. ANY changes you make to the Docker while it is running, whether adding applications, files, or configuration changes, will be LOST if you just exit the Docker.

You can retain changes you would like to make to the Docker - see the section below: Clone the YumaPro Docker.

Now the Docker has started, follow the sections below to become familiar with YumaPro SDK Eval.

For the first test run yangcli-pro, the YANG based Command Line Interface (CLI) client, to test the netconfd-pro server is running and you can connect to it by connecting to the server and displaying some data using the 'sget' command:

user-1@d49158b992f5:~$ yangcli-pro

  yangcli-pro version 23.10-6-EVAL (23.6.0)
  libssh2 version 1.10.0

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

  Online user manual:
  https://docs.yumaworks.com/en/latest/yangcli/index.html

  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 server=localhost user=user-1 password=password-1


NETCONF 1.1 session established for user-1 on localhost

Client Session Id: 1

   ...   [output omitted for clarity]

YANG library set to: 1.0 (RFC 7895)
module-set-id: 4458

user-1@localhost>

user-1@localhost> sget /netconf

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

rpc-reply {
  data {
    netconf {
      streams {
        stream  NETCONF {
          name NETCONF
          description 'default NETCONF event stream'
          replaySupport true
          replayLogCreationTime 2024-01-01T00:00:00.000001Z
        }
      }
    }
  }
}

user-1@localhost>

Next use yangcli-pro to load the ietf-interfaces.yang module to the server, with a copy for the client, and then query the server interface statistics:

user-1@localhost> ysys:load ietf-interfaces

RPC Data Reply 4 for session 5 [default]:

rpc-reply {
  mod-revision 2018-02-20
}

user-1@localhost> mgrload ietf-interfaces

Load module 'ietf-interfaces' OK

user-1@localhost>

user-1@localhost> sget /interfaces-state

Filling container /interfaces-state:
RPC Data Reply 3 for session 6 [default]:

rpc-reply {
  data {
    interfaces-state {
      interface  lo {
        name lo
        admin-status up
        oper-status up
        if-index 1
        phys-address 00:00:00:00:00:00
        speed 0
        statistics {
          in-octets 106252
          in-unicast-pkts 270
          in-multicast-pkts 0
          in-discards 0
          in-errors 0
          out-octets 106252
          out-unicast-pkts 270
          out-discards 0
          out-errors 0
        }
      }
    }
  }
}

user-1@localhost>

If you repeat the yangcli-pro command 'sget /interfaces-state' you will notice the interface statistics changing. Depending on the interface usage it may require more than one repeat of the command to produce a change.

For more details and examples on how to use 'yangcli-pro', refer to the YumaPro yangcli-pro Manual.

RESTCONF on Docker

Next use the command 'quit' to exit yangli-pro. Use the 'curl' command-line tool to access the URL shown below to display the same ietf-interface data this time using RESTCONF:

user-1@localhost> quit

user-1@d49158b992f5:~$ curl http://localhost/restconf/data/interfaces-state
{
 "ietf-interfaces:interfaces-state": {
  "interface": [
   {
    "name":"lo",
    "admin-status":"up",
    "oper-status":"up",
    "if-index":1,
    "phys-address":"00:00:00:00:00:00",
    "speed":"0",
    "statistics": {
     "in-octets":"108179",
     "in-unicast-pkts":"282",
     "in-multicast-pkts":"0",
     "in-discards":0,
     "in-errors":0,
     "out-octets":"108179",
     "out-unicast-pkts":"282",
     "out-discards":0,
     "out-errors":0
    }
   }
  ]
 }
}

Again, repeating the curl command shows the interface counts changing.

Access the server from the host

Now, find the IP address that has been assigned to the Docker container. Use the 'ifconfig' command as shown below:

user-1@d49158b992f5:~$ ifconfig
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 172.17.0.2  netmask 255.255.0.0  broadcast 172.17.255.255
  ...

The container’s IP address in this instance is 172.17.0.2, as shown by the 'eth0’s inet' value.

Note

Each time you restart the container the IP address of the container may change.

Next, in a different terminal on your host computer, use curl to access the same data as before:

> curl http://172.17.0.2/restconf/data/interfaces-state
{
 "ietf-interfaces:interfaces-state": {
  "interface": [
   {
    "name":"lo",
    "admin-status":"up",
    "oper-status":"up",
    "if-index":1,
    "phys-address":"00:00:00:00:00:00",
    "speed":"0",
    "statistics": {
     "in-octets":"109600",
     "in-unicast-pkts":"294",
     "in-multicast-pkts":"0",
     "in-discards":0,
     "in-errors":0,
     "out-octets":"109600",
     "out-unicast-pkts":"294",
     "out-discards":0,
     "out-errors":0
    }
   }
  ]
 }
}

You can also use the same URL, http://172.17.0.2/restconf/data/interfaces-state, inside a browser on your host system as shown below:

../_images/YumaPro-Docker-Browser-URL.png

Note

YumaPro Dockers are only accessible, with ssh, ping, etc., from their host machine.

For more details and examples on using RESTCONF, refer to Using RESTCONF.

Cloning the YumaPro Docker to Save Changes

When working with YumaPro Dockers changes can be made to the Docker image, such as changing the existing user, adding different users, modifying permissions, and adding/creating files on the container filesystem.

To preserve these changes for the next time the YumaPro Docker starts, the current system and the changes made must be cloned to a new Docker image using the Docker 'commit' command.

Note

It is important to stop the netconfd-pro server before cloning the image. If this is not done the clone snapshot will try restarting the server and fail as the PID file used by the server is already in use. This may also apply to other applications you masy have installed that are running at the time the snapshot is taken.

To stop the netconfd-pro server running with the --with-yuma-system='true' parameter, connect to yangcli-pro and execute the following command:

user-1@d49158b992f5:~$ yangcli-pro server=localhost user=user-1 password=password-1

user-1@localhost> shutdown

RPC OK Reply 3 for session 3 [default]:

user-1@localhost>

ses: session 1 shut by remote peer

> quit

To commit the changes made inside a Docker container follow the steps below:

  1. In a terminal window on the host system, NOT inside the Docker container, find the 'CONTAINER ID' to clone with: sudo docker ps -a

  2. Execute: sudo docker commit [CONTAINER ID] [new_container_name]

  3. Run the new container: sudo docker run -it [new_container_name]

Note

You can run the new container at the same time the original is running. The two will have different IP addresses.

The steps above are shown below:

> sudo docker ps -a
CONTAINER ID   IMAGE                     COMMAND                  CREATED         STATUS                      PORTS     NAMES
5e1083099515   yumapro-sdk-eval-docker   "/bin/sh -c 'sudo se…"   5 minutes ago   Exited (0) 10 seconds ago             amazing_tesla

> sudo docker commit 5e1083099515 yp-sdk-eval-docker
sha256:f371123192caf32e5a4df0596322fd3769a8af6bdeab6d7af79276aa99d9b9c6

> sudo docker image ls
REPOSITORY                TAG       IMAGE ID       CREATED          SIZE
yp-sdk-eval-docker        latest    f371123192ca   44 seconds ago   551MB
yumapro-sdk-eval-docker   latest    3ecd852b1db8   3 hours ago      551MB

> sudo docker run -it yp-sdk-eval-docker


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

netconfd-pro version 23.10-6-EVAL-13fcf (23.6.0)

Starting netconfd-pro server in the background with basic parameters..
Refer to docker-logs/netconfd-docker.log file for logging information.
user-1@5216f72f80c6:~$

Note

As the netconfd-pro server was stopped before making the clone the ietf-interfaces module will need to be reloaded into the server and the client. If you want specific YANG modules to be automatically loaded or other parameters configured, each time the server restarts, modify the server configuration file - /etc/yumapro/netconfd-pro.conf.

There are many CLI parameters for the server which can be found documented here: YumaPro CLI Reference

Further Reading