Note

You are viewing the legacy Cascade documentation, which only applies to some Rigado customers. To view the current Cascade documentation, click here.

2.2. Configuring a Gateway

2.2.1. Introduction

Configuration information can be sent to an individual Gateway to configure the Network Settings, NTP Time Server/Time Zone, as well as individual App settings. Configuration information is provided in a JSON file, which can be input into either the rigado gateway configure CLI command (docs) or to the /v1/gateways/{serial}/configure API endpoint (docs).

Important

A Gateway must be online to receive configuration commands. A configuration command—and its payload—will only be sent to a Gateway once. If the Gateway is offline, it will not receive the new configuration.

Note

Gateway network and time configuration is also available through the Edge Direct web application. See Gateway Network Configuration.

2.2.2. JSON Document

Configuration is sent to a Gateway using a JSON document that follows the format described in the GatewayConfig API documentation.

{
    "apps": {
     "my-favorite-app": {
       "values": {
         "extra.logging.enabled": false,
         "parameter.name": "important value",
         "password": "abc12345"
       }
     },
     "my-other-app": {
       "values": {
         "worker.count": 33
       }
     }
    },
    "network": {
     "office-wifi": {
       "wireless": {
         "ssid": "my-network",
         "security": {
           "password": "secret-password"
         }
       }
     }
    },
    "time": {
     "ntp": {
       "server": "ntp.ubuntu.com",
       "backup": "pool.ntp.org"
     },
     "zone": "America/Los_Angeles"
    }
}

The three major parts of this configuration are Apps, Network, and Time. You can include any or all of them in a single configuration command.

Note

If any configuration changes require the Gateway to reboot, other configuration changes may not be performed. To make changes that require rebooting, we recommend you run separate configuration commands with the corresponding JSON payloads. Currently the only configuration that triggers a reboot is the NTP server in Time Config (see below).

App Configuration

The first kind of Gateway Configuration is for apps. This section of the JSON must match the following schema:

{
   "app-name-1": {
      "values": {
         "key1": "value1",
         ...
      }
   },
   ...
}

When this configuration is sent to the Gateway, the Edge Direct agent on the Gateway will perform snap set commands on each of the apps listed, using the keys and values listed.

It is important to know that after the configuration is applied (the snap set commands executed) the agent on the Gateway restarts the app which config options have been set.

This is the default behavior, however in case it is not desired it can be changed. Each app that should not be restarted must set a config option restartAfterConfig to value false.

Note that it is not necessary, although does no harm at all, to set this option to true for the apps that should continue being restarted. This is because a lack of this option or any other value than false triggers a restart.

To learn more about snap configuration, see Configuration in snaps. To learn more about setting a configuration hook for your snap, see The configure hook.

Network Configuration

The second kind of Gateway Configuration is for network connections. This section of the JSON must match the following schema:

{
   "connection-name-1": NetworkConnection,
   "connection-name-2": NetworkConnection,
   ...
}

A NetworkConnection object is described in greater detail in the API documentation, but it contains all the configuration options necessary for many different types of network connection.

When this configuration is sent to the Gateway, the Edge Direct agent on the Gateway will attempt to implement the network connections described in the payload.

At this time, the only way to delete network configurations is by sending a network-reset command. More information about this command can be found in the CLI documentation.

Example configurations for various types of network can be found below.

Updating a Connection

A network configuration payload includes a connection name in order to be able to update the connection later. If you want to update the details of a configuration, send a new configuration payload with the same connection name. For instance, if you send the initial configuration:

{
   "network": {
      "office-wifi": {
         "ipv4": {
            "method": "auto"
         },
         "wireless": {
            "ssid": "office",
            "security": {
               "password": "password",
               "keyManagement": "wpa-psk"
            }
         }
      }
   }
}

the Gateway agent will attempt to connect to the Wi-Fi network office using DHCP. If you then wanted to switch this connection to using a static IP, you would send a new configuration with the same connection name and updated details.

{
   "network": {
      "office-wifi": {
         "ipv4": {
            "method": "manual",
            "staticAddress": {
               "gateway": "192.168.1.1",
               "ip": "192.168.1.199",
               "subnetMask": "24"
            }
         },
         "wireless": {
            "ssid": "office",
            "security": {
               "password": "password",
               "keyManagement": "wpa-psk"
            }
         }
      }
   }
}

Note

We strongly recommend you keep an active ethernet connection during network configuration so that in case of breaking changes to wireless networks, the Gateway can still receive new configuration commands.

The above example may not be robust enough for some deployments. For instance, if the password of that wireless network changes, you would want a second configuration in place before that change. This second configuration will use the new password, so that when the Gateway agent attempts each connection, at least one will succeed.

{
   "network": {
      "office-wifi-updated": {
         "ipv4": {
            "method": "auto"
         },
         "wireless": {
            "ssid": "office",
            "security": {
               "password": "new-password",
               "keyManagement": "wpa-psk"
            }
         }
      }
   }
}

The key point here is that the connection name office-wifi-updated is different from the original connection name office-wifi, and thus the Gateway will have both connections configured. Only one will have a password that works for the network, but the Gateway will try both according to the specified autoconnectPriority.

Prioritizing Connections

Each network connection can be configured with an autoconnectPriority. If the connection is set to autoconnect, connections with higher priority will be preferred. Defaults to 0. The higher number means higher priority.

