svn commit: r1641419 - /incubator/slider/site/trunk/content/docs/security.md

[jm...@apache.org]

Author: jmaron
Date: Mon Nov 24 16:55:04 2014
New Revision: 1641419

URL: http://svn.apache.org/r1641419
Log:
updated keytab distribution and installation section

Modified:
    incubator/slider/site/trunk/content/docs/security.md

Modified: incubator/slider/site/trunk/content/docs/security.md
URL: http://svn.apache.org/viewvc/incubator/slider/site/trunk/content/docs/security.md?rev=1641419&r1=1641418&r2=1641419&view=diff
==============================================================================
--- incubator/slider/site/trunk/content/docs/security.md (original)
+++ incubator/slider/site/trunk/content/docs/security.md Mon Nov 24 16:55:04 2014
@@ -118,21 +118,24 @@ The Application Master will read in the 
 relevant number of componentss. 
 
 ### The Keytab distribution/access Options
-  The AM has been modified to leverage keytabs for authenticating rather than relying on delegation-token based authentication mechanisms.  In order to perform this login the AM requires access to a keytab file that contains the principal representing the user identity to be associated with the launched application instance.  There are two mechanisms supported for keytab access and/or distribution:
+  Rather than relying on delegation token based authentication mechanisms, the AM leverages keytab files for obtaining the principals to authenticate to the configured cluster KDC. In order to perform this login the AM requires access to a keytab file that contains the principal representing the user identity to be associated with the launched application instance (e.g. in an HBase installation you may elect to leverage the ‘hbase’ principal for this purpose). There are two mechanisms supported for keytab access and/or distribution:
 
 #### Local Keytab file access:
 
-  An application deployer may choose to pre-distribute the keytab files required to the node manager hosts in a yarn cluster.  In that instance the appConfig.json requires the following property:
+  An application deployer may choose to pre-distribute the keytab files required to the Node Manager (NM) hosts in a Yarn cluster. In that instance the appConfig.json requires the following properties:
 
     . . .
     "components": {
         "slider-appmaster": {
             "jvm.heapsize": "256M",
-            "slider.am.keytab.local.path": "/etc/security/keytabs/hbase.headless.keytab"
+            "slider.am.keytab.local.path": "/etc/security/keytabs/hbase.headless.keytab",
+            “slider.keytab.principal.name” : “hbase"
         }
     }
 
-  The “slider.am.keytab.local.path” property provides the full path to the keytab file location and is mandatory for the local lookup mechanism.  In this scenario the distribution of keytab files for the AM AND the application itself is the purview of the application deployer.  So, for example, for an hbase deployment, the hbase site service keytab will have to be distributed as well and indicated in the hbase-site properties:
+  The “slider.am.keytab.local.path” property provides the full path to the keytab file location and is mandatory for the local lookup mechanism.  The principal to leverage from the file is identified by the “slider.keytab.principal.name” property.
+  
+  In this scenario the distribution of keytab files for the AM AND the application itself is the purview of the application deployer.  So, for example, for an hbase deployment, the hbase site service keytab will have to be distributed as well and indicated in the hbase-site properties:
 
         . . .
         "site.hbase-site.hbase.master.kerberos.principal": "hbase/_HOST@EXAMPLE.COM",
@@ -141,21 +144,22 @@ relevant number of componentss. 
 
 #### Slider keytab distribution:
 
-  The deployer can select to upload the keytab files for the AM and the application to an HDFS directory (with appropriate permissions set) and slider will localize the keytab files to locations accessible by the AM or the application containers:
+  The deployer can select to upload the keytab files (manually or using the Slider client install-keytab option - see below) for the AM and the application to an HDFS directory (with appropriate permissions set) and slider will localize the keytab files to locations accessible by the AM or the application containers:
 
     . . .
     "components": {
         "slider-appmaster": {
             "jvm.heapsize": "256M",
             "slider.hdfs.keytab.dir": ".slider/keytabs/hbase",
-            "slider.am.login.keytab.name": "hbase.headless.keytab"
+            "slider.am.login.keytab.name": "hbase.headless.keytab",
+            “slider.keytab.principal.name” : “hbase"
         }
     }
      
    The “slider.hdfs.keytab.dir” points to an HDFS path, relative to the user’s home directory (e.g. /users/hbase), in which slider can find all keytab files required for both AM login as well as application services (e.g. for hbase that would be the headless keytab for the AM and the service keytab for the HBase application components).  If no value is specified, a default location of “.slider/keytabs/<cluster name>” is assumed.
     The “slider.am.login.keytab.name” is the name of the keytab file (mandatory property), found within the specified directory, that the AM will use to lookup up the login principal and authenticate.
 
-  If leveraging the slider-based distribution mechanism, the keytab files for components will be accessible from a “keytabs” sub-directory of the container work folder, e.g.:
+  If leveraging the slider-based distribution mechanism, the keytab files for components will be accessible from a “keytabs” sub-directory of the container work folder and can therefore be specified relative to the $AGENT_WORK_ROOT/keytabs directory, e.g.:
 
         . . .
         "site.hbase-site.hbase.master.kerberos.principal": "hbase/_HOST@EXAMPLE.COM",
@@ -167,6 +171,34 @@ relevant number of componentss. 
 * The principal name established on the client side before invocation of the Slider CLI (the principal used to ‘kinit’) or
 * The value specified for a “slider.keytab.principal.name” property. 
 
+#### Slider Client Keytab installation:
+
+The Slider client can be leveraged to install keytab files individually into a designated keytab HDFS folder. The format of the command is:
+
+	slider install-keytab —keytab <path to keytab on local file system> —folder <name of HDFS folder to store keytab> [—overwrite]
+
+The command will store the keytab file specified by the ‘—keytab’ option in to an HDFS folder that is created or exists under /user/username/.slider/keytabs named by the ‘—folder’ option (e.g. if the folder name specified is ‘HBASE’ the keytab will be stored in /user/username/.slider/keytabs/HBASE).  The command can be used to upload keytab files individually up to HDFS.  For example, if uploading both AM and HBase service keytabs to the ‘HBASE’ folder, the command will be invoked twice:
+
+	slider install-keytab —keytab /my/local/keytabs/folder/hbase.headless.keytab —folder HBASE
+	slider install-keytab —keytab /my/local/keytabs/folder/hbase.service.keytab —folder HBASE
+
+Subsequently, the associated hbase-site configuration properties would be:
+
+	"global": {
+	    . . .
+       "site.hbase-site.hbase.master.kerberos.principal": "hbase/_HOST@EXAMPLE.COM",
+       "site.hbase-site.hbase.master.keytab.file": "${AGENT_WORK_ROOT}/keytabs/hbase.service.keytab",
+       . . .
+    }
+	"components": {
+       "slider-appmaster": {
+           "jvm.heapsize": "256M",
+           "slider.hdfs.keytab.dir": ".slider/keytabs/HBASE",
+           "slider.am.login.keytab.name": "hbase.headless.keytab"
+           “slider.keytab.principal.name” : “hbase"
+       }
+   	}
+   	
 ## Securing communications between the Slider Client and the Slider AM.
 
 When the AM is deployed in a secure cluster,