trinodb · electrum · Aug 2, 2022 · Jul 29, 2022
diff --git a/docs/src/main/sphinx/client/cli.rst b/docs/src/main/sphinx/client/cli.rst
@@ -13,9 +13,10 @@ Requirements
 The CLI requires a Java virtual machine available on the path.
 It can be used with Java version 8 and higher.
 
-The CLI uses the :doc:`Trino client REST API
-</develop/client-protocol>` over HTTP/HTTPS to communicate with the
-coordinator on the cluster.
+The CLI uses the :doc:`Trino client REST API </develop/client-protocol>` over
+HTTP/HTTPS to communicate with the coordinator on the cluster.
+
+.. _cli-installation:
 
 Installation
 ------------
@@ -37,7 +38,11 @@ the version:
 
     java -jar trino-cli-*-executable.jar --version
 
-The syntax can be used for the examples in the following sections.
+The syntax can be used for the examples in the following sections. In addition,
+using the ``java`` command allows you to add configuration options for the Java
+runtime with the ``-D`` syntax. You can use this for debugging and
+troubleshooting, such as when :ref:`specifying additional Kerberos debug options
+<cli-kerberos-debug>`.
 
 Running the CLI
 ---------------
@@ -328,27 +333,29 @@ To access a Trino cluster configured to use :doc:`/security/jwt`, use the
 Kerberos authentication
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-In addition to the options that are required when connecting to an unauthorized
-Trino coordinator, invoking the CLI with Kerberos support enabled requires a
-number of additional command line options. The simplest way to invoke the CLI is
-with a wrapper script.
+The Trino CLI can connect to a Trino cluster that has :doc:`/security/kerberos`
+enabled.
+
+Invoking the CLI with Kerberos support enabled requires a number of additional
+command line options. You also need the :ref:`Kerberos configuration files
+<server_kerberos_principals>` for your user on the machine running the CLI. The
+simplest way to invoke the CLI is with a wrapper script:
 
 .. code-block:: text
 
     #!/bin/bash
 
     ./trino \
-      --server https://trino-coordinator.example.com:7778 \
+      --server https://trino.example.com \
       --krb5-config-path /etc/krb5.conf \
       --krb5-principal someuser@EXAMPLE.COM \
       --krb5-keytab-path /home/someuser/someuser.keytab \
-      --krb5-remote-service-name trino \
-      --keystore-path /tmp/trino.jks \
-      --keystore-password password \
-      --catalog <catalog> \
-      --schema <schema>
+      --krb5-remote-service-name trino
+
+When using Kerberos authentication, access to the Trino coordinator must be
+through :doc:`TLS and HTTPS </security/tls>`.
 
-The following table list the available options for Kerberos authentication:
+The following table lists the available options for Kerberos authentication:
 
 .. list-table:: CLI options for Kerberos authentication
   :widths: 40, 60
@@ -373,8 +380,32 @@ The following table list the available options for Kerberos authentication:
     - Remote kerberos service principal pattern. Defaults to
       ``${SERVICE}@${HOST}``.
 
-See :doc:`/security/cli` for more information on configuring and using Kerberos
-with the CLI.
+.. _cli-kerberos-debug:
+
+Additional Kerberos debugging information
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can enable additional Kerberos debugging information for the Trino CLI
+process by passing ``-Dsun.security.krb5.debug=true``,
+``-Dtrino.client.debugKerberos=true``, and
+``-Djava.security.debug=gssloginconfig,configfile,configparser,logincontext``
+as a JVM argument when :ref:`starting the CLI process <cli-installation>`:
+
+.. code-block:: text
+
+    java \
+      -Dsun.security.krb5.debug=true \
+      -Djava.security.debug=gssloginconfig,configfile,configparser,logincontext \
+      -Dtrino.client.debugKerberos=true \
+      -jar trino-cli-*-executable.jar \
+      --server https://trino.example.com \
+      --krb5-config-path /etc/krb5.conf \
+      --krb5-principal someuser@EXAMPLE.COM \
+      --krb5-keytab-path /home/someuser/someuser.keytab \
+      --krb5-remote-service-name trino
+
+For help with interpreting Kerberos debugging messages, see :ref:`additional
+resources <kerberos-debug>`.
 
 Pagination
 ----------

diff --git a/docs/src/main/sphinx/security.rst b/docs/src/main/sphinx/security.rst
@@ -34,7 +34,6 @@ Authentication
   security/salesforce
   security/oauth2
   security/kerberos
-  security/cli
   security/certificate
   security/jwt
 

diff --git a/docs/src/main/sphinx/security/cli.rst b/docs/src/main/sphinx/security/cli.rst
diff --git a/docs/src/main/sphinx/security/kerberos.rst b/docs/src/main/sphinx/security/kerberos.rst
@@ -3,7 +3,7 @@ Kerberos authentication
 =======================
 
 Trino can be configured to enable Kerberos authentication over HTTPS for
