3.3. Configuration States

Configuration States is a flexible mechanism to remotely read and write all kinds of settings on a Cascade gateway. Customers can use Configuration States to control system configurations like network connections, app settings, and NTP (Network Time Protocol) server options are with Configuration States. Rigado has designed this feature to allow gateway configuration setup through Edge Direct to take place regardless of the gateway’s Internet connectivity, and to make it easy to see what configuration is currently on a gateway.

3.3.1. How Configuration States Works

Types

Configuration is written and maintained in a JSON file for each Cascade gateway. There are four types of the JSON document visible to customers that make up the whole configuration:

  • App Sets: control the settings for an app on a gateway. All customers have the ability to configure the rigado-edge-connect app (see Edge Connect Configuration). “Advanced Mode” customers have the ability to configure their custom apps as well.

  • NTP Time Server: controls the time-server settings on a gateway

  • Network: controls the network configurations a gateway has

  • Early Access Program (EAP): controls whether the gateway has EAP Mode enabled.

    Note

    EAP is only configurable by customers who have Advanced Mode access to Edge Direct.

Edge Direct helps you manage these configurations by individual type. The Edge Direct web interface provides user-friendly forms for some configuration types, and a JSON editing view for App Set, since App Set configurations have a more widely-varying structure across use cases.

You may also use the rigado CLI to handle the JSON directly yourself (see rigado config create).

The Configuration Interface in Edge Direct

../_images/config.png

Figure 3.6 The Config tab of a gateway detail page, showing the different config types, in different states

On the Config tab of a gateway, you can see the current configuration of the gateway, as well as the state of each desired configuration.

In the Configurations area, you can:

  • View the most recent configurations by type
  • See when the configuration was last modified
  • View the state of each configuration type
  • Click Update to edit that configuration

Click a configuration type within the Current Configuration area to expand and view the gateway’s current configuration:

../_images/current-ntp.png

Figure 3.7 A Current Configuration for the NTP Server and Time Zone settings on a gateway

Configuration Flow

1. When a you submit a configuration, it’s saved as the gateway’s desired configuration. Its first state will be PENDING while the Edge Direct backend is processing and saving the desired configuration. The state will remain PENDING until the server receives acknowledgement from the gateway that it has received the configuration.

Note

It’s possible to update the desired configuration multiple times before the configuration is applied to the gateway. Only the most recent desired configuration will ever be applied. Any intermediate updates made to the desired configuration before it is applied will be ignored.

  1. When a gateway receives a configuration, the state changes to IN PROGRESS. The state remains IN PROGRESS while the Edge Direct agent on the gateway applies the configuration to the gateway.

  2. When the Edge Direct agent on the gateway applies the configuration successfully, the desired configuration’s state will become APPLIED.

  3. If the Edge Direct agent on the gateway encounters an error while applying the configuration, the state of the desired configuration will change to ERROR. The agent on the gateway will stop processing the configuration exactly where the error occurs. You can view the edit screen for the configuration to see available information about the error.

    ../_images/error-network.png

    Figure 3.8 Example ERROR state for a Network configuration

    This may leave part of the configuration applied and part of the configuration not applied. When the configuration is in the ERROR state, you can examine the Current Configuration view to see what was applied and what was not applied.

    Important

    When an error occurs, Edge Direct will not roll back the gateway’s configuration to a previous desired configuration. This is to ensure that the current configuration is always knowable and that a gateway cannot enter a configuration error loop.

The states a configuration goes through are as follows:

  • PENDING: the gateway has not yet received the configuration
  • IN PROGRESS: the gateway is applying the configuration
  • APPLIED: the agent on the gateway has applied the configuration and reported this fact to the Edge Direct server
  • ERROR: the agent on the gateway has tried to apply the configuration, and reported an error to the Edge Direct server

Note

The Edge Direct web-application may show another state for each configuration type: INITIALIZING. This means that a gateway has the ability to use the Configuration States feature, but it has not yet checked in to the Edge Direct server to set up its initial configuration.

Handling Secrets

