This is an automated email from the ASF dual-hosted git repository.

rlevas pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/ambari.git


The following commit(s) were added to refs/heads/trunk by this push:
     new 6fce9b1  [AMBARI-23484] Update Kerberos service documentation for 
Ambari 2.7.0
6fce9b1 is described below

commit 6fce9b1ed5686814aa13454144e4b3ce89ad9b31
Author: Robert Levas <rle...@hortonworks.com>
AuthorDate: Thu Apr 5 17:47:12 2018 -0400

    [AMBARI-23484] Update Kerberos service documentation for Ambari 2.7.0
---
 .../docs/security/kerberos/enabling_kerberos.md    |  94 ++++++++++++++-----
 .../docs/security/kerberos/kerberos_service.md     | 100 ++++++++++++++-------
 2 files changed, 140 insertions(+), 54 deletions(-)

diff --git a/ambari-server/docs/security/kerberos/enabling_kerberos.md 
b/ambari-server/docs/security/kerberos/enabling_kerberos.md
index 2b14048..bfda3cd 100644
--- a/ambari-server/docs/security/kerberos/enabling_kerberos.md
+++ b/ambari-server/docs/security/kerberos/enabling_kerberos.md
@@ -83,7 +83,7 @@ curl -H "X-Requested-By:ambari" -u admin:admin -i -X POST 
http://AMBARI_SERVER:8
 curl -H "X-Requested-By:ambari" -u admin:admin -i -X PUT -d @./payload 
http://AMBARI_SERVER:8080/api/v1/clusters/CLUSTER_NAME
 ```
 
-Payload when using an MIT KDC:
+Example payload when using an MIT KDC:
 
 ```
 [
@@ -96,7 +96,7 @@ Payload when using an MIT KDC:
           "domains":"",
           "manage_krb5_conf": "true",
           "conf_dir":"/etc",
-          "content" : "[libdefaults]\n  renew_lifetime = 7d\n  forwardable= 
true\n  default_realm = {{realm|upper()}}\n  ticket_lifetime = 24h\n  
dns_lookup_realm = false\n  dns_lookup_kdc = false\n  #default_tgs_enctypes = 
{{encryption_types}}\n  #default_tkt_enctypes ={{encryption_types}}\n\n{% if 
domains %}\n[domain_realm]\n{% for domain in domains.split(',') %}\n  
{{domain}} = {{realm|upper()}}\n{% endfor %}\n{%endif %}\n\n[logging]\n  
default = FILE:/var/log/krb5kdc.log\nadmin_serve [...]
+          "content" : "[libdefaults]\n  renew_lifetime = 7d\n  forwardable = 
true\n  default_realm = {{realm}}\n  ticket_lifetime = 24h\n  dns_lookup_realm 
= false\n  dns_lookup_kdc = false\n  default_ccache_name = /tmp/krb5cc_%{uid}\n 
 #default_tgs_enctypes = {{encryption_types}}\n  #default_tkt_enctypes = 
{{encryption_types}}\n{% if domains %}\n[domain_realm]\n{%- for domain in 
domains.split(',') %}\n  {{domain|trim()}} = {{realm}}\n{%- endfor %}\n{% endif 
%}\n[logging]\n  default = FI [...]
         }
       }
     }
@@ -109,18 +109,15 @@ Payload when using an MIT KDC:
         "properties": {
           "kdc_type": "mit-kdc",
           "manage_identities": "true",
+          "create_ambari_principal": "true",
+          "manage_auth_to_local": "true",
           "install_packages": "true",
           "encryption_types": "aes des3-cbc-sha1 rc4 des-cbc-md5",
           "realm" : "EXAMPLE.COM",
-          "kdc_host" : "KDC_SERVER",
-          "admin_server_host" : "KDC_SERVER",
+          "kdc_hosts" : "FQDN.KDC.SERVER",
+          "master_kdc" : "FQDN.MASTER.KDC.SERVER",
+          "admin_server_host" : "FQDN.ADMIN.KDC.SERVER",
           "executable_search_paths" : "/usr/bin, /usr/kerberos/bin, /usr/sbin, 
/usr/lib/mit/bin, /usr/lib/mit/sbin",
-          "password_length": "20",
-          "password_min_lowercase_letters": "1",
-          "password_min_uppercase_letters": "1",
-          "password_min_digits": "1",
-          "password_min_punctuation": "1",
-          "password_min_whitespace": "0",
           "service_check_principal_name" : "${cluster_name}-${short_date}",
           "case_insensitive_username_rules" : "false"
         }
