Getting started

This guide explains how to run the FRINX UniConfig for the first time. Content:

System requirements

RAM: 8GB minimum; 16GB recommended
Linux: Supported Linux distributions are Centos7, Ubuntu 16.04 and Ubuntu 18.04
Java: FRINX distribution requires Java 8 (Openjdk 1.8.0-171 or newer)

Note

Unless stated otherwise, this documentation assumes you are using Linux.

To install Java

CentOS: Run a terminal and insert a command below:

sudo yum install java-1.8.0-openjdk

Ubuntu: Run a terminal and insert a command below:

sudo apt-get install openjdk-8-jdk

Download the FRINX UniConfig distribution

Please click on the following link to download a zip archive of the latest Oxygen FRINX UniConfig distribution:

Oxygen: distribution-karaf-4.2.2.frinx.zip

By downloading the file you accept the FRINX software agreement: EULA

Activate your FRINX UniConfig distribution

To activate your installation, unzip the file and open the directory. Enter the following commands in a terminal to start and activate FRINX UniConfig.

Note

The token is unique to your user account on frinx.io and cannot be shared with other users. It can be found here (you need to be logged in frinx.io to view your token)

./bin/karaf frinx.createtoken [frinx-license_secret-token]

Note

In the event of copying the command shown above into the terminal, insert your unique token in place of [frinx-licence_secret-token]. Do not insert token number into the square brackets.

FRINX UniConfig needs approximately 3 minutes to startup and shutdown.

To maintain system integrity, please do not interrupt the startup by shutting down running processes within this time.

In the event of interruption, the initial state can be restored by entering the following commands from a terminal within your FRINX UniConfig main directory.

First command forcibly kills the FRINX UniConfig karaf process Second command cleans certain directories:

kill -9 $(pgrep  -o -f  karaf)
rm  -rf  data/ snapshots/ journal/

To stop FRINX UniConfig safely from within the karaf console, hold the ‘CTRL’ key and press the ‘D’ key. For more info on operating karaf, see running-frinx-odl-after-activation

For non-standard setups, use this guide Operations_Manual/running-frinx-odl-initial

Running as a docker container

Enter the following commands to start your Docker container and activate your installation:

Note

The token is unique to your user account on frinx.io and cannot be shared with other users. It can be found here (you need to be logged in frinx.io to view your token)

For Oxygen:

docker pull frinx/frinx_odl:4.2.2.frinx
TOKEN=[frinx-license_secret-token]
docker run -it --hostname some-hostname --name some-frinx -p 8181:8181 frinx/frinx_odl:4.2.2.frinx frinx.createtoken.force $TOKEN

For Carbon:

docker pull frinx/frinx_odl:3.1.8.frinx
TOKEN=[frinx-license_secret-token]
docker run -it --hostname some-hostname --name some-frinx -p 8181:8181 frinx/frinx_odl:3.1.8.frinx frinx.createtoken.force $TOKEN

For Beryllium:

docker pull frinx/frinx_odl:2.3.1.frinx
TOKEN=[frinx-license_secret-token]
docker run -it --hostname some-hostname --name some-frinx -p 8181:8181 frinx/frinx_odl:2.3.1.frinx frinx.createtoken.force $TOKEN

For Boron:

docker pull frinx/frinx_odl:1.4.16.frinx
TOKEN=[frinx-license_secret-token]
docker run -it --hostname some-hostname --name some-frinx -p 8181:8181 frinx/frinx_odl:1.4.16.frinx frinx.createtoken.force $TOKEN

The default credentials are:

username: admin
password: admin

You can verify that at http://localhost:8181/auth/v1/users

Note about networking

In the previous example only port 8181 was mapped to the docker host. To access all other ports there are more options, most notably:

Use docker0 ethernet bridge

By default, Docker runs with an isolated network interface. From the Docker host type:

docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' some-frinx

to get the IP of the running container. You can then access all ports including the web server (8181) using that IP. The IP is accessible only from the docker host, unless routing is set up.

Use host networking

If you want to map all ports exposed by the image, you can use host networking:

docker run --net=host ...

To the outside world this would be the same as running karaf directly on the host.

Advanced networking

For these options please refer to the official Docker networking documentation.

