Gateway Edge Agent Usage

Losant’s Gateway Edge Agent (GEA) is a command-line utility exposed through Docker as a container that you run on your Edge Compute device(s). To get the Edge Agent running on your device, follow along with the video below.

For help getting the Docker and GEA installed on your device, see the installation instructions. All command examples below assume you can run docker without sudo or that you are logged in as root (not recommended). If you wish to run docker as your current user, see these instructions.

Running the GEA: Quick Start

Below is the minimum command required to start the GEA. This command works well during evaluation to quickly get an instance of the GEA up and running. The rest of this document describes other configuration options that are recommended for production deployments.

docker run --restart=always -d \
-e "DEVICE_ID=YOUR_DEVICE_ID" \
-e "ACCESS_KEY=YOUR_ACCESS_KEY" \
-e "ACCESS_SECRET=YOUR_ACCESS_SECRET" \
losant/edge-agent

Creating a Storage Area

It is strongly recommended to mount a volume from the host file system into the GEA’s Docker container. This allows any data created by the GEA to be persisted when the container is removed (for instance, when upgrading the GEA Docker image).

1. Create a data directory on your host file system at the path of your choosing. This can be done with the following command:

sudo mkdir -p /var/lib/losant-edge-agent/data

If you intend to use on-disk workflows, you’ll also need to create a workflows subdirectory.

sudo mkdir -p /var/lib/losant-edge-agent/data/workflows

2. Change the owner of the parent directory (and all subdirectories) so the GEA can read and write to these locations. The GEA’s user ID and group ID are both 999.

sudo chown -R 999:999 /var/lib/losant-edge-agent

3. When starting the container, use the -v argument to mount your data directory into the container at /data.

-v /var/lib/losant-edge-agent/data:/data

The GEA places a file named losant-edge-agent-store.db in the /data directory. This is a database file that contains the following information:

• Edge workflows: Contains workflows that have been deployed to this device from the cloud. This allows the GEA to begin executing previously deployed workflows immediately upon a system or container restart.
• Workflow storage: Contains data persisted across workflow executions using the Storage: Set Value Node, and accessed using the Storage: Get Value Node.
• Buffered messages: Contains any device state or other MQTT messages that the agent attempted to send while not being connected to Losant’s MQTT broker. When the connection is re-established, these messages will be sent to the platform.
• Custom files: This directory is also a good location to write any custom files that your workflows may need to create. The File: Write Node can be used to create files at any location within the container (as long as the GEA user has permission), but if that location is not a volume mounted from the host, those files will be lost when the container is removed. If you do not require custom files to be persisted, we recommend writing files inside the container at /home/losant.

Running With a Configuration File

The GEA has many configuration options, most of which can be set with a TOML-formatted configuration file. The configuration file can be created using any text editor you prefer. It’s then mounted into the container where it can be read by the GEA.

Below is the minimum configuration file:

[gateway]
id = '<your-device-id>'
key = '<your-access-key>'
secret = '<your-access-secret>'

You can download a configuration file with all available options from the Device Actions menu on your device’s overview page. It is recommended to start from this file and modify as needed.

The configuration file must be mounted into the container at /etc/losant/losant-edge-agent-config.toml. This is done using the -v argument when starting the GEA container. The following example assumes the config.toml file is in the storage location defined in the previous section.

-v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml

Making Changes To The Configuration File

A configuration file allows you to modify the GEA’s configuration without destroying the container (as opposed to environment variables). For example, let’s increase the log level from info (default) to verbose. Verbose logging can be useful for short periods of time to help debug specific issues. Verbose logging produces a large amount of data and is not recommended as the default setting for production deployments.

[logger]
level = 'verbose'

Once the desired configuration change is made, you can restart the GEA container using the Docker CLI:

docker restart CONTAINER_ID

You can find the container ID by first running the docker ps command.

Triggers

Some edge workflow triggers can retrieve their configuration from the GEA’s configuration file. For example, when creating an MQTT Trigger that connects to an external broker, the details of that connection must be defined in the configuration file. Not all triggers support this feature, so please see the documentation for your desired trigger for details.

Your configuration file can have any number of trigger configurations. In the TOML syntax, they are defined as an Array of Tables named triggers.