@@ -130,7 +127,7 @@ Payload when using an MIT KDC:
 ]
 ```
 
-Payload when using an Active Directory:
+Example payload when using an Active Directory:
 
 ```
 [
@@ -143,7 +140,7 @@ Payload when using an Active Directory:
           "domains":"",
           "manage_krb5_conf": "true",
           "conf_dir":"/etc",
-          "content" : "[libdefaults]\n  renew_lifetime = 7d\n  forwardable= 
true\n  default_realm = {{realm|upper()}}\n  ticket_lifetime = 24h\n  
dns_lookup_realm = false\n  dns_lookup_kdc = false\n  #default_tgs_enctypes = 
{{encryption_types}}\n  #default_tkt_enctypes ={{encryption_types}}\n\n{% if 
domains %}\n[domain_realm]\n{% for domain in domains.split(',') %}\n  
{{domain}} = {{realm|upper()}}\n{% endfor %}\n{%endif %}\n\n[logging]\n  
default = FILE:/var/log/krb5kdc.log\nadmin_serve [...]
+          "content" : "[libdefaults]\n  renew_lifetime = 7d\n  forwardable = 
true\n  default_realm = {{realm}}\n  ticket_lifetime = 24h\n  dns_lookup_realm 
= false\n  dns_lookup_kdc = false\n  default_ccache_name = /tmp/krb5cc_%{uid}\n 
 #default_tgs_enctypes = {{encryption_types}}\n  #default_tkt_enctypes = 
{{encryption_types}}\n{% if domains %}\n[domain_realm]\n{%- for domain in 
domains.split(',') %}\n  {{domain|trim()}} = {{realm}}\n{%- endfor %}\n{% endif 
%}\n[logging]\n  default = FI [...]
         }
       }
     }
@@ -156,11 +153,14 @@ Payload when using an Active Directory:
         "properties": {
           "kdc_type": "active-directory",
           "manage_identities": "true",
+          "create_ambari_principal": "true",
+          "manage_auth_to_local": "true",
           "install_packages": "true",
           "encryption_types": "aes des3-cbc-sha1 rc4 des-cbc-md5",
           "realm" : "EXAMPLE.COM",
-          "kdc_host" : "AD_HOST",
-          "admin_server_host" : "AD_HOST",
+          "kdc_hosts" : "FQDN.AD.SERVER",
+          "master_kdc" : "FQDN.MASTER.AD.SERVER",
+          "admin_server_host" : "FQDN.AD.SERVER",
           "ldap_url" : "LDAPS://AD_HOST:PORT",
           "container_dn" : "OU=....,....",
           "executable_search_paths" : "/usr/bin, /usr/kerberos/bin, /usr/sbin, 
/usr/lib/mit/bin, /usr/lib/mit/sbin",
@@ -179,6 +179,49 @@ Payload when using an Active Directory:
   }
 ]
 ```
+Example payload when using IPA:
+
+```
+[
+  {
+    "Clusters": {
+      "desired_config": {
+        "type": "krb5-conf",
+        "tag": "version1",
+        "properties": {
+          "domains":"",
+          "manage_krb5_conf": "true",
+          "conf_dir":"/etc",
+          "content" : "[libdefaults]\n  renew_lifetime = 7d\n  forwardable = 
true\n  default_realm = {{realm}}\n  ticket_lifetime = 24h\n  dns_lookup_realm 
= false\n  dns_lookup_kdc = false\n  default_ccache_name = /tmp/krb5cc_%{uid}\n 
 #default_tgs_enctypes = {{encryption_types}}\n  #default_tkt_enctypes = 
{{encryption_types}}\n{% if domains %}\n[domain_realm]\n{%- for domain in 
domains.split(',') %}\n  {{domain|trim()}} = {{realm}}\n{%- endfor %}\n{% endif 
%}\n[logging]\n  default = FI [...]
+        }
+      }
+    }
+  },
+  {
+    "Clusters": {
+      "desired_config": {
+        "type": "kerberos-env",
+        "tag": "version1",
+        "properties": {
+          "kdc_type": "ipa",
+          "manage_identities": "true",
+          "create_ambari_principal": "true",
+          "manage_auth_to_local": "true",
+          "install_packages": "true",
+          "encryption_types": "aes des3-cbc-sha1 rc4 des-cbc-md5",
+          "realm" : "EXAMPLE.COM",
+          "kdc_hosts" : "FQDN.KDC.SERVER",
+          "master_kdc" : "FQDN.MASTER.KDC.SERVER",
+          "admin_server_host" : "FQDN.ADMIN.KDC.SERVER",
+          "executable_search_paths" : "/usr/bin, /usr/kerberos/bin, /usr/sbin, 
/usr/lib/mit/bin, /usr/lib/mit/sbin",
+          "service_check_principal_name" : "${cluster_name}-${short_date}",
+          "case_insensitive_username_rules" : "false"
+        }
+      }
+    }
+  }
+]
+```
 
 #### Create the KERBEROS_CLIENT host components
 _Once for each host, replace HOST_NAME_
@@ -220,10 +263,15 @@ curl -H "X-Requested-By:ambari" -u admin:admin -i -X POST 
-d @./payload http://A
 Payload:
 
 ```
