Apache
/
hadoop
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

HADOOP-6507. Hadoop Common Docs - delete 3 doc files that do not belong under Common. Contributed by Corinne Chandel. 

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/trunk@933406 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Thomas White 2010-04-12 20:57:27 +00:00
parent fb154e3a03
commit 631f45618d
4 changed files with 3 additions and 959 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGES.txt
View File

@ -314,6 +314,9 @@ Trunk (unreleased changes)
HADOOP-6691. TestFileSystemCaching sometimes hangs. (hairong)
HADOOP-6507. Hadoop Common Docs - delete 3 doc files that do not belong
under Common. (Corinne Chandel via tomwhite)
Release 0.21.0 - Unreleased
INCOMPATIBLE CHANGES

192
src/docs/src/documentation/content/xdocs/hdfs_permissions_guide.xml
View File

@ -1,192 +0,0 @@
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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>
HDFS Permissions Guide
</title>
</header>
<body>
<section> <title>Overview</title>
<p>
The Hadoop Distributed File System (HDFS) implements a permissions model for files and directories that shares much of the POSIX model. Each file and directory is associated with an <em>owner</em> and a <em>group</em>. The file or directory has separate permissions for the user that is the owner, for other users that are members of the group, and for all other users. For files, the <em>r</em> permission is required to read the file, and the <em>w</em> permission is required to write or append to the file. For directories, the <em>r</em> permission is required to list the contents of the directory, the <em>w</em> permission is required to create or delete files or directories, and the <em>x</em> permission is required to access a child of the directory. In contrast to the POSIX model, there are no <em>setuid</em> or <em>setgid</em> bits for files as there is no notion of executable files. For directories, there are no <em>setuid</em> or <em>setgid</em> bits directory as a simplification. The <em>Sticky bit</em> can be set on directories, preventing anyone except the superuser, directory owner or file owner from deleting or moving the files within the directory. Setting the sticky bit for a file has no effect. Collectively, the permissions of a file or directory are its <em>mode</em>. In general, Unix customs for representing and displaying modes will be used, including the use of octal numbers in this description. When a file or directory is created, its owner is the user identity of the client process, and its group is the group of the parent directory (the BSD rule).
</p>
<p>
Each client process that accesses HDFS has a two-part identity composed of the <em>user name</em>, and <em>groups list</em>. Whenever HDFS must do a permissions check for a file or directory <code>foo</code> accessed by a client process,
</p>
<ul>
<li>
If the user name matches the owner of <code>foo</code>, then the owner permissions are tested;
</li>
<li>
Else if the group of <code>foo</code> matches any of member of the groups list, then the group permissions are tested;
</li>
<li>
Otherwise the other permissions of <code>foo</code> are tested.
</li>
</ul>
<p>
If a permissions check fails, the client operation fails.
</p>
</section>
<section><title>User Identity</title>
<p>
In this release of Hadoop the identity of a client process is just whatever the host operating system says it is. For Unix-like systems,
</p>
<ul>
<li>
The user name is the equivalent of <code>`whoami`</code>;
</li>
<li>
The group list is the equivalent of <code>`bash -c groups`</code>.
</li>
</ul>
<p>
In the future there will be other ways of establishing user identity (think Kerberos, LDAP, and others). There is no expectation that this first method is secure in protecting one user from impersonating another. This user identity mechanism combined with the permissions model allows a cooperative community to share file system resources in an organized fashion.
</p>
<p>
In any case, the user identity mechanism is extrinsic to HDFS itself. There is no provision within HDFS for creating user identities, establishing groups, or processing user credentials.
</p>
</section>
<section> <title>Understanding the Implementation</title>
<p>
Each file or directory operation passes the full path name to the name node, and the permissions checks are applied along the path for each operation. The client framework will implicitly associate the user identity with the connection to the name node, reducing the need for changes to the existing client API. It has always been the case that when one operation on a file succeeds, the operation might fail when repeated because the file, or some directory on the path, no longer exists. For instance, when the client first begins reading a file, it makes a first request to the name node to discover the location of the first blocks of the file. A second request made to find additional blocks may fail. On the other hand, deleting a file does not revoke access by a client that already knows the blocks of the file. With the addition of permissions, a client's access to a file may be withdrawn between requests. Again, changing permissions does not revoke the access of a client that already knows the file's blocks.
</p>
<p>
The map-reduce framework delegates the user identity by passing strings without special concern for confidentiality. The owner and group of a file or directory are stored as strings; there is no conversion from user and group identity numbers as is conventional in Unix.
</p>
<p>
The permissions features of this release did not require any changes to the behavior of data nodes. Blocks on the data nodes do not have any of the <em>Hadoop</em> ownership or permissions attributes associated with them.
</p>
</section>
<section> <title>Changes to the File System API</title>
<p>
All methods that use a path parameter will throw <code>AccessControlException</code> if permission checking fails.
</p>
<p>New methods:</p>
<ul>
<li>
<code>public FSDataOutputStream create(Path f, FsPermission permission, boolean overwrite, int bufferSize, short replication, long blockSize, Progressable progress) throws IOException;</code>
</li>
<li>
<code>public boolean mkdirs(Path f, FsPermission permission) throws IOException;</code>
</li>
<li>
<code>public void setPermission(Path p, FsPermission permission) throws IOException;</code>
</li>
<li>
<code>public void setOwner(Path p, String username, String groupname) throws IOException;</code>
</li>
<li>
<code>public FileStatus getFileStatus(Path f) throws IOException;</code> will additionally return the user, group and mode associated with the path.
</li>
</ul>
<p>
The mode of a new file or directory is restricted my the <code>umask</code> set as a configuration parameter. When the existing <code>create(path, &hellip;)</code> method (<em>without</em> the permission parameter) is used, the mode of the new file is <code>666&thinsp;&amp;&thinsp;^umask</code>. When the new <code>create(path, </code><em>permission</em><code>, &hellip;)</code> method (<em>with</em> the permission parameter <em>P</em>) is used, the mode of the new file is <code>P&thinsp;&amp;&thinsp;^umask&thinsp;&amp;&thinsp;666</code>. When a new directory is created with the existing <code>mkdirs(path)</code> method (<em>without</em> the permission parameter), the mode of the new directory is <code>777&thinsp;&amp;&thinsp;^umask</code>. When the new <code>mkdirs(path, </code><em>permission</em> <code>)</code> method (<em>with</em> the permission parameter <em>P</em>) is used, the mode of new directory is <code>P&thinsp;&amp;&thinsp;^umask&thinsp;&amp;&thinsp;777</code>.
</p>
</section>
<section> <title>Changes to the Application Shell</title>
<p>New operations:</p>
<dl>
<dt><code>chmod [-R]</code> <em>mode file &hellip;</em></dt>
<dd>
Only the owner of a file or the super-user is permitted to change the mode of a file.
</dd>
<dt><code>chgrp [-R]</code> <em>group file &hellip;</em></dt>
<dd>
The user invoking <code>chgrp</code> must belong to the specified group and be the owner of the file, or be the super-user.
</dd>
<dt><code>chown [-R]</code> <em>[owner][:[group]] file &hellip;</em></dt>
<dd>
The owner of a file may only be altered by a super-user.
</dd>
<dt><code>ls </code> <em>file &hellip;</em></dt><dd></dd>
<dt><code>lsr </code> <em>file &hellip;</em></dt>
<dd>
The output is reformatted to display the owner, group and mode.
</dd>
</dl></section>
<section> <title>The Super-User</title>
<p>
The super-user is the user with the same identity as name node process itself. Loosely, if you started the name node, then you are the super-user. The super-user can do anything in that permissions checks never fail for the super-user. There is no persistent notion of who <em>was</em> the super-user; when the name node is started the process identity determines who is the super-user <em>for now</em>. The HDFS super-user does not have to be the super-user of the name node host, nor is it necessary that all clusters have the same super-user. Also, an experimenter running HDFS on a personal workstation, conveniently becomes that installation's super-user without any configuration.
</p>
<p>
In addition, the administrator my identify a distinguished group using a configuration parameter. If set, members of this group are also super-users.
</p>
</section>
<section> <title>The Web Server</title>
<p>
The identity of the web server is a configuration parameter. That is, the name node has no notion of the identity of the <em>real</em> user, but the web server behaves as if it has the identity (user and groups) of a user chosen by the administrator. Unless the chosen identity matches the super-user, parts of the name space may be invisible to the web server.</p>
</section>
<section> <title>On-line Upgrade</title>
<p>
If a cluster starts with a version 0.15 data set (<code>fsimage</code>), all files and directories will have owner <em>O</em>, group <em>G</em>, and mode <em>M</em>, where <em>O</em> and <em>G</em> are the user and group identity of the super-user, and <em>M</em> is a configuration parameter. </p>
</section>
<section> <title>Configuration Parameters</title>
<dl>
<dt><code>dfs.permissions = true </code></dt>
<dd>
If <code>yes</code> use the permissions system as described here. If <code>no</code>, permission <em>checking</em> is turned off, but all other behavior is unchanged. Switching from one parameter value to the other does not change the mode, owner or group of files or directories.
<p>
</p>
Regardless of whether permissions are on or off, <code>chmod</code>, <code>chgrp</code> and <code>chown</code> <em>always</em> check permissions. These functions are only useful in the permissions context, and so there is no backwards compatibility issue. Furthermore, this allows administrators to reliably set owners and permissions in advance of turning on regular permissions checking.
</dd>
<dt><code>dfs.web.ugi = webuser,webgroup</code></dt>
<dd>
The user name to be used by the web server. Setting this to the name of the super-user allows any web client to see everything. Changing this to an otherwise unused identity allows web clients to see only those things visible using "other" permissions. Additional groups may be added to the comma-separated list.
</dd>
<dt><code>dfs.permissions.supergroup = supergroup</code></dt>
<dd>
The name of the group of super-users.
</dd>
<dt><code>dfs.upgrade.permission = 0777</code></dt>
<dd>
The choice of initial mode during upgrade. The <em>x</em> permission is <em>never</em> set for files. For configuration files, the decimal value <em>511<sub>10</sub></em> may be used.
</dd>
<dt><code>dfs.umaskmode = 022</code></dt>
<dd>
The <code>umask</code> used when creating files and directories. May be specified either via three octal digits or symbolic values, with the same constraints as the dfs chmod command.
</dd>
</dl>
</section>
</body>
</document>

