The IronFlock Agent is a (lightweight) daemon running on IoT devices that provides an interface to manage containers on the device and to collect/request app logs. In particular, the daemon enables the IronFlock IoT Development Studio to authenticate and securely connect to an IoT device in order to control apps running in containers on the device and retrieve their result and logs.
The IronFlock Agent is provided as a statically linked binary and accepts various
CLI parameters to configure it when launched. To show a list of the parameters
it accepts apply the help parameter ./reagent -help
Usage of ./reagent:
-agentDir string
default location of the agent binary (default "/opt/reagent", (linux), "$HOME/reagent", (other))
-appsDir string
default path for apps and app-data (default (default agentDir) + "/apps")
-arch
displays the architecture for which the binary was built
-compressedBuildExtension string
sets the extension in which the compressed build files will be provided (default "tgz")
-config string
reswarm configuration file
-connTimeout uint
Sets the connection timeout for the socket connection in milliseconds (0 means no timeout) (default 1250)
-dbFileName string
defines the name used to persist the database file (default "reagent.db")
-debug
sets the log level to debug (default true)
-debugMessaging
enables debug logs for messenging layer
-env string
determines in which environment the agent will operate. Possible values: (production, test, local) (default "production")
-logFile string
log file used by the reagent (default "/var/log/reagent.log" (linux), "$HOME/reagent/reagent.log" (other))
-nmw
enables the agent to use the NetworkManager API on Linux machines (default true)
-offline
starts the agent without establishing a socket connection. meant for debugging (default=false)
-ppTimeout uint
Sets the ping pong timeout of the client in milliseconds (0 means no timeout)
-prettyLogging
enables the pretty console writing, intended for debugging
-profiling
sets up a pprof webserver on the defined port
-profilingPort uint
port of the profiling service (default 80)
-remoteUpdateURL string
bucket to be used to download updates (default "https://storage.googleapis.com")
-respTimeout uint
Sets the response timeout of the client in milliseconds (default 5000)
-update
determines if the agent should update on start (default true)
-version
displays the current version of the agentThe config parameter needs to be populated with the path to a local .flock file. This .flock file contains all the neccessary device configuration and authentication data required to run the agent.
Read more on .flock files and how they work here: https://docs.ironflock.com/#/en/Reswarm/reflasher
Example Usage
./reagent -config path/to/config.flock -prettyLogging
The agent embeds the frp client into the binary. For that to work locally you first have to download the frp client.
make download_frpc
Once Go has been downloaded and installed, users can run the project locally by running the following command :
make run
# or on a mac
make run_mac
During development the /opt/reagent folder is used as the agent directory. There you can find additional config like the frpc.ini for the tunnel configuration.
To test with a local test device use the test-config.flock file when connecting to the local dev environment. A few things might need to be adjusted according to your environment.
The secret must be the one from the device's database record. Also use the insecure (ws instead of wss) endpoint and make sure the swarm_key and device_key are set.
If you encounter any privilege issues, please try removing the agent home directory beforehand (by default found in ${HOME}/reagent) or try running go as root.
Using go's built-in (cross-)compilation and some shell scripts we can easily build, publish and release a binary for a lot of different architectures and operating systems.
It is recommended to build the agent within Docker, to do so you can run make build-all-docker in the root of this project.
While not recommended users can also build the IronFlock Agent on the host machine using the make build-all command.
Both commands make use of the targets file to determine the target platform(s) and architecture(s).
Once building has completed, the resulting binaries can be found within the build/ directory at the root of this project.
The targets file, which can be found in the root of this project, determines which platforms and architectures the binary should be (cross-)compiled into.
The following platforms are set by default:
linux/amd64
linux/arm64
linux/arm/7
linux/arm/6
linux/arm/5
windows/amd64
darwin/amd64
Run go tool dist list to see all possible combinations supported by go in case you wish to add your own.
NOTE: The IronFlock Agent only supports a limited amount of targets, please read more here
Due to this project using a CGo-free port of SQLite/SQLite3, the IronFlock Agent can only be built into a limited amount of target platforms and architectures:
linux/386
linux/amd64
linux/arm
linux/arm64
linux/riscv64
windows/amd64
windows/arm64
darwin/amd64
darwin/arm64
freebsd/amd64
The version that is baked into the binary on build is determined by the string provided in the src/release/version.txt file. Adjust this file accordingly before making a build.
Once built the version of a binary can be verified with:
./reagent -version
Once the IronFlock Agent has been built into the platform(s) and architecture(s) of your needs the binaries can then be published into our remote bucket.
The make publish command will publish all binaries that are found within the build/ folder to our re-agent gcloud bucket.
Once the new binaries have been published they need to be made public for each IronFlock environment (local, production and test cloud).
To update the latest available IronFlock Agent binary, the availableVersions.json must be updated and published.
Once updated, the file can be published using the make publish-latestVersions command.
!!!!! USE WITH CAUTION !!!!!
make rollout can be used to build, publish the binary and publish the version files in one step.
Before doing so make sure the version files (availableVersions.json, src/release/version.txt) have been updated properly as explained in the Versioning and Release sections.
The Reagent makes use of WAMP and Docker as its two key technologies.
In order to implement a daemon running on an IoT device that is able to manage, create, stop and remove Docker containers we use the officially supported Go SDK.
Please remember that on a default docker setup on a Linux platform we always
have to launch the daemon with root permissions, since the docker daemon is
accessed via the socket ///var/run/docker.sock which is only readable with
root permissions by default.