For example, you can have configuration for the OPC UA Trigger, the MQTT Trigger, and the Beckhoff Trigger by adding the following sections to your configuration file.

# Entry for the OPC UA configuration
[[triggers]]
name = 'myOPCUAconfig'
type = 'opcua'
uri = 'opc.tcp://localhost:4335/UA/Server'
eventFilter = ['Value']

[[triggers.monitoredItems]]
nameSpace = 1
identifier = 'i=2254'

[[triggers.monitoredItems]]
nameSpace = 1
identifier = 'i=2255'

## Another entry for the MQTT configuration
[[triggers]]
name = 'myMqttConfig'
type = 'mqttClient'
host = 'broker.example.com'
username = 'user'
password = 'pass'
clientId = 'myClientId'

## Another entry for the Beckhoff configuration
[[triggers]]
name = 'beckhoffTrig1'
type = 'beckhoff'
localAmsNetId = '192.168.5.221.1.2'
localAdsPort = 32750
targetAmsNetId = '5.123.154.18.1.1'
targetAdsPort = 851
routerHost = '127.0.0.1'
routerTcpPort = 48898
cycleTimeMs = 1000
subscriptionItems = [ 'GVL_Var.TestDint1', 'GVL_Var.TestDint2' ]

Every trigger requires the name and type fields. The name field is how you reference the configuration in your workflow. If the trigger supports this feature, there will be a field in the trigger’s editor where you can enter this name. The type field is specific to each trigger and the correct value can be found in each trigger’s documentation. All other fields are specific to each trigger.

Updating GEA Configuration from an Edge Workflow

It is possible to dynamically retrieve and modify the GEA’s configuration using the Agent Config: Get and Agent Config: Set Nodes. Changes made to the configuration using a workflow apply immediately and do not require any actions on the Docker container.

This functionality, paired with a Device: Command Trigger, allows you to remotely change the configuration of your fielded GEA instances at runtime.

When you invoke an Agent Config: Set Node, the GEA writes an updated configuration file to disk and then immediately applies that file. If you’ve mounted a configuration file from the host file system, the GEA must have write permission to that location. Configuration values defined through environment variables cannot be modified using this node.

Running With Environment Variables

In addition to a configuration file, the GEA also supports environment variables. Both can be used at the same time, however environment variables will override any values defined in the configuration file.

There are many environment variables available, but only three are required (DEVICE_ID, ACCESS_KEY, ACCESS_SECRET). Environment variables are set by adding one or more -e arguments to your docker run command.

docker run --restart=always -d \
-e "DEVICE_ID=YOUR_DEVICE_ID" \
-e "ACCESS_KEY=YOUR_ACCESS_KEY" \
-e "ACCESS_SECRET=YOUR_ACCESS_SECRET" \
losant/edge-agent

Unlike a configuration file, there is no way to change the value of an environment variable once the container has been started. To change an environment variable, you must stop (and optionally remove) the previous container and start a new container with the new variables defined. If you’re using a mounted storage location, all data will be persisted between the old and new container.

Environment variables are most common when using a third-party device management solution (e.g. Balena). These solutions typically provide a web interface to define configuration options that they will set as environment variables on your containers.

Web Server: HTTP Request Trigger / HTTP Response Node

If you wish to enable the HTTP Trigger for your Edge Compute device, you can do so by binding a host port at the time of container creation. To do this, add the -p flag to expose the port and then configure the GEA to enable the web server. See Docker’s exposing ports documentation for more information.

docker run -d --restart=always \
  -v /var/lib/losant-edge-agent/data:/data \
  -v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml \
  -p 8080:8080 \
  losant/edge-agent

# ...
[webserver]
enabled = true

Health Checks and Auto Restarting

As of version 1.49.0, the GEA supports Docker’s HEALTHCHECK functionality. This is enabled by default and automatically monitors the health of the GEA process. For example, if the GEA process is still alive but locked up or otherwise not responding, the container will be marked “unhealthy”.

You can optionally extend the healthcheck to monitor the GEA’s connection to the platform. This is not enabled by default because many use cases run the GEA in offline mode. To enable the healthcheck for platform connection, set the following configuration:

