Docs
Go to Edge Direct App

Configuration

Suggest Edits

To effectively manage distributed networks at scale, it's important to have a way to change hardware and software configurations, deploy those changes and track their status. Edge Direct manages this by using Stateful configurations that store a complete copy of the deployed Gateway & Container Configurations in the cloud and monitor the deployment status. Customers can use Configuration to control system configurations like Network connections & settings, Edge Connect Recipes, and software updates. Updates for Configurations can be queued asynchronously for offline hardware or scheduled to be applied at specific times through Maintenance Windows.

Configurations can be applied to individual Gateways or to a group of Gateways at the Site level. Gateways assigned to a Site can still have unique Configuration where needed through use of configuration variables.

How Configuration Works

Rigado hardware and software are conveniently managed through the Edge Direct management portal. This ensures that any change requested by users are carefully validated and orchestrated, delivering secure deployment through encrypted connections to edge hardware.

Whenever a new Configuration change is submitted, Edge Direct automatically validates, formats, and securely stores the change on the server. The Configuration change is queued, awaiting retrieval by the hardware during its next check-in or when its designated Maintenance Window is open. Once the hardware is prepared to receive the Configuration update, it fetches and attempts to apply it. The progress of this application status is continuously tracked and displayed in Edge Direct, enabling users to monitor the status of their updates.

Storing the Configuration in Edge Direct allows for status tracking and easy recovery if, for any reason, the hardware encounters difficulties during the application process. This real-time tracking capability allows for seamless monitoring of update rollouts.

🚧

For a Gateway or Container to retrieve a Configuration update it needs to be powered on and Online in Edge direct, requiring an active network connection.

Configuration Status

On the Configuration tab of a Site, you can see a breakdown of each type of Configuration and how many Gateways are in each status for a given type. Similarly, the Configuration tab of a Gateway will track each of the Configuration types and the status of deployment onto that Gateway.

Types of Configuration Status

  • SCHEDULED: A Configuration update has been made but is waiting for an open Maintenance Window to deploy. This status is only valid for Hardware assigned to a Site.
  • PENDING: The Configuration update is available for the Hardware, but the Hardware has not yet received it.
  • IN PROGRESS: The Hardware is actively applying the configuration.
  • APPLIED: The Configuration update has successfully applied the configuration and reported completion to Edge Direct.
  • ERROR: The Hardware attempted to apply the configuration but was unsuccessful and reported an Error to Edge Direct.

Configuration Rollout

The main method of deploying updates is to change the desired Configuration of a Site to trigger an automated rollout to multiple Gateways & Containers. A typical deployment flow will follow the path outlined below:

  1. A new Configuration is submitted to a Site where it’s saved as the Site’s scheduled Configuration. The status will go to SCHEDULED for all of the Site’s Hardware. The status will remain SCHEDULED until the Site’s Maintenance Window opens. In the Site Configuration tab, it will show an update is now scheduled, but the Gateway status will continue to track the previous released configuration status until the Maintenance Window opens. If the Site has an “ongoing” Maintenance Window, the configuration instead enters the PENDING status immediately.

📘

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 the Maintenance Window opens will be ignored.

  1. Once the Site’s Maintenance Window opens, all SCHEDULED Configuration updates replace the current Configurations. The Configurations enter the PENDING status for each Gateway/Container while Edge Direct waits for the Hardware to check-in. The status will remain PENDING until the server receives acknowledgement from the Hardware that it has received the configuration.
  2. When the Hardware receives a Configuration, the status changes to IN PROGRESS. The status remains IN PROGRESS while the hardware applies the updated Configuration.
  3. When the Hardware successfully applies the updated Configuration, the Desired Configuration’s status will change to APPLIED.
    1. If the hardware encounters an issue while applying the Configuration, the status of the Desired Configuration will change to ERROR. The Hardware will stop trying to apply the updated Configuration and will continue operating with it's current Configuration. Details on the issue can be found in the specific Configuration category sub page, which can be found by clicking the View or Edit link in line.

📘

Updating individual Gateways can be done only when it is Unassigned from a Site. In this case, Configuration updates skip the SCHEDULED status and goes straight into PENDING.

Managing Configurations

