The Losant Edge Agent (“Agent”) is a command-line utility exposed through Docker as a container you can run on your Edge Compute device. The below outlines some example usage for how you can interact with the Agent on your device. For full documentation of all available flags and options, see the
losant/edge-agent image on Docker Hub.
For help getting the Agent setup on your device, see the installation instructions. All command examples below assume you can run
sudo or that you are logged in as
root (not recommended). If you wish to run
docker as your current user, see these instructions.
It is strongly recommended that you mount a volume into the Agent as a workspace for persistent data. By default, the Agent will write data inside the container to
/data. By mounting a volume or using a volume container, we can have the Agent write to a local folder on the Edge Compute device. By doing so, you have access to the persistent data created by the agent on your host machine and can reuse it if you have to destroy an Agent container and rebuild (upgrading the agent, for instance). Another benefit is that the Agent doesn’t accumulate data internally which could impact the performance and/or stability of the container.
All we need to do is create a folder locally to house the data. This folder can be anywhere on your file system, so long as permissions are set so
docker can write to it. For instance, you might choose to put this folder at
~/losant-edge-agent for easy access. For this example, we’re going to create a folder at
/var/lib/losant-edge-agent/ and update the permissions to allow
docker to write to it.
sudo mkdir -p /var/lib/losant-edge-agent/data sudo chmod -R a+rwx /var/lib/losant-edge-agent
The Losant Edge Agent has many configuration options, see the official Docker Hub Repo for a full list and advanced configuration. Because of the robust configuration options, you can configure the Agent via a toml formatted configuration file. In addition to using a configuration file for this example, we’re also going to configure the Agent to log to a file. See the section below for a full example configuration file.
Let’s create a configuration file in the directory we created earlier. Here’s our
/var/lib/losant-edge-agent/config.toml file. I’m using
vim to create the configuration file, but any editor is fine.
sudo vim /var/lib/losant-edge-agent/config.toml
[logger] out = '/data/losant-edge-agent-log.log' level = 'verbose' [gateway] id = '<your-device-id>' key = '<your-access-key>' secret = '<your-access-secret>' [store] path = '/data/losant-edge-agent-store.db'
Notice that we are designating the logger to output to the same
/data directory within the container that the store is writing to. This allows us to just mount a local folder on our host to the
/data directory in the Agent container and have all persistent data written to a single place. Now we can run the Agent container without specifying environment variables, and instead simply provide the path to our
docker run -d --restart always --name docs-agent \ -v /var/lib/losant-edge-agent/data:/data \ -v /var/lib/losant-edge-agent/config.toml:/etc/losant/losant-edge-agent-config.toml \ losant/edge-agent
/etc/losant/losant-edge-agent-config.toml is the default location for the
toml configuration file inside the container, so we mount our local configuration to that location in the container. Now that our Agent container is running, we can see the output by watching the log file we specified with
$ tail -f /var/lib/losant-edge-agent/data/losant-edge-agent-log.log 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
Because we have designated a configuration file and configured our Agent container to read from it, making changes are easy. Let’s say we decide that
verbose logging is just too much logging and we only really care about
error level logs. We can simply modify our
/var/lib/losant-edge-agent/config.toml like so:
# ... [logger] out = '/data/losant-edge-agent-log.log' level = 'error' # ...
Then restart the Agent to have the Agent pick up our new configuration changes.
docker restart docs-agent
If you wish to enable the HTTP Request Trigger for your Edge Compute device, you can do so by binding a host port at the time of container creation. In order to build on the configuration we have going, we only need to add the
-p flag and then configure the Agent in our configuration file to enable the trigger. See exposing ports with Docker for more information. For more advanced configuration of the HTTP Request Trigger and HTTP Response Node, see the Docker Hub Repo.
docker run -d --restart always --name docs-agent \ -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
There are only three required environment variables that must be set to run the container. You must provide the
DEVICE_ID obtained when you created your Edge Compute device, as well as the
ACCESS_SECRET associated with your application. Although these are the only required configuration, we’re also going to mount in a volume for the Agent to write to.
docker run -d --restart always --name docs-agent \ -e 'DEVICE_ID=<your-device-id>' \ -e 'ACCESS_KEY=<your-access-key>' \ -e 'ACCESS_SECRET=<your-access-secret>' \ -v /var/lib/losant-edge-agent/data:/data \ losant/edge-agent
Let’s break this down a little bit. By specifying the
-d parameter to
docker run, we are asking the Agent to run in the background so we have control of our terminal after running the Agent. The
--restart always option tells Docker to always restart the container if it were to die unexpectedly or on device boot. This aids in keeping your Edge Compute device up and running with minimal intervention. The
--name option allows us to name our container so that we may stop and start it more easily in the future. The
-e allows us to enumerate any and all environment variables we would like to pass in as configuration. Lastly, the
-v flag tells
docker run that we would like to mount our host folder
/data inside the container. Note, by specifying an image
losant/edge-agent without a tag, we are asking for the
latest tag of the Agent. It is recommended that you select a version-
losant/edge-agent:1.0.0 for example.
Before we move on to more advanced ways of configuring the Agent, 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 Agent. 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 logs [-f] <container-name|container-id> (more info)
This command allows us to look at the console output of the Agent after it has been started and is running. Unless you are writing your Agent logs to a file, this is the primary way you’ll get a glimpse into what the Agent 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 container id of your 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 running Agent 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 Agent 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 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 restart <container-name|container-id> (more info)
Instead of running
docker stop and then
docker start, you can simply run
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 Agent on your device.
With these basic
docker commands, we can manage our running agent. 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
Updating the Edge Agent to the latest version is accomplished through a series of
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 new version of the Edge Agent. Note that if sudo is being used to pull, it should be used consistently to avoid unexpected behavior.
When you create an Edge Workflow, you specify a target agent version. Edge Workflows can only run on devices with that specified target agent version or higher. The Edge Agent is always backward compatible.
After you update your Edge Agent, to take advantage of the new features, you will need to update your Edge Workflows to the proper target agent version. Upgrading your target agent version is easily accomplished within the Agent Version tab in the Workflow Settings Panel.
As seen above, you can configure the Agent with the following options. Most of the following options can be set through:
- environment variables (most common for Docker).
- the configuration file.
- command-line flags.
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.
For additional information review the Docker Hub Repo.
|Environment Variable||Configuration File Option||Command Line Flag|
# 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 and are not required. # [logger] # Desired logger output destination - CLI: --logger-out, EnvVar: LOGGER_OUT # out = 'console' # # Desired level of logging - CLI: --logger-level, EnvVar: LOGGER_LEVEL # level = 'info' # [gateway] # Losant Device ID of Agent - CLI: --device-id, EnvVar: DEVICE_ID id = '' # # Losant Access Key for Agent - CLI: --access-key, EnvVar: ACCESS_KEY key = '' # # Losant Access Secret for Agent - CLI: --access-secret, EnvVar: 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, EnvVar: QUEUE_OFFLINE_MESSAGES # queueOfflineMessages = true # [store] # Path to Agent Persistent Store - CLI: --store-path, EnvVar: STORE_PATH # path = './losant-edge-agent-store.db' # [udp] # Address for UDP server - CLI: --udp-address, EnvVar: UDP_ADDRESS # address = '0.0.0.0' # [webserver] # If webserver should be enabled - CLI: --webserver-enabled, EnvVar: WEBSERVER_ENABLED # enabled = true # # Port to run webserver on - CLI: --webserver-port, EnvVar: WEBSERVER_PORT # port = 8080 # # Address to run webserver on - CLI: --webserver-address, EnvVar: WEBSERVER_ADDRESS # address = '0.0.0.0' # # Basic auth username for webserver - CLI: --webserver-username, EnvVar: WEBSERVER_USERNAME # username = '' # # Basic auth password for webserver - CLI: --webserver-password, EnvVar: WEBSERVER_PASSWORD # password = '' # [webserver.ssl] # NOTE 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, EnvVar: WEBSERVER_SSL_KEY_PATH # Key can also be provided directly using the EnvVar WEBSERVER_SSL_KEY # keyPath = '' # # Path to the SSL Certificate file to use for the webserver # CLI: --webserver-ssl-cert-path, EnvVar: WEBSERVER_SSL_CERT_PATH # Certificate can also be provided directly using the EnvVar WEBSERVER_SSL_CERT # certificatePath = '' # # Path to the SSL Bundle file to use for the webserver # CLI: --webserver-ssl-bundle-path, EnvVar: WEBSERVER_SSL_BUNDLE_PATH # Bundle can also be provided directly using the EnvVar WEBSERVER_SSL_BUNDLE # bundlePath = '' # [localBroker] # If the local broker should be enabled - CLI: --local-broker-enabled, EnvVar: LOCAL_BROKER_ENABLED # enabled = false # # Port to run the local broker on - CLI: --local-broker-port, EnvVar: LOCAL_BROKER_PORT # port = 1883 # # Address to run the local broker on - CLI: --local-broker-address, EnvVar: LOCAL_BROKER_ADDRESS # address = '0.0.0.0' # # Username for the local broker - CLI: --local-broker-username, EnvVar: LOCAL_BROKER_USERNAME # username = '' # # Password for the local broker - CLI: --local-broker-password, EnvVar: LOCAL_BROKER_PASSWORD # password = '' # [localBroker.ssl] # NOTE 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, EnvVar: LOCAL_BROKER_SSL_KEY_PATH # Key can also be provided directly using the EnvVar LOCAL_BROKER_SSL_KEY # keyPath = '' # # Path to the SSL Certificate file to use for the local broker # CLI: --local-broker-ssl-cert-path, EnvVar: LOCAL_BROKER_SSL_CERT_PATH # Certificate can also be provided directly using the EnvVar LOCAL_BROKER_SSL_CERT # certificatePath = '' # # Path to the SSL Bundle file to use for the local broker # CLI: --local-broker-ssl-bundle-path, EnvVar: LOCAL_BROKER_SSL_BUNDLE_PATH # Bundle can also be provided directly using the EnvVar LOCAL_BROKER_SSL_BUNDLE # bundlePath = ''
The following are exposed only as environment variables, and meant for advanced control of the 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
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
BROKER_HOST- Controls the address of the MQTT broker for the edge agent to connect to. Default value is
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
STATS_REPORT_TIME- Controls how frequently the edge agent reports workflow statistics to the Losant cloud, in milliseconds. Default is
BROADCAST_UPDATE_TOPIC_BASE- Controls the mqtt topic base for broadcast updates from the Losant cloud to edge agents. Default is
IDLE_OPCUA_SESSION_TTL- Controls how long until an unused OPCUA session is considered idle. Default is 30000 (30 seconds).
IDLE_OPCUA_CLIENT_TTL- Controls how long until an unused OPCUA client is considered idle. Default is 60000 (60 seconds).
IDLE_OPCUA_CLEANUP_INTERVAL- Controls how frequently the edge agent cleans up idle OPCUA clients and sessions. Default is 10000 (10 seconds).