FAQ
ForgeRock Identity Platform
ForgeRock Identity Cloud

FAQ: IG in Standalone Mode

Last updated Jan 19, 2023

The purpose of this FAQ is to provide answers to commonly asked questions regarding IG in standalone mode. This is a non-Web container dependent release of IG, which is delivered as a standalone Java® executable.


Frequently asked questions

Q. Does IG running in standalone mode have a header size limit?

A. Yes, the default header size for IG is 8 KB (8,192 bytes).

You will see the following error in your IG logs when this limit is exceeded:io.netty.handler.codec.TooLongFrameException: HTTP header is larger than 8192 bytes.

If you suspect you are exceeding the header size limit (for example, IG returns a HTTP Status 431 Request Header Fields Too Large response in the browser) but you don't see the above error, you can add the following logger entry to the logback.xml file:<logger name="io.vertx.core.http.impl.HttpServerImpl" level="TRACE"/>

Q. How do I increase the header size limit for HTTP/1.1 requests?

A. You can add the Vert.x maxHeaderSize property to either your admin.json file (if the error is happening on the server side) or to the route itself (if the error is happening on the client (handler) side).

For example:

  • Server side: Increase the size limit to 16 KB in the admin.json when requests are coming in on port 7070:"connectors": [    {         "port": 7070,         "vertx": {             "maxHeaderSize": 16384           }     } ],
  • Client (handler) side: Increase the size limit to 16 KB for the ReverseProxyHandler in the config.json file:"handler": {    "name": "MaxHeaderReverseProxyHandler",     "type": "ReverseProxyHandler",     "config": {          "vertx": {               "maxHeaderSize": 16384          }      } }

Q. How do I increase the header size limit for HTTP/2 requests?

A. If you are using the HTTP/2 protocol, you need to use the initialSettings Vert.x option, which is specific to HTTP/2 settings. Additionally, the property that controls header size limits for HTTP/2 is called maxHeaderListSize.

Again, you would add these settings to either the admin.json file or handler depending on what you were trying to achieve. In other words, if you want IG to be able to accept large HTTP/2 header requests, then you would update the admin.json file, but if you want to enable IG to make large HTTP/2 header requests, then you would update the corresponding handler.

For example, an updated admin.json would look similar to this: "connectors": [    {         "port": 7070,         "vertx": {             "initialSettings": {                 "maxHeaderListSize": 16384             }         },         "tls": {

Q. How can I configure IG in standalone mode to listen for requests on a specific host/IP address in addition to the port?

A. You can change the connector listen port in the admin.json file using the port option, but to specify a host or IP address to listen on, you need to use the host Vert.x option.

For example:{    "connectors": [         {             "port": 9080,             "vertx": {                 "host": "192.0.2.0"             }         }     ] }You can specify the FQDN hostname instead of an IP address. If the host property is not set, it defaults to 0.0.0.0, which listens on all interfaces.

See AdminHttpApplication (admin.json) - Properties for further information.

Q. Is there an equivalent setting in standalone mode that corresponds to the maxThreads setting?

A. IG in standalone mode uses a different threading model compared to when it is run in a container such as Apache Tomcat™. See ClientHandler/ReverseProxyHandler Tuning in Standalone Mode for further information on the tuning options available.

Q. How do I enable GC logging in standalone mode?

A. You can use environment variables to enable GC logging in the env.sh file, for example:JVM_OPTS="-Xlog:gc"

See Configure environment variables and system properties for IG in standalone mode for further information.

Q. How do I set the JVM heap size in standalone mode?

A. You can use environment variables to set the JVM heap size and other JVM options in the env.sh file, for example:JVM_OPTS="-Xms256m -Xmx2048m"

See Configure environment variables and system properties for IG in standalone mode for further information.

Q. How does IG determine which DNS servers to use in standalone mode? 

A. By default, IG uses the DNS servers specified in the system /etc/resolv.conf file. If this file is empty or inaccessible, then IG reverts to the default Google Public DNS servers.

If you cannot use the /etc/resolv.conf file to specify the DNS servers, then you can set the  addressResolverOptions Vert.x option in the admin.json file instead to specify the the preferred nameservers, for example:{    "vertx": {         "addressResolverOptions" : {             "servers": [ "192.0.2.0", "192.0.2.255" ]         }     } }

Q. Why am I seeing a DNS resolver error when I try to start standalone IG?

A. When running IG in standalone mode, you might see the following error when it fails to start:Caused by: java.lang.RuntimeException: io.netty.resolver.dns.DnsResolveContext$SearchDomainUnknownHostException: Search domain query failed. Original hostname: '<hostname>' failed to resolve '<hostname>' after 2 queries

This is a known issue with Vert.x that occurs when there is an OPT record in the DNS response: Hostname resolution does not handle answers set in additional section instead of answers section and DNS resolver doesn't work some times.

You can resolve this by adding the following JVM option to the env.sh file, for example:JVM_OPTS="-Dvertx.disableDnsResolver=true"See Configure environment variables and system properties for IG in standalone mode for further information.

Q. Can I monitor standalone IG using Dynatrace?

A. Yes you can. You will need to use the Java Monitoring Agent from Dynatrace and install the jar in your standalone IG. This agent will provide you with JVM traffic-related metrics. See Java monitoring for further information.

To monitor IG traffic, you would need to use OpenTracing to capture information on the Vert.x client, but this isn't currently supported in IG. There is an RFE to provide this support: OPENIG-7098 (OpenTracing support for standalone IG). In the meantime, you can use one of the following workarounds:

See Monitoring for further information.

See Also

FAQ: IG performance and tuning

How do I generate more detailed debug logs to diagnose an issue in IG (All versions)?

Migrate from web container mode to standalone mode

Install IG in standalone mode

Monitoring Vert.x Metrics

Vert.x HttpServerOptions

Vert.x HttpClientOptions


Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.