Configurations are built to be modular and easily modified or copied between Sites. There are three management options available in the Configurations menu:

  • Edit: Opens the configuration pane to change the current configuration.
  • Import: Opens an import prompt that allows copying of a Configuration of that type from another Site.
  • View: Opens a read-only version of the Configuration pane. Some Configurations are not editable due to user permissions & management. All Individual Gateway Configurations are set to view-only when assigned to a Site, since the Configuration is managed at that level.

Editing a Configuration

To edit a configuration, simply click on the Edit button in-line with the Configuration type. This opens a Configuration pane that is unique to each Configuration type.

When editing a Configuration, Edge Direct will perform real-time validation on the Configuration to ensure it is formatted correctly before allowing submission. The Submit button will be grayed out if the current Configuration is not valid.

Once done modifying the configuration, clicking the Submit button will bring up the Authorize Configuration Update window pictured below. This window provides two options:

  • Queue: This is the default option for any Configuration when the Site has a set Maintenance Window. This will set the Configuration update as Scheduled, not applying the Configuration until the next Maintenance Window opens.
  • Authorize: This option will force an immediate roll out of the Configuration update to all assigned Gateways & Containers, even if outside a Maintenance Window. To perform this, the user must type authorize into the provided field and the Queue button will then switch to Authorize.

Importing a Configuration

Importing Configurations is an easy way to propagate the same Configuration across multiple Sites. This allows the user to take an existing applied Configuration, make a copy, and apply it to the current Site. After clicking the Import button in line with the desired Configuration to update, the following Import window will appear. This window provides two options:

  • Site: Select the source Site to copy the Configuration from the drop down menu of other Sites with a Configuration of the same type applied.
  • Overwrite Variables: Overwrite all configuration variable values in the current Site with the values stored in the source Site. This only overwrites the Site level variables, not variables set on individual Gateways within the Site. Any new variables used in the source Site Configuration that are not in the current Site will be imported automatically, regardless of this being selected.

After submitting the Import request, it will bring up the Authorize Configuration Update window. Follow the same flow as Editing a Configuration to finish applying the Configuration import.

Configuration Variables

Some Configurations require unique values to be set for individual Gateways and Containers within a Site. Since Sites function on a shared Configuration, Edge Direct has the option to add configuration variables to allow for such unique values. Configuration Variables enable users to set a generic variable in a Site Configuration and then assign it different values at either the Site or individual Hardware level.

📘

Configuration Variables can assign values at both the Site and Gateway level. If a value is present at the Gateway level it takes priority and the Site level value will be ignored.

Creating a new Configuration Variable

To use variables in a Configuration, a variable first needs to be defined in Edge Direct. This can be done in the configuration variables page, which is accessed through the main menu on the left. This page will show all currently defined configuration variables, and allow creation of new variables.

📘

The Configuration Variables page can only be accessed by Administrators.

To create a new variable, click the "Create New Variable" button in the top right. This will bring up the Create Variable window, which requires a unique name and variable type. The type will be used to generate a valid JSON Configuration for each Gateway. It also gives the option to make the variable hidden, which prevents a value from being displayed or read back after it is submitted. To learn more about hidden variables, see the below Configuration Secrets section.

The types of configuration variables available 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])
  • Object: A snippet of JSON to be used to replace whole blocks of configuration

Once the new Configuration Variable has been created, it can be imported and used across any number of Sites and Gateways.

Using a Configuration Variable in a Site

To use a configuration variable in a Site, navigate to the configuration tab and at the bottom click the "Import Variable" button. This will bring up the Import Variable window, where you can select the variable to use, specify if it's Required and a Default Value. Both settings, Required and Default Value, are optional.

Setting a Configuration variable to Required will require it to have a value defined at either the Site or Gateway level before Edge Direct will attempt to apply a Configuration using the variable. This is useful for validation when deploying new Sites to ensure all Hardware gets the proper values needed set. If a Required variable is not set, Edge Direct will set the Configuration using it to ERROR and display an Error message.

Default Value is the value that will be applied to all hardware in the Site if they are not defined at the Gateway or Container level. This can be changed after Variables are imported as well. Configuration variables with values set at the Gateway or Container level will always be used in place of any Site defaults.

Assigning a Configuration Variable to a Gateway

