3.4. Configuration

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. 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.

As of early 2020, customers will have the ability to organize gateways into “sites”. Gateways assigned to a site will receive configurations from the site itself. Gateways not assigned to a site may be configured individually.

3.4.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 apps 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).

States

../_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 site, you can see a breakdown of each type of configuration, and how many gateways are in each state for a given type.

  1. When a you submit a configuration to a site, it’s saved as the site’s scheduled configuration. Its first state will be SCHEDULED for all of the site’s gateways. The state will remain SCHEDULED until the site’s maintenance window opens. If the site has an “ongoing” maintenance window, the configuration enters the PENDING state immediately.

    Note

    Configuration of an individual gateway skips the SCHEDULED step, and goes straight into PENDING.

2. When the site’s maintenance window opens, its scheduled configurations become desired configurations. The configurations enter the PENDING state while the Edge Direct backend processes and saves the desired configuration for each site gateway. The state will remain PENDING until the server receives acknowledgement from each gateway that it has received the configuration.

Note

It’s possible to update the scheduled or desired configuration multiple times before the configuration is applied to the gateway. Only the most recent configuration will ever be applied. Any intermediate updates made 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.7 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:

  • SCHEDULED: the site has not yet made the configuration available to any gateways
  • PENDING: the configuration is available to a gateway, but 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
  • certificate
  • certificates
  • 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).

3.4.2. Configuring Multiple Gateways

If you would like to update multiple gateways with the same configuration, we recommend putting those gateways in a site. After they are configured with the site’s configuration JSON, if you move them out of the site they will retain their current configuration.

For some applications, you will want multiple gateways to be in the same site, and to receive the same configuration template, but with certain values substituted unique to each gateway. To achieve this behavior, Rigado has developed a feature called “Configuration Variables”.

Creating a Configuration Variable

In order to use variables in your configuration, you first need to create the variables in Edge Direct. A top-level page will show you the available configuration variables, and allow you to create new ones

When you create a new variable, you specify its name and its type. The type will be used to generate a valid JSON configuration for each gateway.

The valid types of configuration variable are

  • String: any string of characters, symbols, or numerals (ex: "myConfigVar": "apple")
  • Number: any real number (ex: "myConfigVar": 1.4)
  • Boolean: a true or false value (ex: "myConfigVar": false)
  • Array: a list of values (ex: "myConfigVar": ["apple", 1.4, false])

Note

a fifth option of Object exists and may be used through the rigado CLI.

Once you have created the configuration variable, you may attach it to any number of sites or gateways.

Assigning a Configuration Variable to a Site

When assigning a configuration variable to a site, you have the option to make that variable required for all gateways in the site, as well as the option to provide a default value for that variable.

  • Required: A site with a required configuration variable will not apply configurations to a gateway unless (a) that gateway has a value for the configuration variable, or (b) the site has a default value for the configuration variable.
  • Default value: If a gateway in the site does not specify its own value for this configuration variable, it will use the site’s default value.

Assigning a Configuration Variable to a Gateway

When assigning a configuration variable to a gateway, you may provide a value for that gateway to use in its configuration.

A gateway will inherit the default values from all of its site’s configuration variables that it does not override.

Using Configuration Variables in a Configuration

Once you’ve created a configuration variable and assigned it to a site or a gateway, you may begin using it in your configuration JSON. The syntax is to replace your desired value with the object:

{
   "VarSub": "key"
}

where key is the name of the configuration variable. This whole object will be replaced by the configuration variable value when the configuration is applied to a gateway.

For example, let’s say you have a site with multiple gateways that each need to use a different wireless network. Your desired configuration is of the format

{
   "connections": {
      "office-wifi": {
         "802-11-wireless": {
            "security": "802-11-wireless-security",
            "ssid": "office-wifi-east-2"
         },
         "802-11-wireless-security": {
            "key-mgmt": "wpa-psk",
            "psk": "superSecretWifiPassword"
         },
         "connection": {
            "autoconnect-priority": 0,
            "id": "office-wifi-east-2",
            "type": "802-11-wireless"
         },
         "ipv4": {
            "may-fail": true,
            "method": "auto",
            "route-metric": -1
         }
      }
   }
}

In this example, we want to make the network SSID and password come from configuration variables. We start by creating new configuration variables named wifiSSID and wifiPSK (both of type String).

../_images/example-1.png

Figure 3.8 Our new configuration variables wifiSSID and wifiPSK

In our example situation, all gateways are first powered on in a test lab, and we want to make sure any new gateways entering the site will receive credentials for the test lab’s network. To this end, we will assign default values in the site’s configuration variables:

../_images/example-2.png

Figure 3.9 Default values for configuration variables wifiSSID and wifiPSK

3.4.3. 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.10 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.4.4. 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.11 Updating a gateway’s NTP Server and Time Zone settings

3.4.5. 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.4.6. 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.12 Updating the EAP Mode configuration for a gateway