Configuring a Cluster-dedicated MIT KDC and Default Domain for a Cluster

If you use Cloudera Manager to enable Hadoop security on your cluster, the Cloudera Manager Server will create the hdfs, mapred, oozie, HTTP, hue, and host principals and then generate keytabs for those principals. Cloudera Manager will then deploy the keytab files on every host in the cluster.

When to use kadmin.local and kadmin

When performing the Kerberos commands in this document, you can use kadmin.local or kadmin depending on your access and account:

If you can log on to the KDC host directly, and have root access or a Kerberos admin account, use the kadmin.local command.
When accessing the KDC from a remote host, use the kadmin command.

To start kadmin.local on the KDC host:

$ sudo kadmin.local

To run kadmin from any host:

$ kadmin

Setting up a Cluster-Dedicated KDC and Default Realm for the Hadoop Cluster

Cloudera has tested the following configuration approaches to Kerberos security for clusters managed by Cloudera Manager. For administration teams that are just getting started with Kerberos security, we recommend starting with these approaches to the configuration of KDC services for a number of reasons.

The number of Service Principal Names (SPNs) that are created and managed by the Cloudera Manager server for a CDH cluster can be significant, and it is important to realize the impact on cluster uptime and overall operations when keytabs must be managed manually by hand. The Cloudera Manager server will manage the creation of service keytabs on the proper hosts based on the current configuration of the database. Manual keytab management can be error prone and face delays when deploying new or moving services within the cluster, especially under time-sensitive conditions.

Cloudera Manager will create SPNs within a KDC that it can access with the kadmin command and reach based on configuration of the /etc/krb5.conf on all systems participating in the cluster. SPNs must be created in the form of service-name/host.fqdn.name@EXAMPLE.COM where service name is the relevant CDH service name such as hue or hbase or hdfs.

If your site already has a working KDC and keytabs for any of the principals that Cloudera Manager creates, as described in the following sections, the Cloudera Manager Server will randomize the key stored in the keytab file and consequently cause your existing host keytabs to become invalid.

This is why Cloudera recommends you prevent your existing host keytabs from becoming invalid is by using a dedicated local MIT Kerberos KDC and default realm for the Hadoop cluster and create all Hadoop hdfs, mapred, oozie, HTTP, hue, and host service principals in that realm. You can also set up a one-way cross-realm trust from the cluster-dedicated KDC and realm to your existing central MIT Kerberos KDC, or to an existing Active Directory realm. Using this method, there is no need to create service principals in the central MIT Kerberos KDC or in Active Directory, but principals (users) in the central MIT KDC or in Active Directory can be authenticated to Hadoop. The steps to implement this approach are as follows:

Install and configure a cluster-dedicated MIT Kerberos KDC that will be managed by Cloudera Manager for creating and storing the service principals for your Hadoop cluster.
See the example kdc.conf and krb5.conf files in Sample Kerberos Configuration files: krb5.conf, kdc.conf, kadm5.acl for configuration considerations for the KDC and Kerberos clients.
Configure a default Kerberos realm for the cluster you want Cloudera Manager to manage and set up one-way cross-realm trust between the cluster-dedicated KDC and either your central KDC or Active Directory. Follow the appropriate instructions below for your deployment: Using a Cluster-Dedicated KDC with a Central MIT KDC or Using a Cluster-Dedicated MIT KDC with Active Directory.

Cloudera strongly recommends the method above because:

It requires minimal configuration in Active Directory.
It is comparatively easy to script the creation of many principals and keytabs. A principal and keytab must be created for every daemon in the cluster, and in a large cluster this can be extremely onerous to do directly in Active Directory.
There is no need to involve central Active Directory administrators in order to get service principals created.
It allows for incremental configuration. The Hadoop administrator can completely configure and verify the functionality the cluster independently of integrating with Active Directory.

Using a Cluster-Dedicated KDC with a Central MIT KDC

In the /var/kerberos/krb5kdc/kdc.conf file on the local dedicated KDC server host, configure the default realm for the Hadoop cluster by substituting your Kerberos realm in the following realms property. Please refer to our example kdc.conf file for more information:
```
[realms]
 HADOOP.EXAMPLE.COM = {
```

In the /etc/krb5.conf file on all cluster hosts and all Hadoop client user hosts, configure the default realm for the Hadoop cluster by substituting your Kerberos realm in the following realms property. Also specify the local dedicated KDC server hostname in the /etc/krb5.conf file (for example, kdc01.example.com).

