Gateway Management¶

Introduction¶

Gateway management spans multiple TrackCentral instances. Management is a complementary aspect to the pure operation a LoRaWAN network. The entity which manages gateways for TrackCentral installations is the Conﬁguration and UPdate Server, in short CUPS. In general, LoRaWAN speciﬁc parameters, such as region channel plan are speciﬁc to a TrackCentral instance and the role of CUPS is to aid the process of conﬁguring gateways with the corresponding LoRaWAN parameters for the corresponding TrackCentral instance.

CUPS oﬀers the following high-level features:

provisioning of gateways on the remote TrackCentral instances
directing the TrackStation processes running on gateways to the correct TrackCentral instance for the LoRaWAN operation
storing and quering meta-data associated with gateways
managing ﬁrmware and software packages for diﬀerent gateways models
distributing ﬁrmware and software package updates to gateways
providing gateways with custom scripts to match diﬀerent proﬁles

In addition to the commands and APIs available in CUPS and TrackCentral, for low-level remote debugging of Linux-based gateways there is the possibility to start on-demand a remote SSH tunnel session using TUN.

Architecture¶

CUPS is a central instance managing a set of gateways across several TrackCentral instances. Several CUPS instances can co-exist managing a set of gateways. To be able to provision gateways on a remote TrackCentral instance, CUPS requires corresponding credentials to impersonate the respective owner on the remote TrackCentral instance. The meta-information as well as current requests from gateways are logged in the local CUPS database. Furthermore, ﬁles such as ﬁrmware images and scripts are saved in the local ﬁle system in the CUPS installation directory. The CUPS installation directory is typically ~/tc/cups-ID6 where tc is the local TrackCentral installation and ID6 is the CUPS identiﬁer. Several CUPS instances can run on the same server with diﬀerent conﬁguration in terms of security and ports.

Server¶

The CUPS server provides two sets of REST APIs. An internal API for gateway clients and an external API for server operators to manage their gateways.

Gateway Meta-Information¶

For each gateway, CUPS keeps the following meta-information:

Meta-info	Description
tag	useful for searching gateways, e.g. used in say the same project
name	human-readable name to describe a gateway, e.g., main hall
model	gateway model, e.g. kerlink, tabs, etc.
hwspec	the number of available SX1301 LoRa radios
mac	the MAC address for the gateway
region	the region plan used for the gateway, must exist on the remote TrackCentral instance where the gateway operates
infos	the ID6 identiﬁer for the remote TrackCentral instance where the gateway operates
cups	the ID6 identiﬁer for a remote CUPS instance which is fully responsible for this gateway, the gateway will be re-conﬁgured to connect to this instance
frozen version	version to which the gateway will be frozen, i.e. no updates to the ﬁrmware or software package will be provided beyond this version
keepcfg	a ﬂag to mark whether certain conﬁguration ﬁles, e.g. WiFi settings, should be kept during a ﬁrmware upgrade
private	a ﬂag to mark whether the gateway will conﬁgured as private in TrackCentral, i.e., only traﬃc from devices which belong to the remote owner devices will be forwarded by TrackCentral
owner	the ID6 identiﬁer for local CUPS owner
remote owner	the ID6 identiﬁer for the remote TrackCentral owner
contact	the contact information for the gateway
email	information associated with the contact or operator of the gateway
address	postal address, associated with the contact or operator of the gateway
phone	phone number, associated with the contact or operator of the gateway; could also be used for the phone number associated with a SIM for gateways connected via 3G/4G
apn	the access point name (APN) to be conﬁgured in case of a mobile connection (3G/4G)
rxdelay	the RxDelay parameter as deﬁned by the LoRaWAN standard, matching special conditions in the network connectivity of the gateway
rx1droﬀ	the RX1DROﬀ parameter as deﬁned by the LoRaWAN standard, matching special conditions in the environment for the gateway
pre	a script for Linux-based gateways which is executed before a ﬁrmware or software package installation
post	a script for Linux-based gateways which is executed after a ﬁrmware or software package installation
script	a script for Linux-based gateways which is executed periodically
keys	additional SSH keys to be installed on the gateway
boot	how many times, the gateway used it’s bootstrap credentials to obtain personalized CUPS credentials
kit	a generic Kit number, relevant for searching gateways
order	a generic Order number, relevant for searching gateways