-The Kerberos Descriptor payload may be a complete Kerberos Descriptor or just 
the updates to overlay
-on top of the default Kerberos Descriptor.
+{
+  "artifact_data" : {
+    ... 
+  } 
+}
 ```
 
+**_Note:_** The Kerberos Descriptor payload may be a complete Kerberos 
Descriptor or just the updates to overlay on top of the default Kerberos 
Descriptor.
+
 #### Set the KDC administrator credentials
 
 ```
@@ -276,14 +324,14 @@ curl -H "X-Requested-By:ambari" -u admin:admin -i -X PUT 
-d '{"ServiceInfo": {"s
 <a name="password-generation"></a>
 #### Password Generation
 
-When Ambari generates keytab files, it uses an internal mechanism rather than 
rely on the KDC or
-Active Directory to do it.  This is because Ambari cannot request a keytab 
file from some KDCs
-such as an Active Directory. In order to create keytab files, Ambari needs to 
know the password for
-each relevant Kerberos identity.  Therefore, Ambari sets or updates the 
identity's password as needed.
+When enabling Kerberos using an Active Directory, Ambari must use an internal 
mechanism to build 
+the keytab files. This is because keytab files cannot be requested remotely 
from an Active Directory. 
+In order to create keytab files, Ambari needs to know the password for each 
relevant Kerberos 
+identity.  Therefore, Ambari sets or updates the identity's password as needed.
 
-The password for each Ambari-managed account in a KDC or Active Directory is 
randomly generated and
-stored only long enough to set the account's password and generate the keytab 
file.  Passwords are
-generated using the following user-settable parameters:
+The password for each Ambari-managed account in an Active Directory is 
randomly generated and
+stored only long enough in memory to set the account's password and generate 
the keytab file.  
+Passwords are generated using the following user-settable parameters:
 
 - Password length (`kerberos-env/password_length`)
   - Default Value: 20
diff --git a/ambari-server/docs/security/kerberos/kerberos_service.md 
b/ambari-server/docs/security/kerberos/kerberos_service.md
index c9cbd49..ced7211 100644
--- a/ambari-server/docs/security/kerberos/kerberos_service.md
+++ b/ambari-server/docs/security/kerberos/kerberos_service.md
@@ -37,9 +37,18 @@ Ambari Kerberos Automation
 
 ##### kdc_type
 
-The type of KDC being used.
-
-_Possible Values:_ `mit-kdc`, `active-directory` 
+The type of KDC being used. 
+
+_Possible Values:_ 
+- `none`
+  - Ambari is not to integrate with a KDC.  In this case, it is expected that 
the Kerberos identities 
+will be created and the keytab files are distributed manually
+- `mit-kdc`
+  - Ambari is to integrate with an MIT KDC
+- `active-directory`
+  - Ambari is to integrate with an Active Directory
+- `ipa` 
+  - Ambari is to integrate with a FreeIPA server
 
 ##### manage_identities
 
@@ -78,12 +87,12 @@ _Possible Values:_ `true`, `false`
 
 ##### ldap_url
 
-The URL to the Active Directory LDAP Interface. This value must indicate a 
secure channel using
+The URL to the Active Directory LDAP Interface. This value **must** indicate a 
secure channel using
 LDAPS since it is required for creating and updating passwords for Active 
Directory accounts.
  
 _Example:_  `ldaps://ad.example.com:636`
 
-This property is mandatory and only used if the `kdc_type` is 
`active-directory`
+If the `kdc_type` is `active-directory`, this property is mandatory.
 
 ##### container_dn
 
@@ -92,7 +101,7 @@ within the configured Active Directory
 
 _Example:_  `OU=hadoop,DC=example,DC=com`
 