97
src/docs/src/documentation/content/xdocs/libhdfs.xml
View File

@ -1,97 +0,0 @@
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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>C API to HDFS: libhdfs</title>
<meta name="http-equiv">Content-Type</meta>
<meta name="content">text/html;</meta>
<meta name="charset">utf-8</meta>
</header>
<body>
<section>
<title>C API to HDFS: libhdfs</title>
<p>
libhdfs is a JNI based C api for Hadoop's DFS. It provides C apis to a subset of the HDFS APIs to manipulate DFS files and the filesystem. libhdfs is part of the hadoop distribution and comes pre-compiled in ${HADOOP_HOME}/libhdfs/libhdfs.so .
</p>
</section>
<section>
<title>The APIs</title>
<p>
The libhdfs APIs are a subset of: <a href="api/org/apache/hadoop/fs/FileSystem.html" >hadoop fs APIs</a>.
</p>
<p>
The header file for libhdfs describes each API in detail and is available in ${HADOOP_HOME}/src/c++/libhdfs/hdfs.h
</p>
</section>
<section>
<title>A sample program</title>
<source>
#include "hdfs.h"
int main(int argc, char **argv) {
hdfsFS fs = hdfsConnect("default", 0);
const char* writePath = "/tmp/testfile.txt";
hdfsFile writeFile = hdfsOpenFile(fs, writePath, O_WRONLY|O_CREAT, 0, 0, 0);
if(!writeFile) {
fprintf(stderr, "Failed to open %s for writing!\n", writePath);
exit(-1);
}
char* buffer = "Hello, World!";
tSize num_written_bytes = hdfsWrite(fs, writeFile, (void*)buffer, strlen(buffer)+1);
if (hdfsFlush(fs, writeFile)) {
fprintf(stderr, "Failed to 'flush' %s\n", writePath);
exit(-1);
}
hdfsCloseFile(fs, writeFile);
}
</source>
</section>
<section>
<title>How to link with the library</title>
<p>
See the Makefile for hdfs_test.c in the libhdfs source directory (${HADOOP_HOME}/src/c++/libhdfs/Makefile) or something like:
gcc above_sample.c -I${HADOOP_HOME}/src/c++/libhdfs -L${HADOOP_HOME}/libhdfs -lhdfs -o above_sample
</p>
</section>
<section>
<title>Common problems</title>
<p>
The most common problem is the CLASSPATH is not set properly when calling a program that uses libhdfs. Make sure you set it to all the hadoop jars needed to run Hadoop itself. Currently, there is no way to programmatically generate the classpath, but a good bet is to include all the jar files in ${HADOOP_HOME} and ${HADOOP_HOME}/lib as well as the right configuration directory containing hdfs-site.xml
</p>
</section>
<section>
<title>libhdfs is thread safe</title>
<p>Concurrency and Hadoop FS "handles" - the hadoop FS implementation includes a FS handle cache which caches based on the URI of the namenode along with the user connecting. So, all calls to hdfsConnect will return the same handle but calls to hdfsConnectAsUser with different users will return different handles. But, since HDFS client handles are completely thread safe, this has no bearing on concurrency.
</p>
<p>Concurrency and libhdfs/JNI - the libhdfs calls to JNI should always be creating thread local storage, so (in theory), libhdfs should be as thread safe as the underlying calls to the Hadoop FS.
</p>
</section>
</body>
</document>