All parts of the meta information can be used for searching gateways. The MAC address of the gateway is used as a unique identiﬁer.

CUPS (internal) API for Gateways¶

CUPS provides an internal API which exposes the same REST calls to all the diﬀerent gateway models for performing the following high-level tasks:

retrieving the TrackCentral URI associated to a gateway
retrieving the credentials required for communication with TrackCentral
retrieving ﬁrmware/package updates
downloading custom scripts (e.g., for Linux-based platforms)
pushing custom logs, alerts and statistics

CUPS (external) API for Gateways¶

CUPS provides an external API which exposes REST calls for a subset of the operations available via the command line interface. The following high-level tasks are available:

retrieve the meta-information associated with a gateway
list the gateways known to CUPS using ﬁlters for the meta-information
move a gateway from one TrackCentral instance to another
update meta-information about a gateway

Client¶

On each gateway a CUPS client is responsible for periodically querying the CUPS instance for possible updates. By default the CUPS client will perform queries once a day, on reboot, or if externally triggered.

For example, if a gateway is no longer provisioned on TrackCentral instance, the connection to TrackCentrak will either break or fail. In this case, the cups client on the GW checks for an update of the TrackCentral URI together with corresponding credentials.

Installation¶

CUPS can be installed as part of a normal TrackCentral installation by specifying the with-cups keyword to the tc-setup-simple installation script.

tc-setup-simple tc with-cups

Logs¶

CUPS keeps logs in the TrackCentral installation directory, and are typically located at ~/tc/temp/cups.log.

Backup¶

If backup is enabled this will run periodically, e.g. once a day, and backup the CUPS/TrackCentral installation directory as well as the CUPS/TrackCentral database.

Operation¶

Command Line Interface¶

All the features available in CUPS can be accessed via the powerful swark.cups command line interface. In addition, CUPS uses the TrackCentral core infrastructure for managing the credentials for the InfoS servers and the PKI infrastructure. The following is an overview of the operations which can be performed using swark.cups. For detailed reference use to online help accessible via the –help option of the command itself. Below is an overview of all commands available in CUPS:

swark.cups --help
usage: swark.cups [-h] {list,add,remove,start,gwadd,gwdel,gwupd,gwlist,gwinfo,gwsync,fwadd,fwdel,fwlist} ...

Manage GW config and update server entries in system setup.

optional arguments:
  -h, --help            show this help message and exit

Subcommands:
  {list,add,remove,start,gwadd,gwdel,gwupd,gwlist,gwinfo,gwsync,fwadd,fwdel,fwlist}

    list                List CUPS instances registered in the system configuration.
    add                 Add CUPS instances to system configuration.
    remove              Remove a CUPS instance from system configuration.
    start               Start a CUPS process.

    gwadd               Provision routers.
    gwdel               Delete a provisioned router.
    gwupd               Update information a gateway.
    gwlist              List provisioned routers.
    gwinfo              Detailed info about provisioned GW.
    gwsync              Sync back into CUPS name,region,rxdelay,rx1droff from TrackCentral.

    fwadd               Add a firmware image.
    fwdel               Delete firmware images.
    fwlist              List known firmware images.

Listing all ID6 of TrackCentral instances known to CUPS¶

swark.infos list

Adding a TrackCentral instances to CUPS¶

The corresponding token has to be generated on the remote TrackCentral instance using the swark.tocap command. The ID6 is local to CUPS and can be assigned by the CUPS operator. This ID6 will be referred to by the gateways managed by CUPS.

swark.infos add --id 1 --uri https://TRACK.CENTRAL.COM:1234 --extra "{'token4cups':'AWcykuKHlDWMUTrqNpeN1VKDvgkD'}"

Adding a new ﬁrmware¶

