[BUG] Kerberos authentication doesn't work with jdk24

[Pigueiras]

What is the bug?

We noticed this issue in new clusters running version 3.2.0, where the bundled Java version is 24 instead of 21. When using Java 24, we encounter the following error on the server:

{"type": "server", "timestamp": "2025-09-18T14:44:51,862+02:00", "level": "ERROR", "component": "o.o.s.a.h.k.HTTPSpnegoAuthenticator", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Login exception due to", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ" ,
"stacktrace": ["javax.security.auth.login.LoginException: Security Exception",
"at java.base/javax.security.auth.login.LoginContext.invoke(LoginContext.java:682) ~[?:?]",
"at java.base/javax.security.auth.login.LoginContext.login(LoginContext.java:460) ~[?:?]",
"at org.opensearch.security.auth.http.kerberos.util.JaasKrbUtil.loginUsingKeytab(JaasKrbUtil.java:88) ~[opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at org.opensearch.security.auth.http.kerberos.HTTPSpnegoAuthenticator.extractCredentials0(HTTPSpnegoAuthenticator.java:214) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at org.opensearch.security.auth.http.kerberos.HTTPSpnegoAuthenticator$2.run(HTTPSpnegoAuthenticator.java:184) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at org.opensearch.security.auth.http.kerberos.HTTPSpnegoAuthenticator$2.run(HTTPSpnegoAuthenticator.java:181) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at java.base/java.security.AccessController.doPrivileged(AccessController.java:74) [?:?]",
"at org.opensearch.security.auth.http.kerberos.HTTPSpnegoAuthenticator.extractCredentials(HTTPSpnegoAuthenticator.java:181) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at org.opensearch.security.auth.BackendRegistry.authenticate(BackendRegistry.java:330) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at org.opensearch.security.filter.SecurityRestFilter.checkAndAuthenticateRequest(SecurityRestFilter.java:330) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at org.opensearch.security.ssl.http.netty.Netty4HttpRequestHeaderVerifier.channelRead0(Netty4HttpRequestHeaderVerifier.java:90) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at org.opensearch.security.ssl.http.netty.Netty4HttpRequestHeaderVerifier.channelRead0(Netty4HttpRequestHeaderVerifier.java:37) [opensearch-security-3.2.0.0.jar:3.2.0.0]",
"at io.netty.channel.SimpleChannelInboundHandler.channelRead(SimpleChannelInboundHandler.java:99) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:444) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.codec.ByteToMessageDecoder.fireChannelRead(ByteToMessageDecoder.java:346) [netty-codec-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.codec.ByteToMessageDecoder.channelRead(ByteToMessageDecoder.java:318) [netty-codec-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:444) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.timeout.IdleStateHandler.channelRead(IdleStateHandler.java:289) [netty-handler-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:442) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.codec.MessageToMessageDecoder.channelRead(MessageToMessageDecoder.java:107) [netty-codec-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:444) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.ssl.SslHandler.unwrap(SslHandler.java:1519) [netty-handler-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.ssl.SslHandler.decodeJdkCompatible(SslHandler.java:1377) [netty-handler-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.ssl.SslHandler.decode(SslHandler.java:1428) [netty-handler-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.codec.ByteToMessageDecoder.decodeRemovalReentryProtection(ByteToMessageDecoder.java:530) [netty-codec-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.codec.ByteToMessageDecoder.callDecode(ByteToMessageDecoder.java:469) [netty-codec-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.handler.codec.ByteToMessageDecoder.channelRead(ByteToMessageDecoder.java:290) [netty-codec-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:444) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.fireChannelRead(AbstractChannelHandlerContext.java:412) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.DefaultChannelPipeline$HeadContext.channelRead(DefaultChannelPipeline.java:1357) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:440) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.AbstractChannelHandlerContext.invokeChannelRead(AbstractChannelHandlerContext.java:420) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.DefaultChannelPipeline.fireChannelRead(DefaultChannelPipeline.java:868) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.nio.AbstractNioByteChannel$NioByteUnsafe.read(AbstractNioByteChannel.java:166) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.nio.NioEventLoop.processSelectedKey(NioEventLoop.java:796) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.nio.NioEventLoop.processSelectedKeysPlain(NioEventLoop.java:697) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.nio.NioEventLoop.processSelectedKeys(NioEventLoop.java:660) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.channel.nio.NioEventLoop.run(NioEventLoop.java:562) [netty-transport-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.util.concurrent.SingleThreadEventExecutor$4.run(SingleThreadEventExecutor.java:998) [netty-common-4.1.121.Final.jar:4.1.121.Final]",
"at io.netty.util.internal.ThreadExecutorMap$2.run(ThreadExecutorMap.java:74) [netty-common-4.1.121.Final.jar:4.1.121.Final]",
"at java.base/java.lang.Thread.run(Thread.java:1447) [?:?]",
"Caused by: java.lang.SecurityException",
"at java.base/javax.security.auth.login.LoginContext.invoke(LoginContext.java:683) ~[?:?]",
"... 49 more"] }