To assign a configuration variable to a Gateway or Container, navigate to the configuration tab in the details pane of the desired Gateway/Container and click the "Import Variable" button near the bottom of the page. This will bring up the Import Variable screen, where you can select the variable to use and specify a value to be used.

📘

If a Configuration uses a variable that is not defined at the Gateway level, it will use the default value defined at the Site level.

📘

Configuration Variables are only used in Site level Configurations. Unassigned Gateways will not use Configuration variable substitutions in Configurations.

Applying Configuration Variables to a Configuration

To use a configuration variable it needs to be called in the Configuration. This can be done multiple ways through the Edge Direct web portal, or API/CLI by directly editing the Configuration JSON. For further instructions on how to apply a configuration variable in the web portal, proceed to the Configuration Types section below for details.

Inserting directly into Configuration JSON

The syntax to use a Configuration Variable to inject the desired variable within the JSON object is:

{
   "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, a Site with multiple Gateways that each need to use a different wireless network. Each Gateway needs a unique WiFi SSID and password, which the variables wifiSSID and wifiPSk are used for.

To apply to the Network Configuration JSON, on the associated lines for "ssid"and "psk" insert the "VarSub" snipet above with the corresponding configuration variable in place of the key. The result will look like:

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

Configuration Secrets

Since Edge Direct stores copies of all Configurations for scheduling & recovery of updates, it is important to securely store and protect any sensitive data from being accessed by users. Edge Direct addresses this through robust data filtering and redaction to ensure it never shows sensitive data to a human user. It relies on two mechanisms to achieve this:

  • Configuration Variables with the "Hide Value" flag enabled
  • A list of sensitive keywords that will always have values redacted (EX: Wireless Network passwords)

If a Configuration contains either of these two keys, it will automatically redact the value populated and replace it with a redaction string consisting of REDACTED and a sha256 hash of the Configuration Value. This allows Edge Direct to track where a secret is being used across Configurations and Sites, so a Configuration using a sensitive keyword can be copied across new Sites without the value being lost. This also allows Edge Direct users to compare the Redacted strings between Gateways or across update revisions to see if the value is the same, even though they cannot see or access the unencrypted values. At no point is the actual value of a sensitive field ever returned or exposed to users.

Configuration Types

Configurations are split into categories that each control a different aspect of the overall Configuration. There are five categories available for use:

  • App Set: Controls the settings for IoT data & connectivity applications, specifically Edge Connect. This category applies to both Gateways and third party hardware running Edge Connect containers.
  • NTP Time Server: Controls the time-server settings of Gateways.
  • Network: Controls the network backhaul interface Configurations of Gateways.
  • Managed Refresh: Controls the minimum revision of system software of Gateways. If a Gateway is running software below the minimum revision, it will trigger a secure update.
  • Edge Direct Cloud: Controls the Gateway cloud hosts used to communicate with Edge Direct. Current options are Azure or AWS clouds.

All Configurations are securely stored and transmitted in JSON. Configurations are all validated by Edge Direct before being deployed to Hardware. The Edge Direct web interface provides user-friendly forms for some Configuration categories, and an Advanced option for JSON editing when needed.

The Rigado API and CLI are both available to set raw JSON configuration files for all config types in Edge Direct.

App Set

App Set controls the configuration for IoT data & connectivity for Edge Connect and other applications. This configuration controls which Edge Connect Recipes are enabled in a Site.

The App Set configuration details pane lists all Recipes used in the active configuration. It also allows viewing and updating of the App Set Configuration JSON if needed.

App Set configurations are typically built and maintained by Recipe publishers or customer engineering teams and are consistent across a solution use case/application. App Sets for a use case are typically stored in template Sites and propagated across Sites by importing the configuration. If an update to the App Set is required, please consult the Recipe publisher or Rigado support.

Customers who maintain their own Edge Connect Recipes and Configurations can manage updates through this Configuration. See Edge Connect Configuration for reference on building a custom App Set.

NTP Server & Time Zone

The Network Time Protocol (NTP) server that Gateways will use for clock synchronization is configured within the Configuration tab.

The following fields are available for configuration:

  • NTP Server: The primary server Gateways will use for clock synchronization.
  • NTP Backup Server: The backup server Gateways will use.
  • NTP Timezone: The timezone your Site & Gateway is in. The timezone selected must be recognized by the IANA timezone database.

Network

The Network configuration type in Edge Direct controls the different interfaces a Gateway can use for network backhaul. All Gateways have Ethernet and WiFi network capability, and select models include Cellular 4G/3G as well.

All Network configurations have a DHCP Ethernet configuration by default that cannot be deleted. To add a new network connection, click on the + Add a ___ Connection text and it will open a fillable form to enter network credentials.

📘

Network configuration only controls the allowed network connections for data backhaul. It does not control which remote hosts a Gateway connects to. Check with the local network administrator that the proper ports and hosts are allowed on a network prior to installation. The full list of remote host network requirements can be found in Prerequisites

To use configuration variables within Network Configurations present in a Site, click on the Network field and it will bring up a list of available variables to use. Selecting a variable will automatically assign it as the value of that field in the Configuration.

Configure Wireless

Required Wireless Fields

The following fields are required to be present in order to create a valid network configuration:

  • Connection Profile Name: This is the network alias name of the connection used by Edge Direct. It is not used in the network connection and does not need to match network name/SSID.
  • Wireless SSID: This is the Service Set Identifier, or primary name associated with a wireless network. SSIDs are case sensitive and can be up to 32 alphanumeric characters.
  • Wireless Network password: This is the password for the Wireless SSID. After initial entry this field will be redacted to protect from readback.

Advanced Wireless Fields

The following fields are optional and only used for Advanced configuration. Please consult your network administrator or Rigado Support before setting these, as misconfiguration could result in poor or no network connectivity.

  • WiFi Region: This field sets the Region the Site is located in and changes which WiFi bands are used depending on local regulations. If the your location is not listed it is recommended to use Worldwide for this setting if using WiFi. This setting is not used if there is no WiFi configuration.
  • 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. If only one WiFi network is defined it is recommended to leave this as Auto.
  • 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.
  • Static IP: This field is sets the Static IP the gateway will use for this connection. All network settings are configured to use DHCP by default. Static IP should only be selected when required by your network administrator.
  • DNS Server: DNS server address, for use with Static IP configurations only.
  • Static Gateway: Static Gateway, for use with Static IP configurations only.
  • CIDR Prefix of a Subnet: Network Subnet range, for use with Static IP configurations only.

Configure Ethernet

By Default, all Network configurations have a DHCP Ethernet configuration that cannot be deleted. The Configure Ethernet configuration allows adding a Static IP configuration to this interface. The following fields are available for configuration:

❗️

Setting a Static IP for Ethernet will take priority over the DHCP configuration, and can cause the Gateway to lose connection to the Internet. Rigado strongly recommends configuring a valid backup Wi-Fi and/or Cellular network connection before configuring a static ethernet connection.

Advanced Fields

The following fields are optional and only used for Advanced configuration. Please consult your network administrator or Rigado Support before setting these, as misconfiguration could result in poor or no network connectivity.

  • Connection Profile Name: This is the network alias name of the connection used by Edge Direct. It is not used in the network connection and does not need to match network name
  • Route Metric: This 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.
  • Static IP: This field sets the Static IP the Gateway will use for this connection. All network settings are configured to use DHCP by default. Static IP should only be selected when required by your network administrator.
  • DNS Server: DNS server address, for use Static IP configurations only.
  • Static Gateway: Static Gateway, for use with Static IP configurations only.
  • CIDR Prefix of a Subnet: Network Subnet range, for use with Static IP configurations only.

Configure Cellular

A valid Cellular Configuration is required for Gateways to use the Cellular modem. This Configuration can be applied to sites with a mix of cellular and non-cellular Gateway models. Gateways models without a Cellular modem will automatically ignore these Configurations.

In the event that a new cellular configuration or a modification is required, 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.

Required Fields

The following fields are required to be present in order to create a valid network configuration:

  • Connection Profile Name: This is the network alias name of the connection used by Edge Direct. It is not used in the network connection and does not need to match network name/carrier.
  • Cellular APN: Access Point Name provided by your cellular provider; this field is required in order to establish a cellular connection. The APN must match the SIM card installed in the Gateway in order to authenticate to the cell carrier network. The APN is unique for each carrier, and in some cases, customer specific.

Advanced Fields

The following fields are optional and only used for Advanced configuration. Please consult your cellular network provider or Rigado Support before setting these, as misconfiguration could result in poor or no network connectivity.

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

Managed Refresh

Managed Refresh controls updating of the system software for Cascade series Gateways. Through setting a Managed Refresh Configuration, customers can ensure that all Gateways assigned to a Site are running at least the minimum required revisions of software to support the latest features and security updates.

All Cascade Gateways run the Linux operating system Ubuntu Core. Ubuntu Core is designed for distributed IoT systems to be modular and secure at scale, as part of this all system software runs in containers called Snaps. This allows each component of the OS to be updated independently instead of requiring a bulk update of the entire OS to save on data usage. All updates are securely hosted in a dedicated Canonical Snap Store managed by Rigado with secure factory provisioning of every Gateway.

Managed Refresh Configuration

The Managed Refresh Configuration consists of a list of system Snap names and associated release information:

  • Release Channel: Ubuntu Core uses Channels to control release roll-out of software versions. Production Gateways will primarily use Stable and occasionally Candidate releases. The available Channels are:
    • Edge - most recent release, usually development or test releases not fully tested
    • Beta - preview release with tested changes, updates still may be needed
    • Candidate - feature complete releases with no planned changes
    • Stable - production tested and published releases for general use
  • Minimum Revision: The minimum acceptable release revision of the software that a Gateway needs to meet. All Snaps are individually released and versioned for traceability.

Gateway System Snaps under management are:

  • cascade: Gateway specific configuration for hardware
  • cascade-configuration: Performs boot time configuration tasks for the Gateway
  • cascade-kernel: Ubuntu Core Linux kernel
  • core: Base Ubuntu Core Linux operating system
  • modem-manager: Utilities to configure and manage the cellular LTE modem
  • network-manager: Utilities to configure and manage all network interfaces
  • pivot-agent: Tool to provision Gateways to Canonical Snap Store
  • rigado-deviceops: Rigado management software to control Gateway functionality and interface with Edge Direct
  • rigado-edge-connect: Rigado IoT Device connectivity, edge data processing & data delivery software

To update Managed Refresh, you can Import a configuration from another Site and apply it to the new Site.

Rigado provides quarterly release updates to Managed Refresh made available to customers which has been further tested for interoperability and reliability on Gateways. It is recommended to use these quarterly release Configurations.

📘

Managed Refresh is not able to be manually edited by Customers to limit issues with interoperability between different revision system Snaps. Rigado makes quarterly update Configurations available for customers to import across Sites.

Gateway Updating Process

Whenever a new Managed Refresh Configuration is applied to a Gateway it will compare its current list of Snap revisions to the desired Minimum Revision from the Configuration. If any Snaps are below that Minimum Revision it will attempt to connect to the Canonical Snap Store and update that Snap to the latest available version on the Store.

For security, the Gateway will only accept updates from the Snap Store. What Managed Refresh does, is dictate when and what a Gateway needs to update.

Once Managed Refresh triggers an update, the Gateway will connect and download the file from the Snap Store. When the new version download is complete, the Gateway will stop the current running Snap, and then load & run the new version. If for any reason the new version fails, it will revert back to the previous working version of the Snap and report an error. Once the new Snap is running or failed to run, it will report back to Edge Direct with the new version.

Managed Refresh will stay in the IN PROGRESS state until all Snaps have been updated and meet the minimum specified revision. Once the Gateway has finished updating all Snaps to meet the Managed Refresh configuration, the Configuration will change to APPLIED.

Edge Direct Cloud

The Selected Edge Direct Cloud Configuration controls which cloud host a Gateway will use for secure communication to Edge Direct. The two options available are Microsoft Azure and Amazon Web Services (AWS).

Further details on the full list of hosts can be found in the Prerequisites section of the docs. When the Configuration shows "Unassigned Cloud" that indicates that there is no default set, and the Gateways in the site will default to their factory provisioned cloud hosts.

To Edit the selected Cloud, click the Edit button, which will bring up the Configuration pane. This pane will provide the two options outlined above. Select one of the two options and click the Submit button to apply the Configuration update.

🚧

Edge Direct Cloud selection is not able to be scheduled. Updates will immediately apply to all Gateways in the site as soon as it is submitted. Changing this configuration impacts network firewall requirements. Please check with your IT administrator before updating.

Updated about 2 months ago

What’s Next