-This property is mandatory and only used if the `kdc_type` is 
`active-directory`
+If the `kdc_type` is `active-directory`, this property is mandatory.
 
 ##### encryption_types
 
@@ -106,6 +115,8 @@ The default realm to use when creating service principals
 
 _Example:_ `EXAMPLE.COM`
 
+This value is expected to be in all uppercase characters.
+
 ##### kdc_hosts
 
 A comma-delimited list of IP addresses or FQDNs for the list of relevant KDC 
hosts. Optionally a
@@ -117,11 +128,22 @@ _Example:_ `kdc.example.com:88, kdc1.example.com:88`
 
 ##### admin_server_host
 
-The IP address or FQDN for the KDC Kerberos administrative host. Optionally a 
port number may be included.
+The IP address or FQDN for the Kerberos administrative host. Optionally a port 
number may be included.
+
+_Example:_ `kadmin.example.com`
+
+_Example:_ `kadmin.example.com:88`
+
+If the `kdc_type` is `mit-kdc` or `ipa`, the value must be the FQDN of the 
Kerberos administrative host. 
+
+##### master_kdc
+
+The IP address or FQDN of the master KDC host in a master-slave KDC 
deployment. Optionally a port 
+number may be included.
 
 _Example:_ `kadmin.example.com`
 
-_Example:_ `kadmin.example.com:88` 
+_Example:_ `kadmin.example.com:88`
 
 ##### executable_search_paths
 
@@ -233,9 +255,9 @@ This property is optional and only used if the `kdc_type` 
is `mit-kdc`
 
 ##### ipa_user_group
 
-The group in IPA user principals should be member of
+The group in IPA that user principals should be a member of.
 
-This property is mandatory and only used if the `kdc_type` is `ipa`
+This property is optional and only used if the `kdc_type` is `ipa`
 
 <a name="krb5-conf"></a>
 #### krb5-conf
@@ -266,34 +288,50 @@ Default value: /etc
 
 Customizable krb5.conf template (Jinja template engine)
 
-```
-Example: [libdefaults]
-renew_lifetime = 7d
-forwardable = true
-default_realm = {{realm}}
-ticket_lifetime = 24h
-dns_lookup_realm = false
-dns_lookup_kdc = false
-#default_tgs_enctypes = {{encryption_types}}
-#default_tkt_enctypes = {{encryption_types}}
+_Default value:_
 
+```
+[libdefaults]
+  renew_lifetime = 7d
+  forwardable = true
+  default_realm = {{realm}}
+  ticket_lifetime = 24h
+  dns_lookup_realm = false
+  dns_lookup_kdc = false
+  default_ccache_name = /tmp/krb5cc_%{uid}
+  #default_tgs_enctypes = {{encryption_types}}
+  #default_tkt_enctypes = {{encryption_types}}
 {% if domains %}
 [domain_realm]
-{% for domain in domains.split(',') %}
-{{domain}} = {{realm}}
-{% endfor %}
+{%- for domain in domains.split(',') %}
+  {{domain|trim()}} = {{realm}}
+{%- endfor %}
 {% endif %}
-
 [logging]
-default = FILE:/var/log/krb5kdc.log
-admin_server = FILE:/var/log/kadmind.log
-kdc = FILE:/var/log/krb5kdc.log
+  default = FILE:/var/log/krb5kdc.log
+  admin_server = FILE:/var/log/kadmind.log
+  kdc = FILE:/var/log/krb5kdc.log
 
 [realms]
-{{realm}} = {
-  admin_server = {{admin_server_host|default(kdc_host, True)}}
-  kdc = {{kdc_host}}
-}
+  {{realm}} = {
+{%- if master_kdc %}
+    master_kdc = {{master_kdc|trim()}}
+{%- endif -%}
+{%- if kdc_hosts > 0 -%}
+{%- set kdc_host_list = kdc_hosts.split(',')  -%}
+{%- if kdc_host_list and kdc_host_list|length > 0 %}
+    admin_server = {{admin_server_host|default(kdc_host_list[0]|trim(), True)}}
+{%- if kdc_host_list -%}
+{%- if master_kdc and (master_kdc not in kdc_host_list) %}
+    kdc = {{master_kdc|trim()}}
+{%- endif -%}
+{% for kdc_host in kdc_host_list %}
+    kdc = {{kdc_host|trim()}}
+{%- endfor -%}
+{% endif %}
+{%- endif %}
+{%- endif %}
+  }
 
 {# Append additional realm declarations below #}
 ```

-- 
To stop receiving notification emails like this one, please contact
rle...@apache.org.

Reply via email to