If we switch back to the same JDK we were using with version 2.18 (Java 21), everything works correctly. The error itself is not very informative, but the problem seems directly related to the Java version change.

How can one reproduce the bug?

Configure Kerberos authentication in OpenSearch and try to do a request. Our opensearch.yml contains:

plugins.security.kerberos.acceptor_keytab_filepath: krb5.keytab
plugins.security.kerberos.acceptor_principal: HTTP/XXXX@YYYY.ZZ
plugins.security.kerberos.krb5_filepath: "/etc/krb5.conf"

And in config.yml is:

...
      kerberos_auth_domain:
        description: "Authenticate via Kerberos"
        http_enabled: true
        transport_enabled: false
        order: 3
        http_authenticator:
          type: kerberos
          challenge: true
          config:
            krb_debug: false
            strip_realm_from_principal: true
        authentication_backend:
          type: noop

What is the expected behavior?
A clear and concise description of what you expected to happen.

What is your host/environment?

• OS: AlmaLinux 9
• Version 3.2.0
• Plugins:

opensearch-alerting
opensearch-asynchronous-search
opensearch-cross-cluster-replication
opensearch-custom-codecs
opensearch-flow-framework
opensearch-geospatial
opensearch-index-management
opensearch-job-scheduler
opensearch-knn
opensearch-ml
opensearch-neural-search
opensearch-notifications
opensearch-notifications-core
opensearch-observability
opensearch-reports-scheduler
opensearch-security
opensearch-security-analytics
opensearch-skills
opensearch-sql
opensearch-system-templates
query-insights
repository-s3

Do you have any screenshots?

Not applicable

Do you have any additional context?

Unfortunately, the stacktrace doesn’t provide much detail. We are not doing anything special in our setup, and the only difference appears to be the Java version. If there is a way to enable more verbose logging or additional debug output in this area, I would be happy to test it by building and deploying a custom version.

[Pigueiras]

If it helps, I have tried changing krb_debug to true and this is what I get:

jdk24 (not working):

