Repository: incubator-impala Updated Branches: refs/heads/master 60127ff93 -> 025b5dbbb
IMPALA-3410 [DOCS] Rework Impala authentication topics to be generic This is part 2 of the work being done to genericize the Impala security topics. All references to Cloudera have been either marked 'hidden' or replaced with links to the relevant open-source docs. Note: -Links to the standalone Cloudera ODBC driver doc have not been removed. -External links to the MIT Kerberos docs and Hadoop security docs were added to impala_keydefs. Change-Id: I639a55eb43555cf074c26d23b5c72f778073231c Reviewed-on: http://gerrit.cloudera.org:8080/5962 Reviewed-by: Laurel Hale <[email protected]> Reviewed-by: John Russell <[email protected]> Tested-by: Impala Public Jenkins Project: http://git-wip-us.apache.org/repos/asf/incubator-impala/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-impala/commit/025b5dbb Tree: http://git-wip-us.apache.org/repos/asf/incubator-impala/tree/025b5dbb Diff: http://git-wip-us.apache.org/repos/asf/incubator-impala/diff/025b5dbb Branch: refs/heads/master Commit: 025b5dbbb0f9879772a4f72450a93205c6ee6753 Parents: 60127ff Author: Ambreen Kazi <[email protected]> Authored: Thu Feb 9 17:18:37 2017 -0800 Committer: Impala Public Jenkins <[email protected]> Committed: Thu Feb 23 18:33:21 2017 +0000 ---------------------------------------------------------------------- docs/impala_keydefs.ditamap | 12 +++++++++ docs/shared/impala_common.xml | 17 +++++++----- docs/topics/impala_delegation.xml | 9 +++---- docs/topics/impala_kerberos.xml | 47 ++++++++++++++++++++-------------- docs/topics/impala_ldap.xml | 18 +++++-------- 5 files changed, 60 insertions(+), 43 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-impala/blob/025b5dbb/docs/impala_keydefs.ditamap ---------------------------------------------------------------------- diff --git a/docs/impala_keydefs.ditamap b/docs/impala_keydefs.ditamap index 6553ec4..08e0f4f 100644 --- a/docs/impala_keydefs.ditamap +++ b/docs/impala_keydefs.ditamap @@ -33,6 +33,18 @@ under the License. </keydef> --> + <keydef href="https://web.mit.edu/kerberos/krb5-latest/doc/admin/install_kdc.html"; scope="external" format="html" keys="mit_install_kdc"> + <topicmeta><linktext>Kerberos Key Distribution Center (KDC)</linktext></topicmeta> + </keydef> + + <keydef href="https://web.mit.edu/kerberos/krb5-latest/doc/index.html"; scope="external" format="html" keys="mit_kerberos_docs"> + <topicmeta><linktext>MIT Kerberos documentation</linktext></topicmeta> + </keydef> + + <keydef href="https://hadoop.apache.org/docs/stable/hadoop-project-dist/hadoop-common/SecureMode.html#Authentication"; scope="external" format="html" keys="upstream_hadoop_authentication"> + <topicmeta><linktext>Authentication in Hadoop</linktext></topicmeta> + </keydef> + <keydef keys="upstream_hbase_docs" href="https://hbase.apache.org/book.html"; scope="external" format="html"> <topicmeta><linktext>the Apache HBase documentation</linktext></topicmeta> </keydef> http://git-wip-us.apache.org/repos/asf/incubator-impala/blob/025b5dbb/docs/shared/impala_common.xml ---------------------------------------------------------------------- diff --git a/docs/shared/impala_common.xml b/docs/shared/impala_common.xml index 2d9656e..4604a33 100644 --- a/docs/shared/impala_common.xml +++ b/docs/shared/impala_common.xml @@ -564,28 +564,31 @@ under the License. <p rev="IMPALA-2660 CDH-40241" id="auth_to_local_instructions"> In <keyword keyref="impala26_full"/> and higher, Impala recognizes the <codeph>auth_to_local</codeph> setting, specified through the HDFS configuration setting - <codeph>hadoop.security.auth_to_local</codeph> - or the Cloudera Manager setting - <uicontrol>Additional Rules to Map Kerberos Principals to Short Names</uicontrol>. + <codeph>hadoop.security.auth_to_local</codeph>. This feature is disabled by default, to avoid an unexpected change in security-related behavior. To enable it: <ul> <li> <p> - For clusters not managed by Cloudera Manager, specify <codeph>--load_auth_to_local_rules=true</codeph> - in the <cmdname>impalad</cmdname> and <cmdname>catalogd</cmdname>configuration settings. + Specify <codeph>--load_auth_to_local_rules=true</codeph> + in the <cmdname>impalad</cmdname> and <cmdname>catalogd</cmdname> configuration settings. </p> </li> - <li audience="Cloudera"> + <li audience="hidden"> <p> For clusters managed by Cloudera Manager, select the <uicontrol>Use HDFS Rules to Map Kerberos Principals to Short Names</uicontrol> checkbox to enable the service-wide <codeph>load_auth_to_local_rules</codeph> configuration setting. + Use the Cloudera Manager setting, <uicontrol>Additional Rules to Map Kerberos Principals to Short Names</uicontrol>, + to insert mapping rules. Then restart the Impala service. </p> + <p> + See <xref href="http://www.cloudera.com/documentation/enterprise/latest/topics/sg_auth_to_local_isolate.html"; scope="external" format="html">Using Auth-to-Local Rules to Isolate Cluster Users</xref> + for general information about this feature. + </p> </li> </ul> - See <xref href="http://www.cloudera.com/documentation/enterprise/latest/topics/sg_auth_to_local_isolate.html"; scope="external" format="html">Using Auth-to-Local Rules to Isolate Cluster Users</xref> for general information about this feature. </p> <note id="authentication_vs_authorization"> http://git-wip-us.apache.org/repos/asf/incubator-impala/blob/025b5dbb/docs/topics/impala_delegation.xml ---------------------------------------------------------------------- diff --git a/docs/topics/impala_delegation.xml b/docs/topics/impala_delegation.xml index 6daa87f..1ea80a2 100644 --- a/docs/topics/impala_delegation.xml +++ b/docs/topics/impala_delegation.xml @@ -76,7 +76,7 @@ under the License. <xref href="http://blog.cloudera.com/blog/2013/07/how-hiveserver2-brings-security-and-concurrency-to-apache-hive/"; scope="external" format="html">this Cloudera blog post</xref> for background information about the delegation capability in HiveServer2. </p> - + <!-- Link to Cloudera blog post --> <p> To set up authentication for the delegated users: </p> @@ -92,11 +92,8 @@ under the License. <li> <p> - On the client side, follow the instructions in the <q>Using User Name and Password</q> section in the - <xref href="http://www.cloudera.com/content/cloudera-content/cloudera-docs/Connectors/PDF/Cloudera-ODBC-Driver-for-Impala-Install-Guide.pdf"; scope="external" format="pdf">ODBC - driver installation guide</xref>. Then search for <q>delegation</q> in that same installation guide to - learn about the <uicontrol>Delegation UID</uicontrol> field and <codeph>DelegationUID</codeph> configuration keyword to enable the delegation feature for - ODBC-based BI tools. + On the client side, to learn how to enable delegation, consult the documentation + for the ODBC driver you are using. </p> </li> </ul> http://git-wip-us.apache.org/repos/asf/incubator-impala/blob/025b5dbb/docs/topics/impala_kerberos.xml ---------------------------------------------------------------------- diff --git a/docs/topics/impala_kerberos.xml b/docs/topics/impala_kerberos.xml index a5cd53b..8812389 100644 --- a/docs/topics/impala_kerberos.xml +++ b/docs/topics/impala_kerberos.xml @@ -36,27 +36,35 @@ under the License. <conbody> <p> - Impala supports Kerberos authentication. For more information on enabling Kerberos authentication, see the - topic on Configuring Hadoop Security in the - <xref href="http://www.cloudera.com/documentation/enterprise/latest/topics/cdh_sg_cdh5_hadoop_security.html"; scope="external" format="html">CDH 5 Security Guide</xref>. + Impala supports an enterprise-grade authentication system called Kerberos. Kerberos provides strong security benefits including + capabilities that render intercepted authentication packets unusable by an attacker. It virtually eliminates the threat of + impersonation by never sending a user's credentials in cleartext over the network. For more information on Kerberos, visit + the <xref href="https://web.mit.edu/kerberos/"; scope="external" format="html">MIT Kerberos website</xref>. </p> <p> + The rest of this topic assumes you have a working <xref keyref="mit_install_kdc"/> + set up. To enable Kerberos, you first create a Kerberos principal for each host running + <cmdname>impalad</cmdname> or <cmdname>statestored</cmdname>. + </p> + + <p audience="hidden"> + For more information on enabling Kerberos authentication, see the + topic on Configuring Hadoop Security in the + <xref href="http://www.cloudera.com/documentation/enterprise/latest/topics/cdh_sg_cdh5_hadoop_security.html"; scope="external" format="html">CDH 5 Security Guide</xref>. When using Impala in a managed environment, Cloudera Manager automatically completes Kerberos configuration. - In an unmanaged environment, create a Kerberos principal for each host running <cmdname>impalad</cmdname> or - <cmdname>statestored</cmdname>. <ph rev="upstream">Cloudera</ph> recommends using a consistent format, such as + <ph rev="upstream">Cloudera</ph> recommends using a consistent format, such as <codeph>impala/_HOST@Your-Realm</codeph>, but you can use any three-part Kerberos server principal. </p> - <p conref="../shared/impala_common.xml#common/user_kerberized"/> - <note conref="../shared/impala_common.xml#common/authentication_vs_authorization"/> - <p outputclass="toc inpage"/> - <p> An alternative form of authentication you can use is LDAP, described in <xref href="impala_ldap.xml#ldap"/>. </p> + + <p outputclass="toc inpage"/> + </conbody> <concept id="kerberos_prereqs"> @@ -88,7 +96,7 @@ under the License. documentation</xref>. </p> <p rev="1.2"> - Currently, you cannot use the resource management feature in CDH 5 on a cluster that has Kerberos + Currently, you cannot use the resource management feature on a cluster that has Kerberos authentication enabled. </p> </note> @@ -99,12 +107,12 @@ under the License. name of the <codeph>keytab</codeph> file containing the credentials for the principal. </p> - <p> + <p audience="hidden"> Impala supports the Cloudera ODBC driver and the Kerberos interface provided. To use Kerberos through the - ODBC driver, the host type must be set depending on the level of the ODBD driver: + ODBC driver, the host type must be set depending on the level of the ODBC driver: </p> - <ul> + <ul audience="hidden"> <li> <codeph>SecImpala</codeph> for the ODBC 1.0 driver. </li> @@ -130,8 +138,8 @@ under the License. <p> To enable Impala to work with Kerberos security on your Hadoop cluster, make sure you perform the installation and configuration steps in - <xref href="http://www.cloudera.com/documentation/enterprise/latest/topics/sg_authentication.html"; scope="external" format="html">Authentication in the CDH 5 Security Guide</xref>. - Also note that when Kerberos security is enabled in Impala, a web browser that + <xref keyref="upstream_hadoop_authentication"/>. + Note that when Kerberos security is enabled in Impala, a web browser that supports Kerberos HTTP SPNEGO is required to access the Impala web console (for example, Firefox, Internet Explorer, or Chrome). </p> @@ -163,7 +171,8 @@ under the License. <ul> <li> Creating service principals for Impala and the HTTP service. Principal names take the form: - <codeph><varname>serviceName</varname>/<varname>fully.qualified.domain.name</varname>@<varname>KERBEROS.REALM</varname></codeph> + <codeph><varname>serviceName</varname>/<varname>fully.qualified.domain.name</varname>@<varname>KERBEROS.REALM</varname></codeph>. + <p conref="../shared/impala_common.xml#common/user_kerberized"/> </li> <li> @@ -171,8 +180,8 @@ under the License. </li> <li> - Editing <codeph>/etc/default/impala</codeph> (in cluster not managed by Cloudera Manager), or editing the - <uicontrol>Security</uicontrol> settings in the Cloudera Manager interface, to accommodate Kerberos + Editing <codeph>/etc/default/impala</codeph> <ph audience="hidden">(in cluster not managed by Cloudera Manager), or editing the + <uicontrol>Security</uicontrol> settings in the Cloudera Manager interface,</ph>to accommodate Kerberos authentication. </li> </ul> @@ -252,7 +261,7 @@ $ chown impala:impala impala-http.keytab</codeblock> --> <codeblock>-kerberos_reinit_interval=60 -principal=impala_1/[email protected] --keytab_file=/var/run/cloudera-scm-agent/process/3212-impala-IMPALAD/impala.keytab</codeblock> +-keytab_file=<varname>/path/to/impala.keytab</varname></codeblock> <p> For more information on changing the Impala defaults specified in <filepath>/etc/default/impala</filepath>, see http://git-wip-us.apache.org/repos/asf/incubator-impala/blob/025b5dbb/docs/topics/impala_ldap.xml ---------------------------------------------------------------------- diff --git a/docs/topics/impala_ldap.xml b/docs/topics/impala_ldap.xml index e2f48fa..757a4e2 100644 --- a/docs/topics/impala_ldap.xml +++ b/docs/topics/impala_ldap.xml @@ -47,12 +47,13 @@ under the License. <note conref="../shared/impala_common.xml#common/authentication_vs_authorization"/> - <p outputclass="toc inpage"/> - <p> An alternative form of authentication you can use is Kerberos, described in <xref href="impala_kerberos.xml#kerberos"/>. </p> + + <p outputclass="toc inpage"/> + </conbody> <concept id="ldap_prereqs"> @@ -121,8 +122,8 @@ under the License. <codeph>--ldap_uri</codeph> sets the URI of the LDAP server to use. Typically, the URI is prefixed with <codeph>ldap://</codeph>. In Impala 1.4.0 and higher, you can specify secure SSL-based LDAP transport by using the prefix <codeph>ldaps://</codeph>. The URI can optionally specify the port, for example: - <codeph>ldap://ldap_server.cloudera.com:389</codeph> or - <codeph>ldaps://ldap_server.cloudera.com:636</codeph>. (389 and 636 are the default ports for non-SSL and + <codeph>ldap://ldap_server.example.com:389</codeph> or + <codeph>ldaps://ldap_server.example.com:636</codeph>. (389 and 636 are the default ports for non-SSL and SSL LDAP connections, respectively.) </li> @@ -160,8 +161,8 @@ under the License. <p> However, LDAP servers often require more complex, structured usernames for authentication. Impala supports three ways of transforming the short name (for example, <codeph>'henry'</codeph>) to a more complicated - string. If necessary, specify one of the following configuration options when starting the - <cmdname>impalad</cmdname> daemon on each DataNode: + string. If necessary, specify one of the following configuration options + when starting the <cmdname>impalad</cmdname> daemon on each DataNode: </p> <ul> @@ -184,11 +185,6 @@ under the License. </li> </ul> - <p rev="CDH-26854"> - For clusters not managed by Cloudera Manager, - specify the option on the <cmdname>impalad</cmdname> command line. - </p> - <p audience="hidden"> For clusters managed by Cloudera Manager 5.4.0 and higher, search for the configuration field names <codeph>ldap_domain</codeph>,