Within every part of a gateway’s configuration is a mechanism for redacting secrets. This mechanism is in place to make sure Edge Direct never shows sensitive data to a human user. It relies on a concrete list of “sensitive” words that it matches against.

List of reserved “sensitive” words (not case-sensitive):

  • accesskey
  • auth-key
  • authcode
  • ca
  • cert
  • cipher-key
  • connectionstring
  • credentials
  • gg-certs-base64
  • gg-certs
  • headers
  • mqttpassword
  • passkey
  • password
  • privatekey
  • psk
  • pw
  • sastoken
  • secret
  • token

The redaction of secrets in a configuration has two parts. The first part concerns displaying sensitive configurations to a user. The second part concerns the user editing and saving sensitive configurations.

Displaying Sensitive Configurations

When a given key in the configuration JSON matches any of the sensitive words, Edge Direct will always return the string value "REDACTED" rather than the secret value. At no point is the actual value of a sensitive field ever returned or exposed to users.

Note

The algorithm that compares the JSON keys to the sensitive words list is not case-sensitive, so the value for the key "Password" would be redacted because it matches the sensitive word "password". For some configuration types such as APP_SET, this is a moot point since keys for that configuration type must be lowercase.

The matcher does verify that the whole key matches the whole sensitive word. For example, the matcher would not redact the value for the key "myPassword".

Editing Sensitive Configurations

When a user updates a sensitive key with a new value, then Edge Direct will save the new value in the gateway’s configuration.

When a user submits a configuration with the value set to "REDACTED", then Edge Direct will not update the gateway’s configured value for that key. Instead, Edge Direct will search the gateway’s current configuration for that sensitive key, and apply the previously-saved value for that key.

Note

The matcher behind this is also not case-sensitive, so sending the value "redacted" is equivalent to sending the value "REDACTED".

This logic only pertains to the JSON keys listed in the above sensitive words list. If you send a configuration with a non-sensitive key’s value set to "REDACTED", that value will be applied on the gateway as "REDACTED".

Example: JSON payload for Wi-Fi Config

Here is an example of a JSON payload that will configure a gateway’s network connection (named wireless) to use a password and WPA-PSK security scheme. This example illustrates how the redaction mechanism works on a “sensitive” key like "password".

Note

the JSON payloads below are truncated for clarity. They do not represent an entire NETWORK configuration payload.

As first submitted by the user:

{
   "wireless": {
      "ssid": "my-wifi-network-ssid",
      "security": {
         "psk": "password",
         "keyManagement": "wpa-psk"
      }
   }
}

As returned by Edge Direct (for instance when viewing the gateway’s network configuration at a later time):

{
   "wireless": {
      "ssid": "my-wifi-network-ssid",
      "security": {
         "psk": "REDACTED",
         "keyManagement": "wpa-psk"
      }
   }
}

At this point, if you want to change the value for psk, you may update the value and send the new sensitive value. If, however you want to update some other part of the configuration but keep the psk to its stored value of password, you can send REDACTED and the Edge Direct backend will continue to use the saved value.

Note

Sending "REDACTED" only works if the key is in the “sensitive” list (see above).

Configuring Multiple Gateways

If you would like to update multiple gateways with the same configuration, we recommend writing a script, and utilizing our CLI. The example below illustrates how to save a JSON file with the configuration payload, and use a simple bash script with our CLI command to configure a list of gateways.

Example: Sharing a network configuration with multiple gateways

