Cisco Gateway Deployment¶

Purpose¶

This document describes the steps to deploy the Leitwert Gateway app on Cisco Access Points using DNA Center. The appendix at the end of this document provides information on deployment using the command line tool ioxclient.

Requirements¶

• Cisco Access Point of the C9100 series. It must be able to run IOx applications.
• Leitwert Gateway application package file package-<tag>.tar. Provided by Leitwert AG.
• Settings and credentials. Provided by Leitwert AG.
  • Gateway ID
  • Messagebus host, port, username, password
  • Loki host, url, port, username, password
• Cisco DNA Center web application, configured to communicate with the Access Point(s) on which the Leitwert Gateway app is to be installed.

Deployment procedure¶

This tutorial has been tested with:

• DNA Center base version 2.1.365.62360
• DNA Center UI version 1.6.2.432
• DNA Center Application Hosting version 1.6.0.2107090810
• C9120 AP running firmware version 17.6.1.13

Install Application Hosting package¶

This is a prerequisite to being able to install the Leitwert Gateway application on the AP.

• Open the menu in the top left corner.
• Click System > Software Updates, then click Installed Apps on the left.
• Scroll down to Automation and check if the package called Application Hosting is installed.
• Download and install if necessary.

Upload the Leitwert Gateway application package¶

• Open the menu in the top left corner and click Provision > IoT Services to enter the App Hosting page.
• To upload the Leitwert Gateway application to Cisco DNA Center, click on New App on the right side of the screen and upload the Leitwert Gateway application tar package to be installed.
• The application should now be listed in the IoT Services page.

Deploy the Leitwert Gateway application¶

• Open the menu in the top left corner and click on Workflows.
• Scroll down and click on the grid labeled Enable IoT Services.
• Follow the guided steps until you reach the Configure App page.
• On the Configure App page, set the details for the Gateway ID, the message bus and the Loki endpoint. This information is provided by either Leitwert AG or your network administrator.

App management¶

Select AP on which to manage the Leitwert Gateway app¶

This is a generic procedure that is used as a prerequisite step in the following app management procedures:

• Open the menu in the top left corner and click Provision > IoT Services to enter the App Hosting page.
• Click on the Leitwert Gateway app icon.
• Click on Manage.
• A list of APs should appear.
• Check the box of the AP(s) on which you would like to manage the Leitwert Gateway app.

Stopping and restarting the app¶

• Select the AP on which to manage the Leitwert Gateway app.
• In the Actions drop-down menu, select Stop App, or Start App.

Uninstalling the app¶

• Select the AP on which to manage the Leitwert Gateway app.
• In the Actions drop-down menu, select Uninstall App.

Edit the app config¶

This section describes how to edit the configuration that was passed to the Leitwert Gateway app during the steps described in Deploy the Leitwert Gateway application:

• Select the AP on which to manage the Leitwert Gateway app.
• In the Actions drop-down menu, select Edit App Config.
• A window appears, in which the configuration can be edited.

Log Files¶

The Leitwert Gateway app generates the following log files:

• gateway_launcher.log
• gateway.log

These log files are described in more detail below.

Downloading app log files¶

• Open the menu in the top left corner and click Provision > IoT Services to enter the App Hosting page.
• Click on the hostname of the AP. A list of apps should apper.
• Select the app for which the logs shall be viewed.
• Click on app logs.
• See also section Log Files for information on the log files that are generated by the Leitwert Gateway app.

Gateway Launcher Log¶

The log file with the name gateway_launcher.log is generated by the shell script /app/launcher.sh. This script prepares the environment for the Leitwert Gateway app to run in. In addition to that, it launches the Leitwert Gateway app executable and re-launches it in case the executable exits.

This log file is erased each time the app is stopped and restarted.

Gateway App Log¶

The log file with the name gateway.log is generated by the Leitwert Gateway app executable. It contains all logs that are generated by the Leitwert Gateway app executable.

This log file is generated by the Python RotatingFileHandler. This handler automatically generates a backup, if a log file has reached a certain size. The file being written to is always gateway.log. When this file is filled, it is closed and renamed to gateway.log.1 - and if file gateway.log.1 exists, then it is renamed to gateway.log.2 and so forth.

Appendix¶

Deplyoment using Ioxclient¶

This section is intended for a technically versed audience. Ioxclient offers administrative features that are not present in the DNA Center interface.

Edit the configuration file for local configuration¶

Create a file called package_config.ini with the following structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

[Gateway]
gateway_id: my-organisation-gateway-123

[Messagebus]
host: rabbitmq.myorganisation.org
port: 1234
vhost: myvirtualhost
username: myuser
password: mypass

[Loki]
host: loki.myorganisation.org
port: 4567
url: /loki/api/v1/push
use_tls: False
username: mylokiuser
password: mylokipass
;If the Loki endpoint uses no credentials, remove or comment the lines containing username and password.

Install the gateway application on the access point¶

Use this resources.json file and execute the following commands:

1
2
3
4

ioxclient app install gateway package-<tag>.tar
ioxclient app activate --payload resources.json gateway
ioxclient app setconfig gateway package_config.ini
ioxclient app start gateway

Verify successful installation and start of the application¶

1

ioxclient app list

1
2
3
4

Currently active profile :  default
Command Name:  application-list
List of installed App :
 1. gateway    --->    RUNNING

Remove gateway application¶

Removing the gateway application is necessary if:

• A new version of the gateway application is available and the application shall be updated.
• A unrecoverable error has happened during installation and the process must be started over.
• The gateway application has to be removed from the access point for other reasons.

Execute the following commands to remove an existing gateway application:

1
2
3

ioxclient app stop gateway
ioxclient app deactivate gateway
ioxclient app uninstall gateway