670
src/docs/src/documentation/content/xdocs/streaming.xml
View File

@ -1,670 +0,0 @@
<?xml version="1.0"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You 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>Hadoop Streaming</title>
<meta name="http-equiv">Content-Type</meta>
<meta name="content">text/html;</meta>
<meta name="charset">utf-8</meta>
</header>
<body>
<section>
<title>Hadoop Streaming</title>
<p>
Hadoop streaming is a utility that comes with the Hadoop distribution. The utility allows you to create and run Map/Reduce jobs with any executable or script as the mapper and/or the reducer. For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper /bin/cat \
-reducer /bin/wc
</source>
</section>
<section>
<title>How Does Streaming Work </title>
<p>
In the above example, both the mapper and the reducer are executables that read the input from stdin (line by line) and emit the output to stdout. The utility will create a Map/Reduce job, submit the job to an appropriate cluster, and monitor the progress of the job until it completes.
</p><p>
When an executable is specified for mappers, each mapper task will launch the executable as a separate process when the mapper is initialized. As the mapper task runs, it converts its inputs into lines and feed the lines to the stdin of the process. In the meantime, the mapper collects the line oriented outputs from the stdout of the process and converts each line into a key/value pair, which is collected as the output of the mapper. By default, the
<em>prefix of a line up to the first tab character</em> is the <strong>key</strong> and the rest of the line (excluding the tab character) will be the <strong>value</strong>.
If there is no tab character in the line, then entire line is considered as key and the value is null. However, this can be customized, as discussed later.
</p>
<p>
When an executable is specified for reducers, each reducer task will launch the executable as a separate process then the reducer is initialized. As the reducer task runs, it converts its input key/values pairs into lines and feeds the lines to the stdin of the process. In the meantime, the reducer collects the line oriented outputs from the stdout of the process, converts each line into a key/value pair, which is collected as the output of the reducer. By default, the prefix of a line up to the first tab character is the key and the rest of the line (excluding the tab character) is the value. However, this can be customized, as discussed later.
</p><p>
This is the basis for the communication protocol between the Map/Reduce framework and the streaming mapper/reducer.
</p><p>
You can supply a Java class as the mapper and/or the reducer. The above example is equivalent to:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper org.apache.hadoop.mapred.lib.IdentityMapper \
-reducer /bin/wc
</source>
<p>User can specify <code>stream.non.zero.exit.is.failure</code> as
<code>true</code> or <code>false</code> to make a streaming task that exits
with a non-zero status to be <code>Failure</code>
or <code>Success</code> respectively. By default, streaming tasks exiting
with non-zero status are considered to be failed tasks.</p>
</section>
<section>
<title>Package Files With Job Submissions</title>
<p>
You can specify any executable as the mapper and/or the reducer. The executables do not need to pre-exist on the machines in the cluster; however, if they don't, you will need to use "-file" option to tell the framework to pack your executable files as a part of job submission. For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper myPythonScript.py \
-reducer /bin/wc \
-file myPythonScript.py
</source>
<p>
The above example specifies a user defined Python executable as the mapper. The option "-file myPythonScript.py" causes the python executable shipped to the cluster machines as a part of job submission.
</p>
<p>
In addition to executable files, you can also package other auxiliary files (such as dictionaries, configuration files, etc) that may be used by the mapper and/or the reducer. For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper myPythonScript.py \
-reducer /bin/wc \
-file myPythonScript.py \
-file myDictionary.txt
</source>
</section>
<section>
<title>Streaming Options and Usage </title>
<section>
<title>Mapper-Only Jobs </title>
<p>
Often, you may want to process input data using a map function only. To do this, simply set mapred.reduce.tasks to zero. The Map/Reduce framework will not create any reducer tasks. Rather, the outputs of the mapper tasks will be the final output of the job.
</p><p>
To be backward compatible, Hadoop Streaming also supports the "-reduce NONE" option, which is equivalent to "-D mapred.reduce.tasks=0".
</p>
</section>
<section>
<title>Specifying Other Plugins for Jobs </title>
<p>
Just as with a normal Map/Reduce job, you can specify other plugins for a streaming job:
</p>
<source>
-inputformat JavaClassName
-outputformat JavaClassName
-partitioner JavaClassName
-combiner streamingCommand or JavaClassName
</source>
<p>
The class you supply for the input format should return key/value pairs of Text class. If you do not specify an input format class, the TextInputFormat is used as the default. Since the TextInputFormat returns keys of LongWritable class, which are actually not part of the input data, the keys will be discarded; only the values will be piped to the streaming mapper.
</p><p>
The class you supply for the output format is expected to take key/value pairs of Text class. If you do not specify an output format class, the TextOutputFormat is used as the default.
</p>
</section>
<section>
<title>Large files and archives in Hadoop Streaming </title>
<p>
The -files and -archives options allow you to make files and archives available to the tasks. The argument is a URI to the file or archive that you have already uploaded to HDFS. These files and archives are cached across jobs. You can retrieve the host and fs_port values from the fs.default.name config variable.
</p>
<p>
Here are examples of the -files option:
</p>
<source>
-files hdfs://host:fs_port/user/testfile.txt#testlink
</source>
<p>
In the above example, the part of the url after # is used as the symlink name that is created in the current working directory of tasks. So the tasks will have a symlink called testlink in the cwd that points to a local copy of testfile.txt. Multiple entries can be specified as:
</p>
<source>
-files hdfs://host:fs_port/user/testfile1.txt#testlink1 -files hdfs://host:fs_port/user/testfile2.txt#testlink2
</source>
<p>
The -archives option allows you to copy jars locally to the cwd of tasks and automatically unjar the files. For example:
</p>
<source>
-archives hdfs://host:fs_port/user/testfile.jar#testlink3
</source>
<p>
In the example above, a symlink testlink3 is created in the current working directory of tasks. This symlink points to the directory that stores the unjarred contents of the uploaded jar file.
</p>
<p>
Here's another example of the -archives option. Here, the input.txt file has two lines specifying the names of the two files: testlink/cache.txt and testlink/cache2.txt. "testlink" is a symlink to the archived directory, which has the files "cache.txt" and "cache2.txt".
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input "/user/me/samples/cachefile/input.txt" \
-mapper "xargs cat" \
-reducer "cat" \
-output "/user/me/samples/cachefile/out" \
-archives 'hdfs://hadoop-nn1.example.com/user/me/samples/cachefile/cachedir.jar#testlink' \
-D mapred.map.tasks=1 \
-D mapred.reduce.tasks=1 \
-D mapred.job.name="Experiment"
$ ls test_jar/
cache.txt cache2.txt
$ jar cvf cachedir.jar -C test_jar/ .
added manifest
adding: cache.txt(in = 30) (out= 29)(deflated 3%)
adding: cache2.txt(in = 37) (out= 35)(deflated 5%)
$ hadoop dfs -put cachedir.jar samples/cachefile
$ hadoop dfs -cat /user/me/samples/cachefile/input.txt
testlink/cache.txt
testlink/cache2.txt
$ cat test_jar/cache.txt
This is just the cache string
$ cat test_jar/cache2.txt
This is just the second cache string
$ hadoop dfs -ls /user/me/samples/cachefile/out
Found 1 items
/user/me/samples/cachefile/out/part-00000 &lt;r 3&gt; 69
$ hadoop dfs -cat /user/me/samples/cachefile/out/part-00000
This is just the cache string
This is just the second cache string
</source>
</section>
<section>
<title>Specifying Additional Configuration Variables for Jobs </title>
<p>
You can specify additional configuration variables by using "-D &lt;n&gt;=&lt;v&gt;". For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper org.apache.hadoop.mapred.lib.IdentityMapper\
-reducer /bin/wc \
-D mapred.reduce.tasks=2
</source>
<p>
The -D mapred.reduce.tasks=2 in the above example specifies to use two reducers for the job.
</p>
<p>
For more details on the jobconf parameters see:
<a href="ext:mapred-default">mapred-default.html</a></p>
</section>
<section>
<title>Other Supported Options </title>
<p>
Other options you may specify for a streaming job are described here:
</p>
<table>
<tr><th>Parameter</th><th>Optional/Required </th><th>Description </th></tr>
<tr><td> -cmdenv name=value </td><td> Optional </td><td> Pass env var to streaming commands </td></tr>
<tr><td> -inputreader JavaClassName </td><td> Optional </td><td> For backwards-compatibility: specifies a record reader class (instead of an input format class) </td></tr>
<tr><td> -verbose </td><td> Optional </td><td> Verbose output </td></tr>
<tr><td> -lazyOutput </td><td> Optional </td><td> Create output lazily. For example, if the output format is based on FileOutputFormat, the output file is created only on the first call to output.collect (or Context.write)</td></tr>
</table>
<p>
Streaming support Hadoop generic command line options.
Supported parameters are :
The general command line syntax is :
<br/> bin/hadoop command [genericOptions] [commandOptions]
</p>
<table>
<tr><th>Parameter</th><th>Optional/Required </th><th>Description </th></tr>
<tr><td> -conf configuration_file </td><td> Optional </td><td> specify an application configuration file </td></tr>
<tr><td> -D property=value </td><td> Optional </td><td> use value for given property </td></tr>
<tr><td> -fs host:port or local </td><td> Optional </td><td> specify a namenode </td></tr>
<tr><td> -jt host:port or local </td><td> Optional </td><td> specify a job tracker </td></tr>
<tr><td> -files </td><td> Optional </td><td> specify comma separated files to be copied to the map reduce cluster </td></tr>
<tr><td> -archives </td><td> Optional </td><td> specify comma separated archives to be unarchived on the compute machines </td></tr>
<tr><td> </td><td> Optional </td><td> </td></tr>
<tr><td> -jt host:port or local </td><td> Optional </td><td> </td></tr>
</table>
<p>
To change the local temp directory use:
</p>
<source>
-D dfs.data.dir=/tmp
</source>
<p>
To specify additional local temp directories use:
</p>
<source>
-D mapred.local.dir=/tmp/local
-D mapred.system.dir=/tmp/system
-D mapred.temp.dir=/tmp/temp
</source>
<p>
For more details on jobconf parameters see:
<a href="ext:mapred-default">mapred-default.html</a></p>
<p>
To set an environment variable in a streaming command use:
</p>
<source>
-cmdenv EXAMPLE_DIR=/home/example/dictionaries/
</source>
</section>
</section>
<section>
<title>More usage examples </title>
<section>
<title>Customizing the Way to Split Lines into Key/Value Pairs </title>
<p>
As noted earlier, when the Map/Reduce framework reads a line from the stdout of the mapper, it splits the line into a key/value pair. By default, the prefix of the line up to the first tab character is the key and the rest of the line (excluding the tab character) is the value.
</p>
<p>
However, you can customize this default. You can specify a field separator other than the tab character (the default), and you can specify the nth (n >= 1) character rather than the first character in a line (the default) as the separator between the key and value. For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper org.apache.hadoop.mapred.lib.IdentityMapper \
-reducer org.apache.hadoop.mapred.lib.IdentityReducer \
-D stream.map.output.field.separator=. \
-D stream.num.map.output.key.fields=4
</source>
<p>
In the above example, "-D stream.map.output.field.separator=." specifies "." as the field separator for the map outputs, and the prefix up to the fourth "." in a line will be the key and the rest of the line (excluding the fourth ".") will be the value. If a line has less than four "."s, then the whole line will be the key and the value will be an empty Text object (like the one created by new Text("")).
</p><p>
Similarly, you can use "-D stream.reduce.output.field.separator=SEP" and "-D stream.num.reduce.output.fields=NUM" to specify the nth field separator in a line of the reduce outputs as the separator between the key and the value.
</p>
<p> Similarly, you can specify "stream.map.input.field.separator" and
"stream.reduce.input.field.separator" as the input separator for map/reduce
inputs. By default the separator is the tab character.</p>
</section>
<section>
<title>A Useful Partitioner Class (secondary sort, the -partitioner org.apache.hadoop.mapred.lib.KeyFieldBasedPartitioner option) </title>
<p>
Hadoop has a library class,
<a href="ext:api/org/apache/hadoop/mapred/lib/keyfieldbasedpartitioner">KeyFieldBasedPartitioner</a>,
that is useful for many applications. This class allows the Map/Reduce
framework to partition the map outputs based on certain key fields, not
the whole keys. For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper org.apache.hadoop.mapred.lib.IdentityMapper \
-reducer org.apache.hadoop.mapred.lib.IdentityReducer \
-partitioner org.apache.hadoop.mapred.lib.KeyFieldBasedPartitioner \
-D stream.map.output.field.separator=. \
-D stream.num.map.output.key.fields=4 \
-D map.output.key.field.separator=. \
-D mapred.text.key.partitioner.options=-k1,2\
-D mapred.reduce.tasks=12
</source>
<p>
Here, <em>-D stream.map.output.field.separator=.</em> and <em>-D stream.num.map.output.key.fields=4</em> are as explained in previous example. The two variables are used by streaming to identify the key/value pair of mapper.
</p><p>
The map output keys of the above Map/Reduce job normally have four fields
separated by ".". However, the Map/Reduce framework will partition the map
outputs by the first two fields of the keys using the
<em>-D mapred.text.key.partitioner.options=-k1,2</em> option.
Here, <em>-D map.output.key.field.separator=.</em> specifies the separator
for the partition. This guarantees that all the key/value pairs with the
same first two fields in the keys will be partitioned into the same reducer.
</p><p>
<em>This is effectively equivalent to specifying the first two fields as the primary key and the next two fields as the secondary. The primary key is used for partitioning, and the combination of the primary and secondary keys is used for sorting.</em> A simple illustration is shown here:
</p>
<p>
Output of map (the keys)</p><source>
11.12.1.2
11.14.2.3
11.11.4.1
11.12.1.1
11.14.2.2
</source>
<p>
Partition into 3 reducers (the first 2 fields are used as keys for partition)</p><source>
11.11.4.1
-----------
11.12.1.2
11.12.1.1
-----------
11.14.2.3
11.14.2.2
</source>
<p>
Sorting within each partition for the reducer(all 4 fields used for sorting)</p><source>
11.11.4.1
-----------
11.12.1.1
11.12.1.2
-----------
11.14.2.2
11.14.2.3
</source>
</section>
<section>
<title>A Useful Comparator Class</title>
<p>
Hadoop has a library class,
<a href="ext:api/org/apache/hadoop/mapred/lib/keyfieldbasedcomparator">KeyFieldBasedComparator</a>,
that is useful for many applications. This class provides a subset of features
provided by the Unix/GNU Sort. For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper org.apache.hadoop.mapred.lib.IdentityMapper \
-reducer org.apache.hadoop.mapred.lib.IdentityReducer \
-D mapred.output.key.comparator.class=org.apache.hadoop.mapred.lib.KeyFieldBasedComparator \
-D stream.map.output.field.separator=. \
-D stream.num.map.output.key.fields=4 \
-D map.output.key.field.separator=. \
-D mapred.text.key.comparator.options=-k2,2nr\
-D mapred.reduce.tasks=12
</source>
<p>
The map output keys of the above Map/Reduce job normally have four fields
separated by ".". However, the Map/Reduce framework will sort the
outputs by the second field of the keys using the
<em>-D mapred.text.key.comparator.options=-k2,2nr</em> option.
Here, <em>-n</em> specifies that the sorting is numerical sorting and
<em>-r</em> specifies that the result should be reversed. A simple illustration
is shown below:
</p>
<p>
Output of map (the keys)</p>
<source>
11.12.1.2
11.14.2.3
11.11.4.1
11.12.1.1
11.14.2.2
</source>
<p>
Sorting output for the reducer(where second field used for sorting)</p>
<source>
11.14.2.3
11.14.2.2
11.12.1.2
11.12.1.1
11.11.4.1
</source>
</section>
<section>
<title>Working with the Hadoop Aggregate Package (the -reduce aggregate option) </title>
<p>
Hadoop has a library package called
<a href="ext:api/org/apache/hadoop/mapred/lib/aggregate/package-summary">Aggregate</a>.
Aggregate provides a special reducer class and a special combiner class, and
a list of simple aggregators that perform aggregations such as "sum", "max",
"min" and so on over a sequence of values. Aggregate allows you to define a
mapper plugin class that is expected to generate "aggregatable items" for each
input key/value pair of the mappers. The combiner/reducer will aggregate those
aggregatable items by invoking the appropriate aggregators.
</p><p>
To use Aggregate, simply specify "-reducer aggregate":
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper myAggregatorForKeyCount.py \
-reducer aggregate \
-file myAggregatorForKeyCount.py \
-D mapred.reduce.tasks=12
</source>
<p>
The python program myAggregatorForKeyCount.py looks like:
</p>
<source>
#!/usr/bin/python
import sys;
def generateLongCountToken(id):
return "LongValueSum:" + id + "\t" + "1"
def main(argv):
line = sys.stdin.readline();
try:
while line:
line = line&#91;:-1];
fields = line.split("\t");
print generateLongCountToken(fields&#91;0]);
line = sys.stdin.readline();
except "end of file":
return None
if __name__ == "__main__":
main(sys.argv)
</source>
</section>
<section>
<title>Field Selection ( similar to unix 'cut' command) </title>
<p>
Hadoop has a library class, org.apache.hadoop.mapred.lib.FieldSelectionMapReduce, that effectively allows you to process text data like the unix "cut" utility. The map function defined in the class treats each input key/value pair as a list of fields. You can specify the field separator (the default is the tab character). You can select an arbitrary list of fields as the map output key, and an arbitrary list of fields as the map output value. Similarly, the reduce function defined in the class treats each input key/value pair as a list of fields. You can select an arbitrary list of fields as the reduce output key, and an arbitrary list of fields as the reduce output value. For example:
</p>
<source>
$HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input myInputDirs \
-output myOutputDir \
-mapper org.apache.hadoop.mapred.lib.FieldSelectionMapReduce\
-reducer org.apache.hadoop.mapred.lib.FieldSelectionMapReduce\
-partitioner org.apache.hadoop.mapred.lib.KeyFieldBasedPartitioner \
-D map.output.key.field.separa=. \
-D mapred.text.key.partitioner.options=-k1,2 \
-D mapred.data.field.separator=. \
-D map.output.key.value.fields.spec=6,5,1-3:0- \
-D reduce.output.key.value.fields.spec=0-2:5- \
-D mapred.reduce.tasks=12
</source>
<p>
The option "-D map.output.key.value.fields.spec=6,5,1-3:0-" specifies key/value selection for the map outputs. Key selection spec and value selection spec are separated by ":". In this case, the map output key will consist of fields 6, 5, 1, 2, and 3. The map output value will consist of all fields (0- means field 0 and all
the subsequent fields).
</p><p>
The option "-D reduce.output.key.value.fields.spec=0-2:5-" specifies
key/value selection for the reduce outputs. In this case, the reduce
output key will consist of fields 0, 1, 2 (corresponding to the original
fields 6, 5, 1). The reduce output value will consist of all fields starting
from field 5 (corresponding to all the original fields).
</p>
</section>
</section>
<section>
<title>Frequently Asked Questions </title>
<section>
<title>How do I use Hadoop Streaming to run an arbitrary set of (semi-)independent tasks? </title>
<p>
Often you do not need the full power of Map Reduce, but only need to run multiple instances of the same program - either on different parts of the data, or on the same data, but with different parameters. You can use Hadoop Streaming to do this.
</p>
</section>
<section>
<title>How do I process files, one per map? </title>
<p>
As an example, consider the problem of zipping (compressing) a set of files across the hadoop cluster. You can achieve this using either of these methods:
</p><ol>
<li> Hadoop Streaming and custom mapper script:<ul>
<li> Generate a file containing the full HDFS path of the input files. Each map task would get one file name as input.</li>
<li> Create a mapper script which, given a filename, will get the file to local disk, gzip the file and put it back in the desired output directory</li>
</ul></li>
<li>The existing Hadoop Framework:<ul>
<li>Add these commands to your main function:
<source>
FileOutputFormat.setCompressOutput(conf, true);
FileOutputFormat.setOutputCompressorClass(conf, org.apache.hadoop.io.compress.GzipCodec.class);
conf.setOutputFormat(NonSplitableTextInputFormat.class);
conf.setNumReduceTasks(0);
</source></li>
<li>Write your map function:
<source>
public void map(WritableComparable key, Writable value,
OutputCollector output,
Reporter reporter) throws IOException {
output.collect((Text)value, null);
}
</source></li>
<li>Note that the output filename will not be the same as the original filename</li>
</ul></li>
</ol>
</section>
<section>
<title>How many reducers should I use? </title>
<p>
See the Hadoop Wiki for details: <a href="mapred_tutorial.html#Reducer">Reducer</a>
</p>
</section>
<section>
<title>If I set up an alias in my shell script, will that work after -mapper, i.e. say I do: alias c1='cut -f1'. Will -mapper "c1" work? </title>
<p>
Using an alias will not work, but variable substitution is allowed as shown in this example:
</p>
<source>
$ hadoop dfs -cat samples/student_marks
alice 50
bruce 70
charlie 80
dan 75
$ c2='cut -f2'; $HADOOP_HOME/bin/hadoop jar $HADOOP_HOME/hadoop-streaming.jar \
-input /user/me/samples/student_marks
-mapper \"$c2\" -reducer 'cat'
-output /user/me/samples/student_out
-D mapred.job.name='Experiment'
$ hadoop dfs -ls samples/student_out
Found 1 items/user/me/samples/student_out/part-00000 &lt;r 3&gt; 16
$ hadoop dfs -cat samples/student_out/part-00000
50
70
75
80
</source>
</section>
<section>
<title>Can I use UNIX pipes? For example, will -mapper "cut -f1 | sed s/foo/bar/g" work?</title>
<p>
Currently this does not work and gives an "java.io.IOException: Broken pipe" error. This is probably a bug that needs to be investigated.
</p>
</section>
<section>
<title>When I run a streaming job by <strong>distributing large executables</strong> (for example, 3.6G) through the -file option, I get a "No space left on device" error. What do I do? </title>
<p>
The jar packaging happens in a directory pointed to by the configuration variable stream.tmpdir. The default value of stream.tmpdir is /tmp. Set the value to a directory with more space:
</p>
<source>
-D stream.tmpdir=/export/bigspace/...
</source>
</section>
<section>
<title>How do I specify multiple input directories? </title>
<p>
You can specify multiple input directories with multiple '-input' options:
</p><source>
hadoop jar hadoop-streaming.jar -input '/user/foo/dir1' -input '/user/foo/dir2'
</source>
</section>
<section>
<title>How do I generate output files with gzip format? </title>
<p>
Instead of plain text files, you can generate gzip files as your generated output. Pass '-D mapred.output.compress=true -D mapred.output.compression.codec=org.apache.hadoop.io.compress.GzipCodec' as option to your streaming job.
</p>
</section>
<section>
<title>How do I provide my own input/output format with streaming? </title>
<p>
At least as late as version 0.14, Hadoop does not support multiple jar files. So, when specifying your own custom classes you will have to pack them along with the streaming jar and use the custom jar instead of the default hadoop streaming jar.
</p>
</section>
<section>
<title>How do I parse XML documents using streaming? </title>
<p>
You can use the record reader StreamXmlRecordReader to process XML documents.
</p>
<source>
hadoop jar hadoop-streaming.jar -inputreader "StreamXmlRecord,begin=BEGIN_STRING,end=END_STRING" ..... (rest of the command)
</source>
<p>
Anything found between BEGIN_STRING and END_STRING would be treated as one record for map tasks.
</p>
</section>
<section>
<title>How do I update counters in streaming applications? </title>
<p>
A streaming process can use the stderr to emit counter information.
<code>reporter:counter:&lt;group&gt;,&lt;counter&gt;,&lt;amount&gt;</code>
should be sent to stderr to update the counter.
</p>
</section>
<section>
<title>How do I update status in streaming applications? </title>
<p>
A streaming process can use the stderr to emit status information.
To set a status, <code>reporter:status:&lt;message&gt;</code> should be sent
to stderr.
</p>
</section>
</section>
</body>
</document>