Automated Agent Installation
The EAM allows an agent Gateway to be automatically configured from text files when the Gateway is started. This capability is enormously useful when installing multiple agent Gateways in your network, as it saves time from manually making this configurations. To automatically configure an agent or controller, you must add two files to the Ignition /data folder before startup: init.properties and eam-install.properties. Example contents are below. After the files have been read, they are renamed to .init.properties.bak and .eam-install.properties.bak. A typical application for this capability would be a script that creates the init files and adds them to an ignition.zip that is distributed to many systems.
For both types of files, settings omitted from the file will use their default values.
note
When using our Docker image, variables defined in docker environment variables will take precedent over the settings listed on this page.
init.properties​
Multiple outgoing Gateway Network connection settings are managed by numbering each setting. The first set of connection settings must contain “0” in the setting name after “gateway.network.” For example, you can create two outgoing connections with different IP addresses like so:
Gateway Network Addresses
gateway.network.0.Host=10.20.11.18
gateway.network.1.Host=10.20.15.23
| Property Name | Description |
|---|---|
SystemName | Sets the Gateway name in Gateway Settings. |
AutoDetectLocal | Set to true to check the first found network interface to determine local IP address. Set to false to manually set the IP address of the Gateway. Expects true or false. |
LocalInterface | Manually sets the IP address of the Gateway. If set, the AutoDetectLocal setting must be set to false. |
UseSSL | Set to true to force all connecting web browsers to connect to the Gateway over SSL. Expects true or false. |
gateway.network.#.PingRate | How often in milliseconds to ping the remote machine. |
gateway.network.#.Enabled | Set to false to disable the gateway connection after it is created. Expects true or false. |
gateway.network.#.Host | The address of the remote machine. |
gateway.network.#.Port | The port of the remote machine. |
gateway.network.#.EnableSSL | Set to true to use SSL to connect to the remote machine. You must change the Port setting to use the Gateway Network SSL port (which defaults to port 8060). Expects true or false. |
gateway.network.#.PingTimeout | How long in milliseconds to wait for a ping request to be processed by the remote machine. |
gateway.network.#.PingMaxMissed | The number of failed pings allowed before the connection state is set to Faulted. |
gateway.network.#.EnableWebSockets | Set to true to allow faster asynchronous communications with the remote machine. Expects true or false. |
gateway.network.#.WebsocketTimeout | How long to wait in milliseconds for a message to be processed over the web socket. |
gateway.network.#.HttpConnectTimeout | How long to wait in milliseconds to initially connect the http data channel. |
gateway.network.#.HttpReadTimeout | How long to wait in milliseconds to read data from the http data channel. |
New in 8.1.32
Configurable Gateway Network general configuration settings are listed below with their default values.| Property Name | Description |
|---|---|
gateway.network.enabled=true | Set to false to disable using the Gateway Network. |
gateway.network.requiressl=true | Determines if only connections using SSL to encrypt traffic are allowed. This setting applies to incoming connections. |
gateway.network.requireTwoWayAuth=false | Enforces two-way SSL authentication. If true, you will need to install the remote machine's certificate on this machine, in addition to manual approval of this machine's certificate on the remote machine. |
gateway.network.sendThreads=5 | The maximum number of threads that will be used to upload messages. Applies to outgoing connections. |
gateway.network.receivethreads=5 | The maximum number of threads that will be used to download messages. Applies to outgoing connections. |
gateway.network.receivemax=100 | Number of received messages that can be held until they are processed by the local system. When this capacity is exceeded, new messages are rejected and errors are reported to the remote gateway. Applies to incoming connections. |
gateway.network.allowincoming=true | If false, only outward connections defined on this Gateway will be allowed. |
gateway.network.securitypolicy=ApprovedOnly | Dictates what connections are allowed. By default, incoming connections must be approved from the Incoming Connections page. |
gateway.network.whitelist= | If connection policy is set to Specified List, this is the comma-separated list of Gateway names which will be allowed to connect. |
gateway.network.allowedproxyhops=0 | The maximum number of proxy hops which could be used to reach the destination Gateway. Any number less than or equal to zero is equivalent to no proxy hops allowed. |
gateway.network.websocketSessionIdleTimeout=30000 | The maximum number of milliseconds that a websocket is allowed to remain idle before it is closed. This value should always be set higher than outgoing connection ping rates to avoid premature connection termination. |
gateway.network.incomingPingRate=5000 | How often, in milliseconds, to send a ping to a remote machine. This will allow an incoming connection's health to be monitored. Set to 0 to disable pings sent from an incoming connection. |
gateway.network.incomingPingTimeout=300 | The maximum time, in milliseconds, allowed for a ping response. Pings that time out are counted as missed pings. |
gateway.network.incomingPingMaxMissed=12 | The amount of missed pings that will force an incoming connection to be considered faulted. |
Example init.properties​
init.properties
SystemName=Agent1
AutoDetectLocal=false
LocalInterface=10.20.11.17
UseSSL=false
gateway.network.0.PingRate=1000
gateway.network.0.Enabled=true
gateway.network.0.Host=10.20.11.18
gateway.network.0.Port=8088
gateway.network.0.EnableSSL=false
gateway.network.0.PingTimeout=300
gateway.network.0.PingMaxMissed=30
gateway.network.0.EnableWebSockets=true
gateway.network.0.WebsocketTimeout=10000
gateway.network.0.HttpConnectTimeout=10000
gateway.network.0.HttpReadTimeout=60000
eam-install.properties​
Before creating an eam-install.properties file, it's important to understand that each property is prepended by a key that determines the category for the property. The three categories are listed below.
agent.: Indicates the property pertains to an agent.controller.: Indicates the property pertains to a controller.setup.: Generic key used for settings that don't uniquely apply to either agents or controller.
| Property Name | Description |
|---|---|
setup.installSelection | Determines what the gateway will be configured as. Expects either Agent or Controller. |
agent.controllerServerName | Sets the name of the gateway in the Gateway Network that will be the controller for this gateway. |
agent.sendStatsInterval | The amount in seconds that the agent will wait before sending new metrics and configuration data to the controller. If there are currently no interesting metrics or updated config data to send, the agent will not send any data. |
controller.archivePath | When controller.archivePath is set to Manual, this property defines the path to use. |
controller.archiveLocation | Determines if the archive location should be set manually, or if the system should automatically pick a location. Expects a value of either Manual or Automatic. |
controller.lowDiskThresholdMB | Sets the low disk space threshold property. Excepts an integer value. |
controller.dataSource | Specifies which database connection the controller should use to record agent history. Note: The database specified by this property must first exist on the gateway for this property to do anything. If the specified database does not exist, then the setting will default to "none". |
Example Agent Configuration​
eam-install.properties
setup.installSelection=Agent
agent.controllerServerName=Ubuntu-Controller
agent.sendStatsInterval=5
Example Controller Configuration​
eam-install.properties
setup.installSelection=Controller
controller.archivePath=path/to my backups
controller.archiveLocation=Manual
controller.lowDiskThresholdMB=1234
controller.dataSource=MyDB