forked from trinodb/trino
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
82 additions
and
130 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 [email protected] \ | ||
--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 [email protected] \ | ||
--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 | ||
---------- | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -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 ``[email protected]``. 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 ``[email protected]``. 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 | ||
|