Rigado provides a form to handle a gateway’s network configuration through the Edge Direct web interface. The JSON that is stored for Network Configuration is significantly more complicated than the form. This is due to the configuration requirements of the low-level software on the gateway (network-manager). Edge Direct omits the details of the configuration that are not necessary for users to manipulate or understand. This is fine for configuring network for a single gateway on the web interface, but it would be tedious to use this interface to configure many gateways at a time. Here is our recommendation:

  1. Configure one gateway in with the network configuration that you want for the whole group you are configuring, using the web interface.

    ../_images/configure-network.png

    Figure 3.9 Configuring the Network settings for a gateway

  2. After you submit the configuration, download the Network JSON by clicking the blue download icon under Current Configurations.

    ../_images/download-network.png

    Figure 3.10 The Current Configuration for Network, showing the download button

    A few more operations are necessary before this JSON file is ready to send as a new desired configuration.

  3. Create a new file named config.json. Type or paste the following into this file:

    {
       "type": "NETWORK",
       "settings": {
    
       }
    }
    

    Then, copy the contents of the file you downloaded, and paste it inside the settings block.

  4. Update the JSON in config.json to make sure there are no "REDACTED" values in it.

    If the gateways you will be configuring don’t already have the sensitive value saved in configuration, sending "REDACTED" would result in an error. On the other hand, if some gateways need a specific sensitive value that the other gateways don’t use, you will need to write a separate JSON payload file for each unique configuration.

  5. Create a new file, containing a list of gateway serials that you want to send this configuration to. Save this file as serials.txt and put one serial per line, like so:

    C123456789-00001
    C123456789-00002
    C123456789-00003
    ...
    

    Note

    This file must have a blank newline at the end for the script to process it properly.

    You don’t have to include the serial of the gateway you already configured in step 1.

  1. Create a script that uses the Rigado CLI to pass the configuration to your list of gateways. For example, the below script loops over the file serials.txt and sends the configuration file config.json to each gateway.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    #!/bin/bash
    
    if [ ! -f serials.txt ]; then
        echo "This script requires a file called serials.txt to exist"
        exit 1
    fi
    
    if [ ! -f config.json ]; then
        echo "This script requires a file called config.json to exist"
        exit 1
    fi
    
    # check command exists
    if [ ! $(command -v rigado) ]; then
        echo "This script requires a command (or alias) called rigado to exist"
        exit 1
    fi
    
    # check user has auth
    rigado auth whoami > /dev/null
    if [ $? != 0 ]; then
        echo "rigado command could not auth properly. Try running 'rigado auth login' and run this script again."
        exit 1
    fi
    
    while read serial; do
        echo "Configuring $serial..."
        rigado config create --serial $serial --filename config.json
    done <serials.txt
    
    echo "Finished"
    

3.3.2. Configure App Set

App Set is the configuration type for setting and controlling variables, data, settings, and other other possible configuration for a specific app on a Cascade gateway. Edge Connect Configuration for the Data Pipeline is set and maintained in this type. Advanced Mode customers who have written and maintain custom apps can set their app sets through this type of the configuration.

../_images/configure-apps.png

Figure 3.11 Updating the App Set configuration of a gateway

Removing an App Configuration

When you want to completely remove all configurations from an app, you must send an empty object for that app name. For example, to remove configurations for an app named my-custom-app, send:

{
   "my-custom-app": {}
}

Sending a completely empty payload ({}) will not change any App Set configurations on your gateway.

3.3.3. Configure NTP Time Server

The Network Time Protocol (NTP) server your gateway will use for clock synchronization is configured in this section.

The following fields are available for configuration:

  • NTP Server: The primary server your gateway should use for clock synchronization.
  • NTP Backup Server: The backup server your gateway should use.
  • NTP Timezone: The timezone your gateway is in. Must be recognized by the IANA timezone database.
../_images/configure-ntp.png

Figure 3.12 Updating a gateway’s NTP Server and Time Zone settings

3.3.4. Configure Network

Configure Wireless

The Configure Wireless feature allows you to connect to a local wireless network for sending data from the gateway to your server. The following fields are available for configuration:

  • Connection Profile Name: This is the personalized name of the connection, not necessarily the network name/SSID.

  • Autoconnect Priority: This describes the behavior when there are multiple connections available on the same interface (e.x., room1-wifi and room2-wifi). A higher number means the connection will have a higher priority. If multiple connections have the same Autoconnect Priority, the network manager on the gateway may prefer connections that are confirmed to work.

  • Route Metric: This is a number that sets the priority for active connections. A lower number means that connection has higher priority.

    For example: Wi-Fi connection “A” is active with routeMetric: 5, Ethernet connection “B” is active with routeMetric: 1, and cellular modem connection “C” is active with routeMetric: 10. Ethernet (“B”) will be the primary active connection in this scenario and Wi-Fi (“A”) will be the next connection to become primary if the Ethernet connection becomes inactive.

  • Wireless SSID: This is the service set identifier, or primary name associated with your wireless network. SSIDs are case sensitive and can be up to 32 alphanumeric characters.

  • Wireless password: This is the password for the Wireless SSID. Characters will be exposed in plaintext when this field is entered.

  • Wireless Key Management: This is the security protocol associated with your network. This is commonly wpa-psk, check with your network administrator.

  • IP addressing: This field is set to DHCP by default. Static IP should only be selected when required by your network administrator.