[libdefaults]
  default_realm = HADOOP.EXAMPLE.COM
[realms]
  HADOOP.EXAMPLE.COM = {
    kdc = kdc01.hadoop.example.com:88
    admin_server = kdc01.hadoop.example.com:749
    default_domain = hadoop.example.com
  }
  EXAMPLE.COM = {
    kdc = kdc01.example.com:88
    admin_server = kdc01.example.com:749
    default_domain = example.com
  }
[domain_realm]
  .hadoop.example.com = HADOOP.EXAMPLE.COM
  hadoop.example.com = HADOOP.EXAMPLE.COM
  .example.com = EXAMPLE.COM
  example.com = EXAMPLE.COM

To set up the cross-realm trust in the cluster-dedicated KDC, type the following command in the kadmin.local or kadmin shell on the cluster-dedicated KDC host to create a krbtgt principal. Substitute your cluster-dedicated KDC realm for HADOOP.EXAMPLE.COM, and substitute your central KDC realm for EXAMPLE.COM. Enter a password when prompted. Note the password because you will need to enter the same exact password in the central KDC in the next step.
```
kadmin:  addprinc krbtgt/HADOOP.EXAMPLE.COM@EXAMPLE.COM 
```
Each of your Hadoop client users must also place this information in their local core-site.xml file. The easiest way to do so is by using the Cloudera Manager Admin Console to generate a client configuration file.
To set up the cross-realm trust in the central KDC, type the same command in the kadmin.local or kadmin shell on the central KDC host to create the exact same krbtgt principal and password.
```
kadmin:  addprinc krbtgt/HADOOP.EXAMPLE.COM@EXAMPLE.COM 
```
Important: In order for a cross-realm trust to operate properly, both KDCs must have the same krbtgt principal and password, and both KDCs must be configured to use the same encryption type.
To properly translate principal names from the central KDC realm into the cluster-dedicated KDC realm for the Hadoop cluster, configure the Trusted Kerberos Realms property of the HDFS service.
1. Open the Cloudera Manager Admin Console.
2. Go to the HDFS service.
3. Click the Configuration tab.
4. Expand the Service-Wide category and click Security.
5. Scroll down to the Trusted Kerberos Realms property, and click on the Value field to add the name of your central KDC realm. If you need to use more advanced mappings which do more than just allow principals from another domain, you may enter them in the Additional Rules to Map Kerberos Principals to Short Names property. For more information about name mapping rules, see Configuring the Mapping from Kerberos Principals to Short Names.
Each of your Hadoop client users must also place this information in their local core-site.xml file. The easiest way to do so is by using the Cloudera Manager Admin Console to generate a client configuration file.
Proceed to Step 2: If You are Using AES-256 Encryption, Install the JCE Policy File. Later in this procedure, you will restart the services to have the configuration changes in core-site.xml take effect.

Using a Cluster-Dedicated MIT KDC with Active Directory

On the Active Directory Server

On the Active Directory server host, type the following command to add the local realm trust to Active Directory:
```
netdom trust HADOOP.EXAMPLE.COM /Domain:EXAMPLE.COM /add /realm /passwordt:TrustPassword
```
On the Active Directory server host, type the following command to set the proper encryption type:
Windows 2003 RC2
Windows 2003 server installations do not support AES encryption for Kerberos. Therefore RC4 should be used. Please see the Microsoft reference documentation for more information.
```
ktpass /MITRealmName HADOOP.EXAMPLE.COM /TrustEncryp RC4
```
Windows 2008
```
ksetup /SetEncTypeAttr HADOOP.EXAMPLE.COM <enc_type>
```
Where the <enc_type> parameter can be replaced with parameter strings for AES, DES, or RC4 encryption modes. For example, for AES encryption, replace <enc_type> with AES256-CTS-HMAC-SHA1-96 or AES128-CTS-HMAC-SHA1-96 and for RC4 encryption, replace with RC4-HMAC-MD5. See the Microsoft reference documentation for more information.
Important: Make the encryption type you specify is supported on both your version of Windows Active Directory and your version of MIT Kerberos.

On the MIT KDC server