The gateway model is inferred from the package.

swark.cups fwadd firmware-1.15.08-all.img

Provisioning a new gateway¶

The remote owner and the corresponding region channel plan must exist on the remote TrackCentral instance and be compatible with the actual hardware speciﬁcation of the gateway.

swark.cups gwadd --tag test --name uiui AB:CD:EF:01:23:52 --remote-infos ::1 --remote-owner ::1 --remote-owner ::1 --region US902/block01 --hwspec sx1301/2 --model odu

Moving and updating information for an existing gateway¶

The swark.cups gwupd command can update all meta-information for a gateway. If the update does not change the remote TrackCentral insance, i.e. InfoS, then changes are only local to the CUPS database. If there is an update to the InfoS, then this means that in addition to updating the meta-information, the gateway will be moved i.e., removed from the old TrackCentral instance, and added to the new TrackCentral instance.

swark.cups gwupd --tag 'new project'--remote-infos ::2 --remote-owner --region EU863/special ::1 AB:CD:EF:01:23:45

Querying gateways matching certain criteria¶

All search operations will match patterns. The example bellow lists all gateways that are online and connected to the remote management tunnel (TUN), have an external IP matching the pattern 1.2.3 and have been annotated with a kit number starting with ABC

swark.cups gwlist --mtun --extip 1.2.3 --kit ABC

Displaying information about a gateway¶

swark.cups gwinfo AB:CD:EF:01:23:45

Running a command locally on a set of Linux-based gateways¶

Run the ipsec status command, locally on each gateway matching the speciﬁed ﬁlters. This assumes the gateways are Linux based. The output of the command is printed on the CUPS command line.

swark.cups gwlist --mtun --extip 1.2.3 --kit ABC --script ipsec status

Custom gateway conﬁguration¶

For Linux-based platforms, special conﬁgurations for gateways can be achieved using custom scripts, e.g. turning oﬀ the WiFi. However, for low-level operations, such as setting static IP address or other special network conﬁguration and routing, which require access to the gateway itself and manual conﬁguration using respective Linux command. Such tasks are not the responsibility of CUPS. In essence, any conﬁguration which a GW requires before it can connect to CUPS needs to be performed manually prior to connecting the gateway to the network. Once the gateway is able to reach its corresponding CUPS server, conﬁguration using scripts provided by CUPS is possible.

Gateway alarms¶

Gateway alarms can be conﬁgured in TrackCentral using the swark.ralarm command.

Remote SSH (TUN)¶

In special situations, for troubleshooting and support, it is may be required to access the Linux system of the GW to retrieve system information, manually repair conﬁguration ﬁles or restart processes. Such remote access is only intended for authorized users skilled in embedded Linux systems and with a deep knowledge of the respective gateway model. The remote SSH access is only available for gateways running Linux. This remote SSH capability allows for interactive and live support. However, this is also the last resort in case of support issues. In normal operation, the commands and APIs available in TrackCentral and CUPS are suﬃcient to operate and conﬁgure gateways.

To allow for remote SSH access a client on the gateway connects to a remote tunnel server. Via the tunner server an SSH connection back to gateway can be established on demand.

Security model¶

All connections to CUPS are protected using TLS with client-authentication. Depending on the API, client authentication is achieved in the following way:

Gateway clients authenticate to the CUPS using client-certiﬁcates, which are assigned by the CUPS server.
External servers can access the external CUPS API using tokens, similar to the TrackCentral API.

All connections from CUPS to the TrackCentral instance are protected using TLS and client-authentication using tokens as speciﬁed in the TrackCentral API documentation.

If available, all connections to a remote gateway are using SSH with public-key authentication. Furthermore, for security reasons the root/admin password for the gateway is automatically changed by CUPS to a random password. Furthermore, most GWs should be conﬁgured to disable SSH access directly via the local interfaces and any other open server ports which can potentially expose vulnerabilities.

In special cases, for development and debugging, security and authentication can be disabled, i.e. CUPS can provide a REST API via plain HTTP and without client-authentication.