Gateway Configuration File Reference
This section details the various configuration changes that can be made to the Gateway's configuration file: ignition.conf. Before the Gateway starts, a wrapper service checks the configuration file for parameter values, and then attempts to start the Gateway using parameters. This means changes made to the configuration file will only occur on startup, and making changes to the configuration file while the Gateway is already running will not have any impact until a restart.
Configuration File Location​
The Gateway's configuration file can be found at:
%IgnitionInstallationDirectory%/data/ignition.conf.
See the Installing and Upgrading Ignition page for default installation directories.
Comments in the File​
Many lines in the configuration file are commented out, either to provide some documentation in the file, or to omit certain parameters, such as some options under the Java Additional Parameters header. The "#" character is used to comment lines in the configuration file.
# this line is commented
this line is not commented
Gateway Memory Allocation​
On a standard installation, the Gateway is initially allocated a fixed amount of heap (memory). Increasing this allows the Gateway to utilize more of the server's memory. To determine if this is necessary, navigate to the Performance page under the Status section of the Gateway webpage. Generally speaking, if the Memory Trend shows a saw tooth pattern that peaks towards the maximum amount of memory, that's expected behavior. However, if memory usage usually floats around maximum allocated, and slow response events occur more than occasionally, then it may be time to consider increasing the maximum allocated memory, assuming the server has available memory.
To increase the maximum amount of memory allocated to the Gateway, open the Gateway configuration file, and search for "wrapper.java.maxmemory". It should look something like following:
# Maximum Java Heap Size (in MB)
wrapper.java.maxmemory=1024
The number at the end of the line represents the maximum amount of memory allocated to the Gateway (in megabytes). To change the amount of memory allocated to the Gateway, simply change this number, save the configuration file, and restart the Gateway. Once the Gateway starts up again, it will attempt to use the amount of memory specified.
The new heap size shouldn't exceed the amount of memory available, nor should you allocate all of the server's memory to the Gateway because the server likely has other applications (including the host operating system) that also need to make use of the system's resources.
Changing Java Additional Parameters​
Adding or modifying parameters in the configuration file is considered an advanced configuration change. Most installations don't require any additional parameters, nor do they require modification to existing parameters. We generally discourage most users from making changes to parameters in the configuration file, as doing so could result some unintended behavior or security vulnerabilities. We list the parameters on this page for the sake of transparency.
If you choose to add or modify parameters in the the configuration file, you do so at your own risk.
A section of the configuration file contains a header stating "Java Additional Parameters". This section allows for a large number of configuration changes, and merits having some discussion on how to add new parameters. On install, the Java Additional Parameters section may look like the following:
# Java Additional Parameters
wrapper.java.additional.1=-Ddata.dir=data
#wrapper.java.additional.2=-Xdebug
#wrapper.java.additional.3=-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:8000
When adding a new parameter, the "wrapper.java.additional.#" prefix must be added to a new line. Each parameter contains a prefix ("wrapper.java.additional.#"), a key, and a value that the key will be set to. Generally speaking, each parameter in the file should follow the pattern below:
wrapper.java.additional.1=-key=value
Uncommented parameters should be listed in ascending numerical order, based on the number at the end of the prefix, as shown below.
# Add parameters like this:
wrapper.java.additional.1=-Ddata.dir=data
#wrapper.java.additional.2=-Xdebug
#wrapper.java.additional.3=-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:8000
wrapper.java.additional.2=-some.thing=foo
wrapper.java.additional.3=-some.other.thing=bar
# Avoid skipping commented numbers:
wrapper.java.additional.1=-Ddata.dir=data
#wrapper.java.additional.2=-Xdebug
#wrapper.java.additional.3=-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=*:8000
wrapper.java.additional.4=-some.thing=foo
Java Service Wrapper Parameters​
Java Service Wrapper, developed by Tanuki Software, is used to control various Wrapper settings (i.e. wrapper.logfile.maxsize and wrapper.logfile.maxfiles). For a list of parameters and their function, visit Tanuki Software's documentation.
Common Localization Parameters​
You may sometimes need to change Ignition's locale information in the Gateway Configuration File. The following parameters will allow you to change the most commonly used localization information.
# Locale - Language (United States English)
wrapper.java.additional.1=-Duser.language=en_US
# Locale - Country (United States)
wrapper.java.additional.2=-Duser.country=US
# Locale - Variant (English (United States, Computer)
wrapper.java.additional.3=-Duser.variant=POSIX
# Timezone (Pacific Time)
wrapper.java.additional.4=-Duser.timezone=America/Los_Angeles
File Encoding Techniques​
You might also need to change how your files are encoded. The following parameter will allow you to change the encoding technique to what you require.
# File Encoding (Using UTF-8)
wrapper.java.additional.1=-Dfile.encoding=UTF-8
Gateway and Gateway Network Parameters​
See the Gateway and Gateway Network Parameters page for more Gateway and Gateway Network parameter information.
Vision Parameters​
See the Vision Client Parameters page for more Vision parameter information.
Perspective Parameters​
See the Perspective Parameters page for more Perspective parameter information.
Data Logging Parameters​
Store and Forward​
It is possible to adjust the refresh rate of the System Tag Provider's System tags. To do so, add the following system flag in the ignition.conf file:
wrapper.java.additional.1=-DStoreAndForwardStatusTagRefreshRate=####
Where "####" is the rate in milliseconds that the tags should refresh at. Default refresh rate is 5000 milliseconds.
Tag Historian Query Syntax​
The Ignition Tag Historian stores and queries data in a particular way. When a tag has Tag History enabled on it, an entry is generated for this tag inside the sqlth_te table in your database. This tag's tag path, along with other tag attributes, are stored in this table. Every tag entry in the sqlth_te table has a unique tag id which is used by the Tag Historian to identify each tag.
Whenever we make any type of change to this tag's historical configurations, such as its Tag Group for instance, the current sqlth_te table entry for this tag becomes retired and a new, unretired entry for this tag gets created with a new tag id. Due to this dynamic, it is common for a tag path in the sqlth_te table to be associated with more than one tag id. When a Tag History query executes for a specific tag, a check is made against the sqlth_te table for all the tag id's that match this tag's tag path. These tag id's are then used to build a dynamic SQL query like the one shown below:
SELECT "tagid", "intvalue", "floatvalue", "stringvalue", "datevalue", "t_stamp", "dataintegrity"
FROM sqlth_1_data
WHERE "t_stamp" >= 1580680800000 AND "t_stamp" <= 1581026400000
AND ( "tagid" = 14568 OR "tagid" = 14571 OR "tagid" = 14572 )
ORDER BY "t_stamp" ASC, "tagid" ASC
When we query tag history for a tag with three tag id's associated with its tag path, the system uses repetitive OR clauses to account for all the tag id's for this tag. Additional OR clauses in this fashion can be hard for databases to optimize. For this reason, we changed the query generating mechanism to use the IN operator like so:
SELECT "tagid", "intvalue", "floatvalue", "stringvalue", "datevalue", "t_stamp", "dataintegrity"
FROM sqlth_1_data
WHERE "t_stamp" >= 1580680800000 AND "t_stamp" <= 1581026400000
AND "tagid" IN (14568, 14571, 14572)
ORDER BY "t_stamp" ASC, "tagid" ASC
The use of the IN operator allows for better database side query optimization. Users who want to change their historian to use the old query constructor with OR operators can do so by placing the following system flag in the ignition.conf file:
The use of the IN operator allows for better database side query optimization. Users who want to change their historian to use the old query constructor with OR operators can do so by placing the following system flag in the ignition.conf file:
wrapper.java.additional.1=-Dignition.taghistorian.useLegacyQuerySyntax=true
Leased Licensing Parameters​
Two Java parameters exist for leased (eight-digit) licenses and are described below:
Session Termination HTTP Timeout Value​
Prior to version 8.1.38, the default value could not be changed from 4 seconds. For version 8.1.38+, the default value is now configurable and has been changed to 7.5 seconds, instead of 4 seconds.
# Defines the HTTP timeout for leased activation session termination requests.
wrapper.java.additional.1=-Dignition.license.leased-activation-session-termination-timeout-ms=xxxx
Leased Activation Session Termination​
Defines whether or not all configured (and active) leased activation license sessions will be terminated when Gateway shutdown is initiated. The default value is false.
wrapper.java.additional.1=-Dignition.license.leased-activation-terminate-sessions-on-shutdown=false