Configure Ethernet

The Configure Ethernet feature allows you to modify your static IP. The following fields are available for configuration:

  • Connection Profile Name: This is the personalized name of the connection.

  • Autoconnect Priority: This describes the behavior when there are multiple connections available on the same interface (e.x., room1-eth and floor23-eth). A higher number means the connection will have a higher priority. If multiple connections have the same Autoconnect Priority, the network manager on the gateway may prefer connections that are confirmed to work.

  • Route Metric: This is a number that sets the priority for active connections. A lower number means that connection has higher priority.

    For example: Wi-Fi connection “A” is active with routeMetric: 5, Ethernet connection “B” is active with routeMetric: 1, and cellular modem connection “C” is active with routeMetric: 10. Ethernet (“B”) will be the primary active connection in this scenario and Wi-Fi (“A”) will be the next connection to become primary if the Ethernet connection becomes inactive.

  • IP addressing: This field is set to DHCP by default. Static IP should only be selected when required by your network administrator.

Warning

Setting a Static IP for ethernet can potentially cause your gateway to lose its connection to the Internet. Rigado strongly recommends you configure your gateway with a valid Wi-Fi and/or Cellular network connection before configuring a static ethernet connection.

Note

The Edge Direct agent on the gateway maintains a default DHCP connection over ethernet. Removing or editing this default connection is not allowed. You can see the details of this connection in the Current Configurations section of the Config tab.

Configure Cellular

In most cases, the 500-W gateway will come pre-configured with your specific cellular carrier’s information, based on your coordination with the Rigado Solutions Engineering team during the planning phase of your project. In those cases, performing cellular configuration is not required.

In the event that cellular configuration is required, or a modification needs to be made, please ensure a SIM card is installed within the unit, and that an alternative connection (Ethernet, Wi-Fi) is available prior to making any changes. For more information on installing a SIM card, see Connecting the Gateway to Cellular.

The following fields are available for configuration:

  • Connection Profile Name: This is the personalized name of the connection.

  • Route Metric: This is a number that sets the priority for active connections. A lower number means that connection has higher priority.

    For example: Wi-Fi connection “A” is active with routeMetric: 5, Ethernet connection “B” is active with routeMetric: 1, and cellular modem connection “C” is active with routeMetric: 10. Ethernet (“B”) will be the primary active connection in this scenario and Wi-Fi (“A”) will be the next connection to become primary if the Ethernet connection becomes inactive.

  • Cellular APN: Access Point Name provided by your cellular provider; this field is required in order to establish a cellular connection. SIM card must be installed in the device in order to set the APN.

  • Advanced Options:

    • Cellular Username: In most cases this field will not be required. Use of this field would depend on your cellular provider configuring your SIM card to include a username.
    • Cellular Password: In most cases this field will not be required. Use of this field would depend on your cellular provider configuring your SIM card to include a username and password.

3.3.5. Configure EAP Mode (Advanced Mode Customers only)

When you want to put a gateway into EAP Mode, you can do that in this type of the configuration. Click the checkbox to indicate that you want the unit to go to EAP Mode and choose the channel you want to follow from the dropdown. The default channel to follow is Candidate and Rigado recommends that you do not follow any other channel without explicit cooperation or request from Rigado. You can learn more about EAP Mode in Early Access Program.

../_images/configure-eap.png

Figure 3.13 Updating the EAP Mode configuration for a gateway