FAQ
ForgeRock Identity Platform
ForgeRock Identity Cloud

FAQ: IG in Standalone Mode

Last updated Feb 14, 2022

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?

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. Why is the increased header size limit ignored when using the HTTP/2 protocol with an HTTPS request?

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.

You should add this to your HTTPS connector. For example, your updated admin.json would now look similar to this: "connectors": [    {         "port": 7070,         "vertx": {             "initialSettings": {                 "maxHeaderListSize": 16384             }         },         "tls": {

You may also need to apply the initialSettings Vert.x option to a handler if the downstream application uses HTTPS, it supports the HTTP/2 protocol and you are passing headers that would exceed the 8 KB limit.

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

See Also

FAQ: IG performance and tuning

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

Migration to IG in Standalone Mode

Install IG in Standalone Mode

Monitoring Vert.x Metrics

Vert.x HttpServerOptions

Vert.x HttpClientOptions


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