Stopping the container

As the container was given the name some-frinx, type:

docker stop some-frinx
Committing the container to local images

The previous docker run command created a license file inside the some-frinx container. We recommend creating a docker image by typing:

docker commit some-frinx frinx/frinx_odl:licensed

This command will create a new tag – licensed. This image has the frinx license file.

Starting a stopped container

To start a stopped container, run:

docker start some-frinx
Starting from clean state

After installing some features it might be useful to come back to a clean karaf. If you created the licensed tag, you can simply run:

docker rm some-frinx
docker run -it --hostname some-hostname --name some-frinx -p 8181:8181 frinx/frinx_odl:licensed
Connecting to the karaf console of a running container
docker exec -it some-frinx bin/client -u karaf

Troubleshooting and advanced topics:

Activating the FRINX ODL Distribution behind a proxy

Please set up java system properties as described here: https://docs.oracle.com/javase/6/docs/technotes/guides/net/proxies.html

This means running karaf with something like this:

JAVA_OPTS=”-Dhttp.proxyHost=10.0.0.100 -Dhttp.proxyPort=8800″
bin/karaf frinx.createtoken …
Activating the FRINX ODL Distribution on a server without Internet access

These are the steps required to generate the license on a system without internet access:

Let’s call the connected computer ONLINE and the one where you want to run karaf OFFLINE.

Generate fingerprint json to a local file:

OFFLINE# $KARAF_HOME/bin/karaf frinx.fingerprint > fingerprint.txt

Now, copy fingerprint.txt to the ONLINE machine:

Copy frinx.license.cfg back to the OFFLINE machine, replacing the file in karaf’s etc folder.

You will now be able to start karaf normally:

Anyconnect VPN issue

If karaf fails with the following exceptions, please try stopping anyconnect. For more information see https://ask.opendaylight.org/question/942/running-karaf/

Frinx License warning: Frinx distribution is only supported on Linux
>
>         _________      .__
>         \________\__ __|__| ____ __  ___
>           / | ___\  V__\  |/    \  \/  /
>          /  | \ |   |  |  |   |  \    \\
>          \__| / |___|  |__>___|  /_/\__\\
>             \/                 \/
>
> Frinx version: 1.2.5.frinx
> frinx-user@root>
> frinx-user@root>Exception in thread "JMX Connector Thread [service:jmx:rmi://0.0.0.0:44444/jndi/rmi://0.0.0.0:1099/karaf-root]" java.lang.RuntimeException: Could not start JMX connector server
>        at org.apache.karaf.management.ConnectorServerFactory$1.run(ConnectorServerFactory.java:258)
> Caused by: java.io.IOException: Cannot bind to URL [rmi://0.0.0.0:1099/karaf-root]: javax.naming.ServiceUnavailableException [Root exception is java.rmi.ConnectException: Connection refused to host: 0.0.0.0; nested exception is:
>        java.net.ConnectException: Operation timed out]
>        at javax.management.remote.rmi.RMIConnectorServer.newIOException(RMIConnectorServer.java:827)
>        at javax.management.remote.rmi.RMIConnectorServer.start(RMIConnectorServer.java:432)
>        at org.apache.karaf.management.ConnectorServerFactory$1.run(ConnectorServerFactory.java:245)
> Caused by: javax.naming.ServiceUnavailableException [Root exception is java.rmi.ConnectException: Connection refused to host: 0.0.0.0; nested exception is:
>        java.net.ConnectException: Operation timed out]
>        at com.sun.jndi.rmi.registry.RegistryContext.bind(RegistryContext.java:147)
>        at com.sun.jndi.toolkit.url.GenericURLContext.bind(GenericURLContext.java:228)
>        at javax.naming.InitialContext.bind(InitialContext.java:425)
>        at javax.management.remote.rmi.RMIConnectorServer.bind(RMIConnectorServer.java:644)
>        at javax.management.remote.rmi.RMIConnectorServer.start(RMIConnectorServer.java:427)
>        ... 1 more
> Caused by: java.rmi.ConnectException: Connection refused to host: 0.0.0.0; nested exception is:
>        java.net.ConnectException: Operation timed out
>        at sun.rmi.transport.tcp.TCPEndpoint.newSocket(TCPEndpoint.java:619)
>        at sun.rmi.transport.tcp.TCPChannel.createConnection(TCPChannel.java:216)
>        at sun.rmi.transport.tcp.TCPChannel.newConnection(TCPChannel.java:202)
>        at sun.rmi.server.UnicastRef.newCall(UnicastRef.java:342)
>        at sun.rmi.registry.RegistryImpl_Stub.bind(Unknown Source)
>        at com.sun.jndi.rmi.registry.RegistryContext.bind(RegistryContext.java:141)
>        ... 5 more
> Caused by: java.net.ConnectException: Operation timed out
>        at java.net.PlainSocketImpl.socketConnect(Native Method)
>        at java.net.AbstractPlainSocketImpl.doConnect(AbstractPlainSocketImpl.java:350)
>        at java.net.AbstractPlainSocketImpl.connectToAddress(AbstractPlainSocketImpl.java:204)
>        at java.net.AbstractPlainSocketImpl.connect(AbstractPlainSocketImpl.java:188)
>        at java.net.SocksSocketImpl.connect(SocksSocketImpl.java:392)
>        at java.net.Socket.connect(Socket.java:589)
>        at java.net.Socket.connect(Socket.java:538)
>        at java.net.Socket.(Socket.java:434)
>        at java.net.Socket.(Socket.java:211)
>        at sun.rmi.transport.proxy.RMIDirectSocketFactory.createSocket(RMIDirectSocketFactory.java:40)
>        at sun.rmi.transport.proxy.RMIMasterSocketFactory.createSocket(RMIMasterSocketFactory.java:148)
>        at sun.rmi.transport.tcp.TCPEndpoint.newSocket(TCPEndpoint.java:613)
>        ... 10 more

