Author: jghoman
Date: Fri Jun 4 00:41:13 2010
New Revision: 951227
URL: http://svn.apache.org/viewvc?rev=951227&view=rev
Log:
HADOOP-6661. User document for UserGroupInformation.doAs. Contributed by
Jitendra Pandey.
Added:
hadoop/common/trunk/src/docs/src/documentation/content/xdocs/Superusers.xml
Modified:
hadoop/common/trunk/CHANGES.txt
hadoop/common/trunk/src/docs/src/documentation/content/xdocs/site.xml
Modified: hadoop/common/trunk/CHANGES.txt
URL:
http://svn.apache.org/viewvc/hadoop/common/trunk/CHANGES.txt?rev=951227&r1=951226&r2=951227&view=diff
==============================================================================
--- hadoop/common/trunk/CHANGES.txt (original)
+++ hadoop/common/trunk/CHANGES.txt Fri Jun 4 00:41:13 2010
@@ -38,6 +38,9 @@ Trunk (unreleased changes)
HADOOP-6714. Resolve compressed files using CodecFactory in FsShell::text.
(Patrick Angeles via cdouglas)
+ HADOOP-6661. User document for UserGroupInformation.doAs.
+ (Jitendra Pandey via jghoman)
+
BUG FIXES
HADOOP-6638. try to relogin in a case of failed RPC connection (expired
tgt)
only in case the subject is loginUser or proxyUgi.realUser. (boryas)
Added:
hadoop/common/trunk/src/docs/src/documentation/content/xdocs/Superusers.xml
URL:
http://svn.apache.org/viewvc/hadoop/common/trunk/src/docs/src/documentation/content/xdocs/Superusers.xml?rev=951227&view=auto
==============================================================================
--- hadoop/common/trunk/src/docs/src/documentation/content/xdocs/Superusers.xml
(added)
+++ hadoop/common/trunk/src/docs/src/documentation/content/xdocs/Superusers.xml
Fri Jun 4 00:41:13 2010
@@ -0,0 +1,106 @@
+<?xml version="1.0"?>
+<!--
+ Copyright 2002-2004 The Apache Software Foundation
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN"
+ "http://forrest.apache.org/dtd/document-v20.dtd";>
+
+
+<document>
+
+ <header>
+ <title>
+ Superusers Acting On Behalf Of Other Users
+ </title>
+ </header>
+
+ <body>
+ <section>
+ <title> Introduction </title>
+ <p>
+ This document describes how a superuser can submit jobs or access hdfs
on behalf of another user in a secured way.
+ </p>
+ </section>
+
+ <section>
+ <title> Use Case </title>
+ <p>
+ The code example described in the next section is applicable for the
following use case.
+ </p>
+ <p>
+ A superuser with username 'super' wants to submit job and access
hdfs on behalf of a user joe. The superuser has kerberos credentials but user
joe doesn't have any. The tasks are required to run as user joe and any file
accesses on namenode are required to be done as user joe. It is required that
user joe can connect to the namenode or job tracker on a connection
authenticated with super's kerberos credentials. In other words super is
impersonating the user joe.
+ </p>
+ </section>
+
+
+ <section>
+ <title> Code example </title>
+ <p>
+ In this example super's kerberos credentials are used for login
and a proxy user ugi object is created for joe. The operations are performed
within the doAs method of this proxy user ugi object.
+ </p>
+ <source>
+ ...
+ //Create ugi for joe. The login user is 'super'.
+ UserGroupInformation ugi =
+ UserGroupInformation.createProxyUser("joe",
UserGroupInformation.getLoginUser());
+ ugi.doAs(new PrivilegedExceptionAction<Void>() {
+ public Void run() throws Exception {
+ //Submit a job
+ JobClient jc = new JobClient(conf);
+ jc.submitJob(conf);
+ //OR access hdfs
+ FileSystem fs = FileSystem.get(conf);
+ fs.mkdir(someFilePath);
+ }
+ }
+ </source>
+ </section>
+
+ <section>
+ <title> Configurations </title>
+ <p>
+ The superuser must be configured on namenode and jobtracker to be
allowed to impersonate another user. Following configurations are required.
+ </p>
+ <source>
+ <property>
+ <name>hadoop.proxyuser.super.groups</name>
+ <value>group1,group2</value>
+ <description>Allow the superuser super to impersonate any
members of the group group1 and group2</description>
+ </property>
+ <property>
+ <name>hadoop.proxyuser.super.hosts</name>
+ <value>host1,host2</value>
+ <description>The superuser can connect only from host1
and host2 to impersonate a user</description>
+ </property>
+ </source>
+ <p>
+ If these configurations are not present, impersonation will not be
allowed and connection will fail.
+ </p>
+ </section>
+
+
+ <section>
+ <title> Caveats </title>
+ <p>
+ The superuser must have kerberos credentials to be able to
impersonate another user. It cannot use delegation tokens for this feature. It
would be wrong if superuser adds its own delegation token to the proxy user
ugi, as it will allow the proxy user to connect to the service with the
privileges of the superuser.
+ </p>
+ <p>
+ However, if the superuser does want to give a delegation token to
joe, it must first impersonate joe and get a delegation token for joe, in the
same way as the code example above, and add it to the ugi of joe. In this way
the delegation token will have the owner as joe.
+ </p>
+ </section>
+ </body>
+</document>
+
Modified: hadoop/common/trunk/src/docs/src/documentation/content/xdocs/site.xml
URL:
http://svn.apache.org/viewvc/hadoop/common/trunk/src/docs/src/documentation/content/xdocs/site.xml?rev=951227&r1=951226&r2=951227&view=diff
==============================================================================
--- hadoop/common/trunk/src/docs/src/documentation/content/xdocs/site.xml
(original)
+++ hadoop/common/trunk/src/docs/src/documentation/content/xdocs/site.xml Fri
Jun 4 00:41:13 2010
@@ -42,6 +42,7 @@ See http://forrest.apache.org/docs/linki
<fsshell label="File
System Shell" href="file_system_shell.html" />
<SLA label="Service
Level Authorization" href="service_level_auth.html"/>
<native_lib label="Native
Libraries" href="native_libraries.html"
/>
+ <superusers label="Superusers Acting On
Behalf Of Other Users" href="Superusers.html"/>
</docs>
<docs label="Miscellaneous">