Environment Variable:

-e "HEALTH_CHECK_OFFLINE_IS_UNHEALTHY=true"

Configuration File:

[healthCheck]
offlineIsUnhealthy = true

When this configuration is enabled, the container will be marked unhealthy whenever the GEA loses the connection to the platform. The GEA uses Docker’s default healthcheck parameters. The healthcheck runs every 30 seconds and the container must fail the healthcheck three times in a row before being marked unhealthy. This means the container, by default, will be marked unhealthy if it’s been disconnected for 90 seconds. Docker supports changing these parameters by passing new values in the docker run command (--health-interval and --health-retries).

Automatically Restarting an Unhealthy Container

Docker does not restart unhealthy containers. The --restart=always flag only restarts a container if the process ends. It does not monitor the health status of a container.

To automatically restart unhealthy containers, we recommend running Autoheal. Autoheal is a very small container (~5MB) that monitors the health of other containers. When it detects an unhealthy container it will automatically restart it.

docker run -d \
  --name autoheal \
  --restart=always \
  -e AUTOHEAL_CONTAINER_LABEL=all \
  -v /var/run/docker.sock:/var/run/docker.sock \
  willfarrell/autoheal

The command above runs Autoheal and monitors all containers. If you have other containers that you want to exclude from Autoheal, you can do so through Autoheal’s configuration. Please refer to its documentation for details.

Managing the Gateway Edge Agent

Before we move on to more advanced ways of configuring the GEA, let’s quickly talk about how to manage it once it’s running. If you’re familiar with Docker, you can skip this section.

In general, the docker --help information is very useful for familiarizing yourself with the commands. Below, we’re going to cover some basic management commands (a few of which we’ve already started using). Let’s recap those plus some additional ones that should allow you to get up and running for basic use cases.

> docker run [-d] [--restart] [--rm] [--name] [-e] [-v] <image-name> (more info)

This command allows us to configure a container from a base image—in our case, losant/edge-agent. We’ve talked about most of the above options in this document as we’ve been using the GEA. The only one not mentioned elsewhere is the --rm flag, which will tell Docker to destroy the container after it has been stopped/killed. This is useful as you work to figure out your final configuration. There are, of course, many more flags you can use with docker run.

> docker logs [-f] <container-name|container-id> (more info)

This command allows us to look at the console output of the GEA after it has been started and is running. Unless you are writing your logs to a file, this is the primary way you’ll get a glimpse into what the GEA has been doing.

> docker ps -a (more info)

This command will output all containers that have been created on your host whether they are running or not. This is useful for getting the ID of the container running the Gateway Edge Agent after it has been started. It is also useful for getting the container ID of a stopped container so that you may restart it.

> docker stop <container-name|container-id> (more info)

You can stop a GEA container that is running in the background using the stop command. This will simply stop the container, but not destroy it. All your environment configuration and any other flags used when running docker run will be preserved when starting again.

> docker kill <container-name|container-id> (more info)

If the GEA container isn’t responding to a container stop command, you may need to kill the container. This will forcefully exit the container and could cause unexpected behavior on future runs of the Gateway Edge Agent.

> docker start <container-name|container-id> (more info)

After stopping a container, you can restart it using the start command. This will preserve all configuration that was entered when running docker run.

> docker restart <container-name|container-id> (more info)

Instead of running docker stop and then docker start, you can simply run docker restart.

> docker rm <container-name|container-id> (more info)

It’s a good practice to name your containers on your Edge Compute device to prevent many containers being created and taking up space on your device. Because of this practice, you’ll need to remove your container before creating another with the same name. Or, you can create a container with a different name as you determine the best way to run the Gateway Edge Agent on your device.

Agent Management Example

With these basic docker commands, we can manage our running GEA container. Note, this example shows how to remove a container and will destroy the container we have running permanently. You would need to create another container from the image if you do so.

