This is the documentation for Cloudera Manager 5.1.x. Documentation for other versions is available at Cloudera Documentation.

Appendix B - Set up a Cluster-dedicated MIT KDC and Default Domain for the Hadoop Cluster

Important: If you have existing Kerberos host keytabs at your site, it's important that you read this section to prevent your existing host keytabs from becoming invalid.

If you use the instructions in this guide to 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.

Note: The following instructions illustrate an example of creating and deploying the principals and keytab files for MIT Kerberos. (If you are using another version of Kerberos, refer the Kerberos documentation for the version of the operating system you are using, for instructions.)

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 or kadmin from any host, run one of the following:

```
$ sudo kadmin.local
```
```
$ kadmin
```

Note:

In this guide, kadmin is shown as the prompt for commands in the kadmin shell, but you can type the same commands at the kadmin.local prompt in the kadmin.local shell.
Running kadmin.local may prompt you for a password because it is being run via sudo. You should provide your Unix password. Running kadmin may prompt you for a password because you need Kerberos admin privileges. You should provide your Kerberos admin password.

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 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 service principal names (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@CLUSTER-REALM.COMPANY.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 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 here 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.

Using a Cluster-Dedicated KDC with a Central MIT KDC

Important: If you plan to use Oozie or the Hue Kerberos ticket renewer in your cluster, you must configure your KDC to allow tickets to be renewed, and you must configure krb5.conf to request renewable tickets. Typically, you can do this by adding the max_renewable_life setting to your realm in kdc.conf, and by adding the renew_lifetime parameter to the libdefaults section of krb5.conf. For more information about renewable tickets, see the Kerberos documentation. This is covered in our example krb5.conf and kdc.conf files.

In the /var/kerberos/krb5kdc/kdc.conf file on the local dedicated KDC server host, (for example, KDC-Server-hostname.CLUSTER-REALM.com), configure the default realm for the Hadoop cluster by substituting YOUR-LOCAL-REALM.COMPANY.COM in the following realms property. Please refer to our example kdc.conf file for more information:
```
[realms]
 CLUSTER-REALM.COMPANY.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-LOCAL-REALM.COMPANY.COM in the following realms property. Also specify the local dedicated KDC server host name in the /etc/krb5.conf file (for example, KDC-Server-hostname.your-local-realm.company.com).

[libdefaults]
 default_realm = CLUSTER-REALM.COMPANY.COM
[realms]
 CLUSTER-REALM.COMPANY.COM = {
  kdc = KDC-Server-hostname.CLUSTER-REALM.company.com:88
  admin_server = KDC-Server-hostname.CLUSTER-REALM.company.com:749
  default_domain = CLUSTER-REALM.company.com
 }
 YOUR-CENTRAL-REALM.COMPANY.COM = {
  kdc = KDC-Server-hostname.your-central-realm.company.com:88
  admin_server = KDC-Server-hostname.your-central-realm.company.com:749
  default_domain = your-central-realm.company.com
 }
[domain_realm]
 .CLUSTER-REALM.company.com = CLUSTER-REALM.COMPANY.COM
  CLUSTER-REALM.company.com = CLUSTER-REALM.COMPANY.COM
 .your-central-realm.company.com = YOUR-CENTRAL-REALM.COMPANY.COM
  your-central-realm.company.com = YOUR-CENTRAL-REALM.COMPANY.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 CLUSTER-REALM.COMPANY.COM, and substitute your central KDC realm for YOUR-CENTRAL-REALM.COMPANY.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/CLUSTER-REALM.COMPANY.COM@YOUR-CENTRAL-REALM.COMPANY.COM 
```
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/CLUSTER-REALM.COMPANY.COM@YOUR-CENTRAL-REALM.COMPANY.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 (CDH 4) Appendix C - Configuring the Mapping from Kerberos Principals to Short Names or (CDH 5) Appendix C - 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

Important: If you are using Active Directory, ensure you have installed the openldap-clients package on the Cloudera Manager Server host before you begin configuring Kerberos authentication.

In the /var/kerberos/krb5kdc/kdc.conf file on the local dedicated KDC server host, (for example, kdc-server-hostname.cluster.corp.company.com), configure the default realm for the Hadoop cluster by substituting YOUR-LOCAL-REALM.COMPANY.COM in the following realms property:
```
[realms]
 CLUSTER-REALM.COMPANY.COM = {
```

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 = CLUSTER-REALM.COMPANY.COM
[realms]
  AD-REALM.COMPANY.COM = {
    kdc = ad.corp.company.com:88
    admin_server = ad.corp.company.com:749
    default_domain = ad.corp.company.com
  }
  CLUSTER-REALM.COMPANY.COM = {
    kdc = kdc-server-hostname.cluster.corp.company.com:88
    admin_server = kdc-server-hostname.cluster.corp.company.com:749
    default_domain = cluster.corp.company.com
 }
[domain_realm]
 .cluster.corp.company.com = CLUSTER-REALM.COMPANY.COM
  cluster.corp.company.com = CLUSTER-REALM.COMPANY.COM
 .corp.company.com = AD-REALM.COMPANY.COM
  corp.company.com = AD-REALM.COMPANY.COM

To properly translate principal names from the Active Directory 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 (CDH 4) Appendix C - Configuring the Mapping from Kerberos Principals to Short Names or (CDH 5) Appendix C - 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.
On the Active Directory server host, type the following command to specify the local MIT KDC host name (for example, kdc-server-hostname.cluster.corp.company.com) and local realm (for example, CLUSTER-REALM.COMPANY.COM):
```
ksetup /addkdc CLUSTER-REALM.COMPANY.COM kdc-server-hostname.cluster.corp.company.com
```
Run this command on every domain controller that will be referenced by the cluster's krb5.conf file. If load balancing is being used and a single KDC hostname has to be provided to all domain controllers, refer the Microsoft documentation instead of explicitly using the ksetup command on individual domain controllers.
On the Active Directory server host, type the following command to add the local realm trust to Active Directory:
```
netdom trust CLUSTER-REALM.COMPANY.COM /Domain:AD-REALM.COMPANY.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 CLUSTER-REALM.COMPANY.COM /TrustEncryp RC4
```
Windows 2008
Note: When using AES 256 encryption with Windows 2008 you must update the proper Java Cryptography Extension (JCE) policy files for the version of JDK you are using.
- JCE Policy Files - JDK 1.6
- JCE Policy Files - JDK 1.7
```
ksetup /SetEncTypeAttr CLUSTER-REALM.COMPANY.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 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/CLUSTER-REALM.COMPANY.COM@AD-REALM.COMPANY.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 Forrest "Functional level"
Active Directory will, based on the Domain or Forrest 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/CLUSTER-REALM.COMPANY.COM@AD-REALM.COMPANY.COM
```
- Windows 2008
```
kadmin: addprinc -e "aes256-cts:normal aes128-cts:normal rc4-hmac:normal" krbtgt/CLUSTER-REALM.COMPANY.COM@AD-REALM.COMPANY.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.
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.

Page generated September 3, 2015.