diff --git a/docs/src/main/sphinx/client/cli.rst b/docs/src/main/sphinx/client/cli.rst index 09faf31b623f..a8a5917acb0e 100644 --- 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 -` over HTTP/HTTPS to communicate with the -coordinator on the cluster. +The CLI uses the :doc:`Trino client REST API ` 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 +`. 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 +` 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 \ - --schema + --krb5-remote-service-name trino + +When using Kerberos authentication, access to the Trino coordinator must be +through :doc:`TLS and HTTPS `. -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 `: + +.. 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 `. Pagination ---------- diff --git a/docs/src/main/sphinx/security.rst b/docs/src/main/sphinx/security.rst index d2c8ff1b5daa..bbf6285e988a 100644 --- 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 deleted file mode 100644 index 8d00c4ffb42d..000000000000 --- a/docs/src/main/sphinx/security/cli.rst +++ /dev/null @@ -1,92 +0,0 @@ -=========================== -CLI Kerberos authentication -=========================== - -The Trino :doc:`/client/cli` can connect to a Trino cluster that has -:doc:`kerberos` enabled. - -Environment configuration -------------------------- - -.. |subject_node| replace:: client - -.. include:: kerberos-services.fragment -.. include:: kerberos-configuration.fragment - -Kerberos principals and keytab files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Each user, who connects to the Trino coordinator, needs a Kerberos principal. -You need to create these users in Kerberos using `kadmin -`_. - -Additionally, each user needs a `keytab file -`_. The -keytab file can be created using :command:`kadmin` after you create the -principal. - -.. code-block:: text - - kadmin - > addprinc -randkey someuser@EXAMPLE.COM - > ktadd -k /home/someuser/someuser.keytab someuser@EXAMPLE.COM - -.. include:: ktadd-note.fragment - -Configuration for TLS -^^^^^^^^^^^^^^^^^^^^^ - -When using Kerberos authentication, access to the Trino coordinator must be -through HTTPS. If you have not yet configured TLS/HTTPS for your coordinator, -refer to :doc:`HTTPS and TLS `. - -Trino CLI execution -------------------- - -Use the :ref:`Kerberos options to run the CLI `. - -Troubleshooting ---------------- - -Many of the same steps, that can be used when troubleshooting the :ref:`Trino -coordinator `, apply to troubleshooting the CLI. - -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 starting the CLI process. Doing so requires invoking -the CLI JAR via ``java`` instead of running the self-executable JAR directly. - -.. code-block:: text - - #!/bin/bash - - 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-coordinator.example.com:7778 \ - --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 \ - --schema - -The :ref:`additional resources ` listed in the -documentation for setting up Kerberos authentication for the Trino coordinator -may be of help when interpreting the Kerberos debugging messages. - -See `Troubleshooting Security -`_ -in the Java documentation for more details about -the ``-Djava.security.debug`` flag, and `Troubleshooting -`_ -for more details about the Java GSS-API and Kerberos issues. diff --git a/docs/src/main/sphinx/security/kerberos.rst b/docs/src/main/sphinx/security/kerberos.rst index 4c275efc6347..6990d77916e1 100644 --- 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 `, or the JDBC and ODBC +clients, such as the :doc:`Trino 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 `_. In addition, the Trino coordinator needs a `keytab file -`_. After you create the principal, you can create the keytab file using :command:`kadmin` +`_. 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 +`_ +in the Java documentation for more details about the ``-Djava.security.debug`` +flag, and `Troubleshooting +`_ for +more details about the Java GSS-API and Kerberos issues. + .. _server_additional_resources: Additional resources