$ docker logs docs-agent
0000-00-00T00:00:00.000Z [info] Agent Starting...
0000-00-00T00:00:00.000Z [info] Connecting to: mqtts://broker.losant.com...
0000-00-00T00:00:00.000Z [info] Webserver started on port: 8080
0000-00-00T00:00:00.000Z [info] Workflows initialized and running...
0000-00-00T00:00:00.000Z [info] Connected to mqtts://broker.losant.com
$ docker ps -a
CONTAINER ID   IMAGE                     COMMAND                   CREATED         STATUS        PORTS     NAMES
51aff3e4b650   losant/edge-agent:latest  "/opt/losant/tini -g..."  30 minutes ago  Up 5 minutes  8080/tcp  docs-agent
$ docker stop docs-agent
docs-agent
$ docker start docs-agent
docs-agent
$ docker kill docs-agent
docs-agent
$ docker ps -a
CONTAINER ID   IMAGE                     COMMAND                   CREATED         STATUS        PORTS     NAMES
51aff3e4b650   losant/edge-agent:latest  "/opt/losant/tini -g..."  31 minutes ago  Exited                  docs-agent
$ docker rm docs-agent
docs-agent
$ docker ps -a
CONTAINER ID   IMAGE                     COMMAND                   CREATED         STATUS        PORTS     NAMES

Viewing Container Logs Remotely

Starting with GEA version 1.44.0, Docker container logs can be remotely retrieved and streamed through the Losant interface. On the device’s “Edge Compute” tab, select a logging level (Error, Warning, Info, or Verbose) and click “Connect”.

If the Edge Compute device is running the agent and is connected to the MQTT broker, the panel will immediately return the most recent 256 messages of the selected log level and will continue streaming new messages in real time so long as the device remains connected.

Note: The interface can only return logs for the Docker container instance that is currently running the GEA - not other containers on the device, or containers that previously ran the GEA and were deleted.

Updating the Gateway Edge Agent

Updating the Gateway Edge Agent to the latest version is accomplished through a series of docker commands:

docker stop <container-name|container-id>
docker rm <container-name|container-id>
docker pull losant/edge-agent:<version of edge agent>
docker run …

With the following steps, the old container will be removed and replaced with a new container running the latest version of the Gateway Edge Agent. Note that if sudo is being used to pull, it should be used consistently to avoid unexpected behavior.

Updating Edge Workflow Target Version

When you create an Edge Workflow, you specify a target agent version. Edge Workflows can only run on devices running that specified target GEA version or higher. The GEA is always backward compatible.

After you update the GEA image, you will need to update your Edge Workflows to the proper target agent version in order to take advantage of the new features. Upgrading your target agent version is easily accomplished within the Agent Version tab in the Workflow Settings Panel.

Running the GEA on Windows

The GEA can be used with compatible Windows machines that have Docker installed. For more info on installing Docker on Windows, please see our documentation here.

The Docker CLI can be invoked using a variety of command-line tools. In the examples below, we’re using Windows Command Prompt (cmd). These examples also assume that the local user account executing these commands will be the same user account running Docker and the GEA container.

First, let’s create a storage area on our host machine to use as a bind mount. This can be any directory. For this example, we’re going to create a new folder called “docker-data” in our user home directory (e.g. C:\Users\your-username\) using the %USERPROFILE% environment variable:

mkdir %USERPROFILE%\docker-data

Now we’ll create a TOML configuration file…

type nul > %USERPROFILE%\docker-data\config.toml

…And open it with Notepad:

notepad.exe %USERPROFILE%\docker-data\config.toml

Enter in the configuration file options you want to include. In this example, we’re going to include the desired level of logging, the GEA device access key details, and the path to the persistent GEA store:

[logger]
level = 'error'

[gateway]
id = '<your-device-id>'
key = '<your-access-key>'
secret = '<your-access-secret>'

[store]
path = '/data/losant-edge-agent-store.db'

Voila! Now we can run our GEA container:

cd %USERPROFILE%\docker-data \
docker run -d --restart always --name losant-edge-agent ^
-v %cd%:/data -v %cd%\config.toml:/etc/losant/losant-edge-agent-config.toml ^
losant/edge-agent

GEA Configuration Options

All Options

As seen above, you can configure the GEA with the following options. Most of the following options can be set through:

• Command-line flags.
• Environment variables (most common for Docker).
• Configuration file.

If an option is set multiple ways, the command line flag is used first, followed by the environment variable, and then finally falling back to the configuration file.