In the /var/kerberos/krb5kdc/kdc.conf file on the local dedicated KDC server host, configure the default realm for the Hadoop cluster by substituting your Kerberos realm in the following realms property:
```
[realms]
 HADOOP.EXAMPLE.COM = {
```
Each of your Hadoop client users must also place this information in their local core-site.xml file. The easiest way to do so is by using the Cloudera Manager Admin Console to generate a client configuration file.
On the local MIT KDC server host, type the following command in the kadmin.local or kadmin shell to add the cross-realm krbtgt principal:
```
kadmin:  addprinc -e "<enc_type_list>" krbtgt/HADOOP.EXAMPLE.COM@EXAMPLE.COM
```
where the <enc_type_list> parameter specifies the types of encryption this cross-realm krbtgt principal will support: either AES, DES, or RC4 encryption. You can specify multiple encryption types using the parameter in the command above, what's important is that at least one of the encryption types corresponds to the encryption type found in the tickets granted by the KDC in the remote realm.

Examples by Active Directory Domain or Forest "Functional level"
Active Directory will, based on the Domain or Forest functional level, use encryption types supported by that release of the Windows Server operating system. It is not possible to use AES encryption types with an AD 2003 functional level. If you notice that DES encryption types are being used when authenticating or requesting service tickets to Active Directory then it might be necessary to enable weak encryption types in the /etc/krb5.conf. Please see the example krb5.conf file for more information.
- Windows 2003
```
kadmin: addprinc -e "rc4-hmac:normal" krbtgt/HADOOP.EXAMPLE.COM@EXAMPLE.COM
```
- Windows 2008
```
kadmin: addprinc -e "aes256-cts:normal aes128-cts:normal rc4-hmac:normal" krbtgt/HADOOP.EXAMPLE.COM@EXAMPLE.COM
```
Note: The cross-realm krbtgt principal that you add in this step must have at least one entry that uses the same encryption type as the tickets that are issued by the remote KDC. If no entries have the same encryption type, then the problem you will see is that authenticating as a principal in the local realm will allow you to successfully run Hadoop commands, but authenticating as a principal in the remote realm will not allow you to run Hadoop commands.

On all of the cluster hosts

In the /etc/krb5.conf file on all cluster hosts and all Hadoop client user hosts, configure both Kerberos realms. Note that the default realm and the domain realm should be configured as the local MIT Kerberos realm for the cluster. Your krb5.conf will contain more configuration properties than those provided below. This example has been provided to clarify REALM/KDC configuration. Please see our example krb5.conf file for more information.

[libdefaults]
  default_realm = HADOOP.EXAMPLE.COM
[realms]
  EXAMPLE.COM = {
    kdc = dc01.example.com:88
    admin_server = dc01.example.com:749
    default_domain = example.com
  }
  HADOOP.EXAMPLE.COM = {
    kdc = kdc01.hadoop.example.com:88
    admin_server = kdc01.hadoop.example.com:749
    default_domain = hadoop.example.com
  }
[domain_realm]
  .hadoop.example.com = HADOOP.EXAMPLE.COM
  hadoop.example.com = HADOOP.EXAMPLE.COM
  .example.com = EXAMPLE.COM
  example.com = EXAMPLE.COM

Use one of the following methods to properly translate principal names from the Active Directory realm into the cluster-dedicated KDC realm for the Hadoop cluster.
- Using Cloudera Manager: Configure the Trusted Kerberos realms property of the HDFS service:
  1. Open the Cloudera Manager Admin Console.
  2. Go to the HDFS service.
  3. Click the Configuration tab.
  4. Expand the Service-Wide category and click Security.
  5. Scroll down to the Trusted Kerberos Realms property, and click on the Value field to add the name of your central KDC realm. If you need to use more advanced mappings which do more than just allow principals from another domain, you may enter them in the Additional Rules to Map Kerberos Principals to Short Names property. For more information about name mapping rules, see Configuring the Mapping from Kerberos Principals to Short Names.
- Using the Command Line: Configure the hadoop.security.auth_to_local setting in the core-site.xml file on all of the cluster hosts. The following example translates all principal names with the realm EXAMPLE.COM into the first component of the principal name only. It also preserves the standard translation for the default realm (the cluster realm).
```
<property>
  <name>hadoop.security.auth_to_local</name>
  <value>
    RULE:[1:$1@$0](^.*@EXAMPLE\.COM$)s/^(.*)@EXAMPLE\.COM$/$1/g
    RULE:[2:$1@$0](^.*@EXAMPLE\.COM$)s/^(.*)@EXAMPLE\.COM$/$1/g
    DEFAULT
  </value>
</property>
```

Enabling Debugging Output for the Sun Kerberos Classes

Integrating Hadoop Security with Active Directory