UniConfig basic principles

The purpose of UniConfig is to manage the intent (desired configuration) of physical and virtual networking devices through a single network API. In addition, UniConfig enables device and network wide transactions so that the network will always remain in a well-defined state without leftovers from failed configuration attempts. UniConfig is delivered as an application in the FRINXOpenDaylight (ODL) distribution and as a standalone application. UniConfig enables users to communicate with their network infrastructure via three different options:

  1. Via unstructured data through CLI
  2. Via OpenConfig API withthe help of our open source device library
  3. Via vendor YANG models native to the connected devices

Option 1) gives users similar capabilities like access through Ansible or similar tools and allows to pass strings to the device and receive strings from the device in a programmatic way. UniConfig provides the mechanism to authenticate and provide a channel to send and receive data but does not interpret the data. That is left for the user application to do.

Option 2) provides users with an OpenConfig API that is translated into device specific CLI or YANG models. This requires “translation units” to be installed for the devices under control. FRINX provides an open source device library that includes many devices from widely deployed network vendors.

Option 3) also called “UniConfig native”, provides the ability to configure devices with any YANG model that is supported by the device. After mounting a device, UniConfig native maps the vendor models into its UniConfig data store and provides stateful configuration capabilities to applications and users.

UniConfig solution

Install features

Features for CLI

Install the features necessary to use CLI with command below:

frinx-user@root>feature:install frinx-cli-all-units odl-restconf odl-netconf-connector-all frinx-unified-topology-all-units frinx-uniconfig-node-manager

Features for NETCONF

Install the features necessary to use NETCONF with command below:

frinx-user@root>feature:install odl-netconf-connector-all

Features for UniConfig

Install the features necessary to use UniConfig with command below:

frinx-user@root>feature:install odl-restconf-all odl-netconf-topology frinx-cli-all-units frinx-unified-topology-all-units frinx-uniconfig-node-manager

Features for UniConfig native

Install the features necessary to use UniConfig-native with command below:

frinx-user@root>feature:install odl-restconf-all odl-netconf-topology frinx-uniconfig-node-manager frinx-uniconfig-native

Connecting devices

When using Karaf to run FRINX UniConfig, the address used for this operation is localhost:8181. After FRINX UniConfig initiation, make sure, you can reach your device through the network. Either using VPN or when the device is located in the same network as your workstation, use the IP address of the device.

After completing steps listed above, you can proceed to the API documentation and start to configure your devices through FRINX UniConfig.