Example Configuration File

# Losant Edge Agent Configuration File
#
# Configuration file location can be configured when running
# the agent by either the command line flag --conf-path or the
# environment variable CONF_PATH
#
# Any configuration variables that are commented out
# below have defaults or are not required. Many can also be provided
# through command line flags or environment variables.
#
[logger]
# Desired logger output destination
# Valid options are 'console' or a file path
# CLI: --logger-out
# Environment Variable: LOGGER_OUT
#
# out = 'console'
#
# Desired level of logging
# Valid options are 'error', 'warn', 'info', 'verbose'
# CLI: --logger-level
# Environment Variable: LOGGER_LEVEL
#
# level = 'info'
#
[gateway]
# Losant Device ID of Agent
# CLI: --device-id
# Environment Variable: DEVICE_ID
# id = ''
#
# Losant Access Key for Agent
# CLI: --access-key
# Environment Variable: ACCESS_KEY
# key = ''
#
# Losant Access Secret for Agent
# CLI: --access-secret
# Environment Variable: ACCESS_SECRET
# secret = ''
#
# If the agent, when it is not connected to Losant, should queue up MQTT messages to
# then send later when the agent does successfully connect
# CLI: --queue-offline-messages
# Environment Variable: QUEUE_OFFLINE_MESSAGES
#
# queueOfflineMessages = true
#
# When the agent reconnects to Losant and queueOfflineMessages is true, the order in
# which any queued offline messages should be sent
# Valid options are 'oldestFirst', and 'newestFirst'
# CLI: --offline-message-replay-order
# Environment Variable: OFFLINE_MESSAGE_REPLAY_ORDER
#
# offlineMessageReplayOrder = 'oldestFirst'
#
# If the agent, when it is not connected to Losant, should subscribe to
# peripheral device information, for use by the Get: Peripheral Node
# Valid options are true, false, 'floating', and 'peripheral'
# CLI: --subscribe-to-peripheral-updates
# Environment Variable: SUBSCRIBE_TO_PERIPHERAL_UPDATES
#
# subscribeToPeripheralUpdates = true
#
# Address of the Losant broker
# Environment Variable: BROKER_HOST
#
# host = 'broker.losant.com'
#
# Protocol to use to connect to broker
# Valid options are 'mqtts', 'mqtt', 'wss', and 'ws'
# Environment Variable: BROKER_PROTOCOL
#
# protocol = 'mqtts'
#
[gateway.clientSsl]
# If an SSL key is provided, an SSL certificate is also required, and vice versa.
# If provided, the key and secret fields above are not required.
#
# Path to the SSL key file to use for client certificate based authentication
# Environment Variable: BROKER_CLIENT_SSL_KEY_PATH (path to the key file)
# Environment Variable: BROKER_CLIENT_SSL_KEY (the key itself)
#
# keyPath = ''
#
# Path to the SSL certificate file to use for client certificate based authentication
# Environment Variable: BROKER_CLIENT_SSL_CERT_PATH (path to the certificate file)
# Environment Variable: BROKER_CLIENT_SSL_CERT (the certificate itself)
#
# certificatePath = ''
#
[store]
# Path to Agent Persistent Store
# CLI: --store-path
# Environment Variable: STORE_PATH
#
# path = './losant-edge-agent-store.db'
#
[udp]
# Address for UDP server
# CLI: --udp-address
# Environment Variable: UDP_ADDRESS
#
# address = '0.0.0.0'
#
[webserver]
# If webserver should be enabled
# CLI: --webserver-enabled
# Environment Variable: WEBSERVER_ENABLED
#
# enabled = true
#
# Port to run webserver on
# CLI: --webserver-port
# Environment Variable: WEBSERVER_PORT
#
# port = 8080
#
# Address to run webserver on
# CLI: --webserver-address
# Environment Variable: WEBSERVER_ADDRESS
#
# address = '0.0.0.0'
#
# Basic auth username for webserver
# CLI: --webserver-username
# Environment Variable: WEBSERVER_USERNAME
#
# username = ''
#
# Basic auth password for webserver
# CLI: --webserver-password
# Environment Variable: WEBSERVER_PASSWORD
#
# password = ''
#
[webserver.ssl]
# If an SSL key is provided, an SSL certificate is
# also required, and vice versa. An SSL bundle is optional.
#
# Path to the SSL key file to use for the webserver
# CLI: --webserver-ssl-key-path
# Environment Variable: WEBSERVER_SSL_KEY_PATH (path to the key file)
# Environment Variable: WEBSERVER_SSL_KEY (the key itself)
#
# keyPath = ''
#
# Path to the SSL certificate file to use for the webserver
# CLI: --webserver-ssl-cert-path
# Environment Variable: WEBSERVER_SSL_CERT_PATH (path to the certificate file)
# Environment Variable: WEBSERVER_SSL_CERT (the certificate itself)
#
# certificatePath = ''
#
# Path to the SSL Bundle file to use for the webserver
# CLI: --webserver-ssl-bundle-path
# Environment Variable: WEBSERVER_SSL_BUNDLE_PATH (path to the bundle file)
# Environment Variable: WEBSERVER_SSL_BUNDLE (the bundle itself)
#
# bundlePath = ''
#
[workflow]
# The directory containing on-disk workflows
# CLI: --workflow-directory
# Environment Variable: WORKFLOW_DIRECTORY
#
# directory = ''
#
[localBroker]
# If the local broker should be enabled
# CLI: --local-broker-enabled
# Environment Variable: LOCAL_BROKER_ENABLED
#
# enabled = false
#
# Port to run the local broker on
# CLI: --local-broker-port
# Environment Variable: LOCAL_BROKER_PORT
#
# port = 1883
#
# Address to run the local broker on
# CLI: --local-broker-address
# Environment Variable: LOCAL_BROKER_ADDRESS
#
# address = '0.0.0.0'
#
# Username for the local broker
# CLI: --local-broker-username
# Environment Variable: LOCAL_BROKER_USERNAME
#
# username = ''
#
# Password for the local broker
# CLI: --local-broker-password
# Environment Variable: LOCAL_BROKER_PASSWORD
#
# password = ''
#
[localBroker.ssl]
# If an SSL key is provided, an SSL certificate is
# also required, and vice versa. An SSL bundle is optional.
#
# Path to the SSL key file to use for the local broker
# CLI: --local-broker-ssl-key-path
# Environment Variable: LOCAL_BROKER_SSL_KEY_PATH (path to the key file)
# Environment Variable: LOCAL_BROKER_SSL_KEY (the key itself)
#
# keyPath = ''
#
# Path to the SSL certificate file to use for the local broker
# CLI: --local-broker-ssl-cert-path
# Environment Variable: LOCAL_BROKER_SSL_CERT_PATH (path to the certificate file)
# Environment Variable: LOCAL_BROKER_SSL_CERT (the certificate itself)
#
# certificatePath = ''
#
# Path to the SSL Bundle file to use for the local broker
# CLI: --local-broker-ssl-bundle-path
# Environment Variable: LOCAL_BROKER_SSL_BUNDLE_PATH (path to the bundle file)
# Environment Variable: LOCAL_BROKER_SSL_BUNDLE (the bundle itself)
#
# bundlePath = ''
#
# [[triggers]]
# Array of trigger configs which can configure an Edge Workflow trigger
# Minimally, these require a type and a unique name
#
# Example OPCUA Trigger Configuration:
#
# [[triggers]]
# name = 'opcuaTrig1'
# type = 'opcua'
# uri = 'opc.tcp://localhost:4335/UA/Server'
# samplingInterval = '10'
# eventFilter = ['Message', 'Value']
#
# [[triggers.monitoredItems]]
# nameSpace = '1'
# identifier = 's=MyVar3'
#
# [[triggers.monitoredItems]]
# identifier = 'i=2255'
#
# Example MQTT Client (External Broker) Trigger Configuration:
#
# [[triggers]]
# name = 'mqttTrig1'
# type = 'mqttClient'
# protocol = 'mqtt'
# host = 'broker.example.com'
# username = 'myUser'
# password = 'myPassword'
# clientId = 'myClientId'
# protocolVersion = '3.1.1'
# subscriptions = ['my/first/topic/#', 'my/second/topic/#']
#
# Example Beckhoff Trigger Configuration:
# [[triggers]]
# name = 'beckhoffTrig1'
# type = 'beckhoff'
# localAmsNetId = '192.168.5.221.1.2'
# localAdsPort = 32750
# targetAmsNetId = '5.123.154.18.1.1'
# targetAdsPort = 851
# routerHost = '127.0.0.1'
# routerTcpPort = 48898
# cycleTimeMs = 1000
# subscriptionItems = [ 'GVL_Var.TestDint1', 'GVL_Var.TestDint2' ]
#
# [healthCheck]
# If the health check endpoint should be enabled
# Environment Variable: HEALTH_CHECK_ENABLED
#
# enabled = true
#
# Port to run health check endpoint on
# Environment Variable: HEALTH_CHECK_PORT
#
# port = 8010
#
# If the agent should be marked as unhealthy when it is not connected to Losant
# Environment Variable: HEALTH_CHECK_OFFLINE_IS_UNHEALTHY
#
# offlineIsUnhealthy = false

