Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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. 

Code Block
# this line is commented
this line is not commented
On_this_page



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:

Code Block
# 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. 

Scroll html ignore
Iulink
URLhttps://www.inductiveuniversity.com/videos/changing-gateway-memory-allocation/8.0
NameChanging Gateway Memory Allocation



Changing Java Additional Parameters

Caution_friendly

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:

Code Block
# 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:

Code Block
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.

Code Block
# 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

Designer and Vision Client Parameters (H2)

Suppressing Error Message Details (H3)

New_in
Version8.1.10


By default, error messages in the Designer and Client report a stack trace, which provides granular information about the source of the error. However in some cases, these stack traces may include sensitive information from the Gateway. You can restrict the amount of information presented in these error messages with the following parameter: 

Code Block
titleExample
wrapper.java.additional.#=-Dignition.xmlrpc.errorDetailSuppression=%Value%

Where %Value% is one of the following values:

ValueDescription
NONEErrors are not suppressed at all. This is functionally the same as not specifying the parameter at all. (default behavior)
CLIENTError messages for client sessions will be surpressedsuppressed, but not designer sessions. 
ALLError messages for both clients and the designer will be suppressed.


Gateway Parameters

Gateway Security HTTP Headers and Configuration

Gateways use more secure security headers. The default settings are listed below, along with their associated keys. These parameters mainly impact Perspective sessions, as well as any pages hosted on Ignition's web server. 


Note_friendly

HTTP headers used by the Gateway are configurable via the ignition.conf file in the Gateway's installation directory. In most cases there won't be a need to modify the new default values. However, if you're embedding a Perspective session inside of an iframe from another origin, and it stops working after upgrade, then take a look at this  Knowledge Base Article  for more details. 

Strict Transport Security

The following keys interact with the Strict-Transport-Security header. Enabling the header involves setting the Dignition.https.sts.maxAge key to a non-zero value. By default, the header is disabled. 

KeyDescription
-Dignition.https.sts.maxAge

Sets the maximum age of the Strict Transport Security header. The value should be set to an integer, representing a number of seconds.

-Dignition.https.sts.includeSubDomains
Applies the includeSubDomains parameter. Expects a boolean value. If omitted, defaults to false.
-Dignition.https.sts.preload 
New_in
Version8.1.5



This parameter allows websites to tell the browser to only connect using HTTPS.  It can be set to " true"  or " false"  to enable or disable the  preload  directive of the  Strict-Transport-Security  header. If omitted, defaults to false.



Code Block
titleExample
wrapper.java.additional.1=-Dignition.https.sts.maxAge=5000
wrapper.java.additional.2=-Dignition.https.sts.includeSubDomains=false
wrapper.java.additional.3=-Dignition.https.sts.preload=true  
Referrer Policy

The following keys interact with the  Referrer-Policy  header: By default, the header is enabled with a value of  strict-origin-when-cross-origin.

KeyDescription
-Dignition.http.header.referrer_policy.enabled

Allows you to enable or disable the Referrer-Policy header. Expects a true or false value. 

-Dignition.http.header.referrer_policy.value

Sets the value of the Referrer-Policy.

Code Block
titleExample
wrapper.java.additional.1=-Dignition.http.header.referrer_policy.enabled=true
wrapper.java.additional.2=-Dignition.http.header.referrer_policy.value=strict-origin-when-cross-origin
X Content Type Options

The following keys interact with the X-Content-Type-Options header: By default, the header is enabled with a value of nosniff .

KeyDescription
-Dignition.http.header.x_content_type_options.enabled

Allows you to enable or disable the X-Content-Type-Options header. Expects a true or false value. 

-Dignition.http.header.x_content_type_options.value

Determines the value of the X-Content-Type-Options.

Code Block
titleExample
wrapper.java.additional.1=-Dignition.http.header.x_content_type_options.enabled=true
wrapper.java.additional.2=-Dignition.http.header.x_content_type_options.value=nosniff 
X Frame Options

The following keys interact with the X-Frame-Options header: By default, the header is enabled with a value of SAMEORIGIN

KeyDescription
-Dignition.http.header.x_frame_options.enabled

Enables or disables the X-Frame-Options header. 

-Dignition.http.header.x_frame_options.value

Determines the value of the X-Frame-Options header

Code Block
titleExample
wrapper.java.additional.1=-Dignition.http.header.x_frame_options.enabled=true
wrapper.java.additional.2=-Dignition.http.header.x_frame_options.value=SAMEORIGIN
X XSS Protection

The following keys interact with the X-XSS-Protection header. By default, the header is enabled with a value of 1; mode=block

KeyDescription
-Dignition.http.header.x_xss_protection.enabled

Enables or disables the X-XSS-Protection header.

-Dignition.http.header.x_xss_protection.value

Determines the value of the X-XSS-Protection header.