-clients, such as the :doc:`Trino CLI </security/cli>`, or the JDBC and ODBC
+clients, such as the :doc:`Trino CLI </client/cli>`, or the JDBC and ODBC
 drivers.
 
 To enable Kerberos authentication for Trino, Kerberos-related configuration
@@ -29,12 +29,13 @@ Kerberos principals and keytab files
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The Trino coordinator needs a Kerberos principal, as do users who are going to
-connect to the Trino coordinator. You need to create these users in
-Kerberos using `kadmin
+connect to the Trino coordinator. You need to create these users in Kerberos
+using `kadmin
 <http://web.mit.edu/kerberos/krb5-latest/doc/admin/admin_commands/kadmin_local.html>`_.
 
 In addition, the Trino coordinator needs a `keytab file
-<http://web.mit.edu/kerberos/krb5-devel/doc/basic/keytab_def.html>`_. After you create the principal, you can create the keytab file using :command:`kadmin`
+<http://web.mit.edu/kerberos/krb5-devel/doc/basic/keytab_def.html>`_. After you
+create the principal, you can create the keytab file using :command:`kadmin`
 
 .. code-block:: text
 
@@ -56,8 +57,8 @@ System access control plugin
 ----------------------------
 
 A Trino coordinator with Kerberos enabled probably needs a
-:doc:`/develop/system-access-control` plugin to achieve
-the desired level of security.
+:doc:`/develop/system-access-control` plugin to achieve the desired level of
+security.
 
 Trino coordinator node configuration
 ------------------------------------
@@ -77,7 +78,8 @@ config.properties
 ^^^^^^^^^^^^^^^^^
 
 Kerberos authentication is configured in the coordinator node's
-:file:`config.properties` file. The entries that need to be added are listed below.
+:file:`config.properties` file. The entries that need to be added are listed
+below.
 
 .. code-block:: text
 
@@ -135,35 +137,38 @@ access-controls.properties
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 At a minimum, an :file:`access-control.properties` file must contain an
-``access-control.name`` property.  All other configuration is specific
-for the implementation being configured.
-See :doc:`/develop/system-access-control` for details.
+``access-control.name`` property.  All other configuration is specific for the
+implementation being configured. See :doc:`/develop/system-access-control` for
+details.
 
 .. _coordinator-troubleshooting:
 
 User mapping
 ------------
 
-After authenticating with Kerberos, the Trino server receives the user's principal which is typically similar to
-an email address.  For example, when ``alice`` logs in Trino might receive ``alice@example.com``.  By default,
-Trino will use the full Kerberos principal name, but this can be mapped to a shorter name using a user-mapping
-pattern.  For simple mapping rules, the  ``http-server.authentication.krb5.user-mapping.pattern`` configuration
-property can be set to a Java regular expression, and Trino will use the value of the first matcher group.  If the
-regular expression does not match, the authentication is denied.  For more complex user-mapping rules, see
+After authenticating with Kerberos, the Trino server receives the user's
+principal which is typically similar to an email address. For example, when
+``alice`` logs in Trino might receive ``alice@example.com``. By default, Trino
+uses the full Kerberos principal name, but this can be mapped to a shorter
+name using a user-mapping pattern. For simple mapping rules, the
+``http-server.authentication.krb5.user-mapping.pattern`` configuration property
+can be set to a Java regular expression, and Trino uses the value of the
+first matcher group. If the regular expression does not match, the
+authentication is denied. For more complex user-mapping rules, see
 :doc:`/security/user-mapping`.
 
 Troubleshooting
 ---------------
 
 Getting Kerberos authentication working can be challenging. You can
-independently verify some of the configuration outside of Trino, to help narrow
+independently verify some of the configuration outside of Trino to help narrow
 your focus when trying to solve a problem.
 
 Kerberos verification
 ^^^^^^^^^^^^^^^^^^^^^
 
 Ensure that you can connect to the KDC from the Trino coordinator using
-:command:`telnet`.
+:command:`telnet`:
 
 .. code-block:: text
 
@@ -184,14 +189,16 @@ Java keystore file verification
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Verify the password for a keystore file and view its contents using
-:ref:`troubleshooting_keystore`
+:ref:`troubleshooting_keystore`.
+
+.. _kerberos-debug:
 
 Additional Kerberos debugging information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 You can enable additional Kerberos debugging information for the Trino
 coordinator process by adding the following lines to the Trino ``jvm.config``
-file
+file:
 
 .. code-block:: text
 
@@ -208,6 +215,13 @@ sends to the logs varies depending on where the authentication is failing.
 Exception messages and stack traces can provide useful clues about the
 nature of the problem.
 
+See `Troubleshooting Security
+<https://docs.oracle.com/en/java/javase/11/security/troubleshooting-security.html>`_
+in the Java documentation for more details about the ``-Djava.security.debug``
+flag, and `Troubleshooting
+<https://docs.oracle.com/en/java/javase/11/security/troubleshooting.html>`_ for
+more details about the Java GSS-API and Kerberos issues.
+
 .. _server_additional_resources:
 
 Additional resources