{"type": "server", "timestamp": "2025-09-18T17:28:03,421+02:00", "level": "WARN", "component": "stderr", "cluster.name": "monitcopy1", "node.name": "osbitos376401-monitcopy1_client4", "message": "krb5loginmodule: Debug is true storeKey true useTicketCache false useKeyTab true doNotPrompt true ticketCache is null isInitiator false KeyTab is /etc/opensearch/monitcopy1_client4/krb5.keytab refreshKrb5Config is true principal is * tryFirstPass is false useFirstPass is false storePass is false clearPass is false", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "T9PS6akiSWOAEtkxQdsuHQ"  }
{"type": "server", "timestamp": "2025-09-18T17:28:03,421+02:00", "level": "WARN", "component": "stderr", "cluster.name": "monitcopy1", "node.name": "osbitos376401-monitcopy1_client4", "message": "krb5loginmodule: Refreshing Kerberos configuration", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "T9PS6akiSWOAEtkxQdsuHQ"  }
{"type": "server", "timestamp": "2025-09-18T17:28:03,421+02:00", "level": "WARN", "component": "stderr", "cluster.name": "monitcopy1", "node.name": "osbitos376401-monitcopy1_client4", "message": "krb5: Java config name: /etc/krb5.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "T9PS6akiSWOAEtkxQdsuHQ"  }
{"type": "server", "timestamp": "2025-09-18T17:28:03,421+02:00", "level": "WARN", "component": "stderr", "cluster.name": "monitcopy1", "node.name": "osbitos376401-monitcopy1_client4", "message": "krb5: Loading config file from /etc/krb5.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "T9PS6akiSWOAEtkxQdsuHQ"  }
{"type": "server", "timestamp": "2025-09-18T17:28:03,421+02:00", "level": "WARN", "component": "stderr", "cluster.name": "monitcopy1", "node.name": "osbitos376401-monitcopy1_client4", "message": "krb5: Loading krb5 profile at /etc/krb5.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "T9PS6akiSWOAEtkxQdsuHQ"  }
{"type": "server", "timestamp": "2025-09-18T17:28:03,422+02:00", "level": "ERROR", "component": "o.o.s.a.h.k.HTTPSpnegoAuthenticator", "cluster.name": "monitcopy1", "node.name": "osbitos376401-monitcopy1_client4", "message": "Login exception due to", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "T9PS6akiSWOAEtkxQdsuHQ" ,
"stacktrace": ["javax.security.auth.login.LoginException: Security Exception",
...

jdk21 (working):

{"type": "server", "timestamp": "2025-09-18T17:31:32,383+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Debug is  true storeKey true useTicketCache false useKeyTab true doNotPrompt true ticketCache is null isInitiator false KeyTab is /etc/opensearch/monitcopy1_client4/krb5.keytab refreshKrb5Config is true principal is * tryFirstPass is false useFirstPass is false storePass is false clearPass is false", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,384+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Refreshing Kerberos configuration", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,384+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Java config name: /etc/krb5.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,384+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Loading config file from /etc/krb5.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,384+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Loading krb5 profile at /etc/krb5.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,384+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Loading krb5 profile at /etc/krb5.conf.d/zzzz.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,384+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Loading krb5 profile at /etc/krb5.conf.d/yyy.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,384+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Loading krb5 profile at /etc/krb5.conf.d/xxx.conf", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
...
{"type": "server", "timestamp": "2025-09-18T17:31:32,387+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Loaded from Java config", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,387+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": ">>> KdcAccessibility: reset", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,387+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "principal is *@YYYY.ZZ", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,387+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Will use keytab", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,387+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Commit Succeeded ", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,388+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Found KeyTab /etc/opensearch/monitcopy1_client4/krb5.keytab", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,388+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Found KeyTab /etc/opensearch/monitcopy1_client4/krb5.keytab", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,388+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Found KeyTab /etc/opensearch/monitcopy1_client4/krb5.keytab", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,388+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Found KeyTab /etc/opensearch/monitcopy1_client4/krb5.keytab", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,388+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "Entered SpNegoContext.acceptSecContext with state=STATE_NEW", "cluster.uuid": "U8GacOsoSV6zJZCizDTPRA", "node.id": "A_5_PZzqRO6Y75TS7zITgQ"  }
{"type": "server", "timestamp": "2025-09-18T17:31:32,389+02:00", "level": "INFO", "component": "stdout", "cluster.name": "monitcopy1", "node.name": "osaitos376401-monitcopy1_client4", "message": "SpNegoContext.acceptSecContext: receiving token = ...
...

[cwperks]

I suspect its due to JSM being replaced with javaagent in 3.x line, but the error does not give enough information on its own unfortunately. I believe its trying to read a file based on https://github.com/openjdk/jdk24u/blob/master/src/java.base/share/classes/javax/security/auth/login/LoginContext.java#L679-L680, but the message does not include the filepath. In previous versions of the JDK, this was surrounded by AccessController.doPrivileged and had access to reading this files within the JDK itself.

[cwperks]

Maybe its this file? https://github.com/opensearch-project/security/blob/main/src/main/java/org/opensearch/security/auth/http/kerberos/HTTPSpnegoAuthenticator.java#L120-L123

If I'm reading the code correctly, its possible to put that in the config/ directory of opensearch and specify the name with the plugins.security.kerberos.krb5_filepath on the kerberos authenticator within config.yml.

tbh I have not setup kerberos authentication for development. Any suggestions on how to get that setup?

[Pigueiras]

If I'm reading the code correctly, its possible to put that in the config/ directory of opensearch and specify the name with the plugins.security.kerberos.krb5_filepath on the kerberos authenticator within config.yml.

Great, thanks a lot! That was the solution 😄 Maybe we could update the documentation here to mention the security restriction of the krb5.conf file in addition to the keytab?

tbh I have not setup kerberos authentication for development. Any suggestions on how to get that setup?

Unfortunately, I can't help much with that, setting up Kerberos isn’t very straightforward and someone else in my company is managing it for me 😅 , but these instructions seem like a reasonable starting point for setting up a local Kerberos environment.

[Pigueiras]

Created the docs PR, let me know if it makes sense 😄

[cwperks]

Thank you @Pigueiras ! The docs PR looks good to me and I would support changing the docs. You are encountering a bug that needs to be fixed. I suppose when the bug is fixed the docs should reference both ways of configuring this file. Thank you for the proactive docs PR :).