Advanced Options

The following are exposed only as environment variables, and meant for advanced control of the Gateway Edge Agent’s behavior:

• MAX_FLOW_RUN_TIME - Controls the maximum amount of time, in milliseconds, a single workflow is allowed to run. Default value is 60000 (1 minute).
• MAX_EXTERNAL_CALL_TIME - Controls the maximum amount of time, in milliseconds, a workflow will wait for a response from an external service. Default value is 30000 (30 seconds).
• BROKER_HOST - Controls the address of the MQTT broker for the GEA to connect to. Default value is broker.losant.com.
• BROKER_PROTOCOL - Controls if the connection to the broker should be TCP vs WebSockets, and if it should be over SSL or not. Default is mqtts. Valid values are mqtt, mqtts, ws, and wss.
• MQTT_CONNECT_TIMEOUT - Controls the timeout when attempting to connect to the MQTT broker. Default value is 30000 (30 seconds). Minimum value is 5000 (5 seconds).
• MQTT_KEEPALIVE - Controls the keepalive for the MQTT connection to the MQTT broker, in milliseconds. Default value is 60000 (1 minute). A value of 0 will disable keepalive.
• MQTT_RECONNECT_INTERVAL - Controls the base interval at which the MQTT connection will try to reconnect to the MQTT broker. Default value is 30000 (30 seconds). Minimum value is 5000 (5 seconds). This will not be the actual reconnect interval; see MQTT_RECONNECT_VARIABILITY.
• MQTT_RECONNECT_VARIABILITY - Controls variability against the base reconnection interval. This is used to define the possible range of reconnect times around MQTT_RECONNECT_INTERVAL, in which a random value will be chosen. Default value is 15000 (15 seconds), minimum value is 5000 (5 seconds). This means that by default, a reconnect will be attempted in the window of 15 to 45 seconds after a disconnection.
• STATS_REPORT_TIME - Controls how frequently the GEA reports workflow statistics to the Losant cloud, in milliseconds. Default is 1800000 (30 minutes).
• BROADCAST_UPDATE_TOPIC_BASE - Controls the MQTT topic base for broadcast updates from the Losant cloud to the Gateway Edge Agent. Default is $SYS.
• IDLE_OPCUA_SESSION_TTL - Controls how long until an unused OPC UA session is considered idle. Default is 30000 (30 seconds).
• IDLE_OPCUA_CLIENT_TTL - Controls how long until an unused OPC UA client is considered idle. Default is 60000 (60 seconds).
• IDLE_OPCUA_CLEANUP_INTERVAL - Controls how frequently the GEA cleans up idle OPC UA clients and sessions. Default is 10000 (10 seconds).
• RAW_FUNCTION_STARTUP_TIMEOUT - Controls how long to allow a raw function background worker to take to become ready. Default is 2x the MAX_FLOW_RUN_TIME.
• RAW_FUNCTION_MEM_LIMIT_MB - Controls how much memory a raw function background worker is allowed to consume. Default is 128.
• RAW_FUNCTION_INSTANCES - Controls how many background workers are created to process raw function nodes. Default is 4.