Code Block
titleExample
wrapper.java.additional.1=-Dignition.http.header.x_xss_protection.enabled=true
wrapper.java.additional.2=-Dignition.http.header.x_xss_protection.value=1; mode=block

Maximum Form Size

Note_friendly

By default, the maximum size is kept low on the default installation to prevent DoS attacks. We do not recommend changing this, especially so if the Gateway isn't in a closed network. 

This parameter allows you limit the amount of data that can be posted back from a browser or other client, to the Gateway. Generally, this is useful to increase the maximum size for WebDev POST requests. More information about this parameter can be found in Jetty's documentation

Code Block
titleExample
wrapper.java.additional.1=-Dorg.eclipse.jetty.server.Request.maxFormContentSize=2000000

Hosted Launcher Installers

Normally, each Ignition Gateway includes files for the various launchers. When you download a launcher from a Gateway, it simply streams its local launcher files. However, you can override this behavior, causing the Gateway to ignore it's local launcher files and instead download launchers from the internet. This is an uncommon configuration for most cases, as it was devised primarily to aid with systems where memory limitations are strict (such as physical devices that include preinstalled Ignition Gateways).  

Enabling Hosted Launchers

The following parameter (and value) enables the use of hosted launchers. While enabled, the Gateway will only ever attempt to retrieve the hosted launchers, meaning it will ignore the local launcher files. 

Code Block
titleExample
wrapper.java.additional.1=-Dignition.hostedLaunchers=true
Hosted Launcher Version

By default, enabling Hosted Launchers will cause the Gateway to retrieve launchers version appropriate launchers: 8.0.0 launchers for 8.0.0 Gateways, 8.1.0 launchers for 8.1.0 Gateways, etc. 

The parameter below can be used to explicitly state which launcher version to retrieve. Generally, this is not recommended, but can potentially be useful if you're looking for a specific launcher version.  It requires that -Dignition.hostedLaunchers  is set to "true". 

Code Block
titleExample
wrapper.java.additional.1=-Dignition.hostedLauncherVersion=8.1.0

Ignition Edition

You can specify which edition of Ignition a Gateway should be set to with the parameter demonstrated below. 

Code Block
titleExample
wrapper.java.additional.1=-Dedition=standard
Caution_friendly

Ignition Gateway Licenses are matched to a specific edition. Changing the edition of an Ignition Gateway that is already licensed can result in the license becoming invalidated. It's recommended that you unactivate a license on a gateway before changing its edition. 

Values
  • Standard Ignition - standard
  • Ignition Edge - edge
  • Ignition Maker - maker

Loading Unsigned Modules - "Developer Mode"

Normally, an Ignition Gateway will not allow unsigned module to be installed. This restriction can be disabled with the flag below. This is normally done in cases where a user is developing a custom module, and wants to install it without having the module signed. 

Code Block
wrapper.java.additional.1=-Dignition.allowunsignedmodules=true


Gateway Network Parameters

Proxy Depth

By default, gateway remote providers can only "hop" two gateways away. For example, assume the numbers below represent gateways, which are all connected over a gateway network. 

Code Block
1 -- 2 -- 3 -- 4

Normally, gateway 1 only has access to gateway 2 and 3. Gateway 4 is too far away. However this can be changed by adding the following to Gateway 1's configuration file:

Code Block
wrapper.java.additional.1=-Dignition.gan.maxproxydepth=3
Note_friendly

The Allow Proxying setting must be enabled for requests to be forwarded in this manner. 


Perspective Parameters

Perspective Web Socket Compression

You can remove the compression header for perspective web socket connections.

This parameter is generally only used in cases where a Microsoft IIS based firewall is acting like a reverse proxy, and needs to be able to rewrite secure web-socket messages.

Code Block
titleExample
wrapper.java.additional.1=-Dperspective.ws.disablePermessageDeflateExtension=true

Perspective Session Route Handling

New_in
Version8.1.8


The following parameters are used to modify route handling for Perspective Sessions. Most systems will not need to modify these parameters. However increasing the values of these parameters may be helpful in cases where large project updates are sent out to active Perspective Sessions over a spotty network. A low timeout and concurrency in that scenario may result in browser timeouts. 

KeyDescription
-Dperspective.fetch-concurrency

Determines the number of concurrency sessions. Defaults to 25.

-Dperspective.fetch-timeout

Determines the timeout period when receiving project updates. Defaults to 5000 milliseconds. 



Code Block
titleExample
wrapper.java.additional.1=-Dperspective.fetch-concurrency=25
wrapper.java.additional.2=-Dperspective.fetch-timeout=5000


Store and Forward Parameters

New_in
Version8.1.2


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:

Code Block
titleExample
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 Parameters

Tag Historian Query Syntax

New_in
Version8.1.2


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:

Code Block
languagesql
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: 

Code Block
languagesql
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:

Code Block
titleExample
wrapper.java.additional.1=-Dignition.taghistorian.useLegacyQuerySyntax=true