Time Configuration

The third kind of Gateway Configuration is for time settings. This section of the JSON must match the following schema:

{
   "ntp": {
      "server": "my-first-choice.com",
      "backup": "pool.ntp.org"
   },
   "zone": "America/New_York"
}

The ntp setting and the zone setting are both optional.

Note

If you set an NTP server and/or backup server, the Gateway may reboot. We recommend that if you have to set the Gateway’s NTP server, do so in its own configuration command, without any Apps or Network configuration in the same payload. You may set NTP server and timezone in the same command.

The timezone string must be recognized by the IANA timezone database. If it is not, the Edge Direct API will return an error before sending the configuration to the Gateway.

Network Configuration Examples

Ethernet DHCP

This example shows how to set the Gateway’s ethernet interface to use DHCP for claiming an IP address.

{
   "network": {
      "Ethernet-DHCP": {
         "autoconnectPriority": -99,
         "ipv4":{
             "method":"auto"
         }
      }
   }
}

The low autoconnectPriority means this connection will be autoconnected only after those above it have been attempted.

The ethernet interface is assumed, since the wireless key is not part of this connection.

Ethernet Static IP

This example shows how to set a static IP address for the Gateway’s ethernet interface.

Warning

Use this configuration with extreme caution. If the router your Gateway is connected to does not honor that IP address, this Gateway could become unreachable. We strongly recommend you keep the ethernet connection configured to use DHCP.

{
   "network": {
      "Ethernet-STATIC": {
         "autoconnectPriority": 1,
         "ipv4": {
            "dns": [
               "8.8.8.8"
            ],
            "method": "manual",
            "staticAddress": {
               "gateway": "192.168.1.1",
               "ip": "192.168.1.136",
               "subnetMask": "24"
            }
         }
      }
   }
}

WPA2 (PSK) DHCP

This example shows how to configure the Gateway’s wireless interface to connect to a WPA2-PSK network using DHCP.

{
   "network": {
      "Wireless-WPA2-PSK-DHCP": {
         "ipv4": {
            "method": "auto"
         },
         "wireless": {
            "ssid": "my-wifi-network-ssid",
            "security": {
               "password": "password",
               "keyManagement": "wpa-psk"
            }
         }
      }
   }
}

WPA2 (PSK) Static IP

This example shows how to configure the Gateway’s wireless interface to connect to a WPA2-PSK network using a static IP address.

{
   "network": {
      "Wireless-WPA2-PSK-STATIC": {
         "wireless": {
            "ssid": "my-wifi-network-ssid",
            "security": {
               "password": "password",
               "keyManagement": "wpa-psk"
            }
         },
         "ipv4": {
            "method": "manual",
            "staticAddress": {
               "gateway": "192.168.1.1",
               "ip": "192.168.1.199",
               "subnetMask": "24"
            }
         }
      }
   }
}

WPA2 (EAP 802.1x) DHCP

This example shows how to configure a Gateway’s wireless interface to connect to a WPA2-EAP-802.1x network using DHCP.

{
  "network": {
      "Wireless-WPA2-EAP-8021x-DHCP": {
         "wireless": {
            "ssid":"my-wifi-ssid",
            "security":{
               "keyManagement":"wpa-eap"
            }
         },
         "eap":{
            "method":["peap"],
            "phase2auth":"mschapv2",
            "identity":"username",
            "password":"password"
         }
      }
   }
}

WPA2 (EAP 802.1x) Static IP

This example shows how to configure a Gateway’s wireless interface to connect to a WPA2-EAP-802.1x network using a static IP address.

{
   "network": {
      "Wireless-WPA2-EAP-8021x-STATIC": {
         "wireless": {
            "ssid":"my-wifi-ssid",
            "security":{
               "keyManagement":"wpa-eap"
            }
         },
         "eap":{
            "method":["peap"],
            "phase2auth":"mschapv2",
            "identity":"username",
            "password":"password"
         },
         "ipv4": {
            "dns": [
               "8.8.8.8"
            ],
            "method": "manual",
            "staticAddress": {
               "gateway": "192.168.1.1",
               "ip": "192.168.1.118",
               "subnetMask": "24"
            }
         }
      }
   }
}

2.2.3. Edge Direct Web-App

The Network Configuration tool provides configuration settings to connect to a Wi-Fi network, establish a Static IP, connect to a specific NTP server, or configure cellular network settings.

A pre-existing network connection is required in order to perform any of the network configuration steps.

Note

The input fields for these configuration settings do not have any restrictions, please be sure verify information is correct prior to submitting.

Please contact Rigado Solutions Engineering for assistance with gateway configuration.

To open the Network Configuration tool, select the Network tab in the gateway detail view, then select CONFIGURE.

../_images/network-configure-1.png

Figure 2.2 Gateway detail view, showing the Configure button

../_images/network-configure-2.png

Figure 2.3 Gateway detail view, with Network Configuration Tool open

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.

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.

Configure NTP

The network time protocol 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.

Note

Sending a new NTP configuration to a gateway may cause it to reboot. Avoid making other configuration changes until the gateway is fully online again.

Note

You are viewing the legacy Cascade documentation, which only applies to some Rigado customers. To view the current Cascade documentation, click here.