You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@knox.apache.org by lm...@apache.org on 2014/11/11 17:26:49 UTC
svn commit: r1638209 - in /knox: site/books/knox-0-5-0/knox-0-5-0.html
trunk/books/0.5.0/book.md
Author: lmccay
Date: Tue Nov 11 16:26:49 2014
New Revision: 1638209
URL: http://svn.apache.org/r1638209
Log:
added samples section
Modified:
knox/site/books/knox-0-5-0/knox-0-5-0.html
knox/trunk/books/0.5.0/book.md
Modified: knox/site/books/knox-0-5-0/knox-0-5-0.html
URL: http://svn.apache.org/viewvc/knox/site/books/knox-0-5-0/knox-0-5-0.html?rev=1638209&r1=1638208&r2=1638209&view=diff
==============================================================================
--- knox/site/books/knox-0-5-0/knox-0-5-0.html (original)
+++ knox/site/books/knox-0-5-0/knox-0-5-0.html Tue Nov 11 16:26:49 2014
@@ -22,6 +22,7 @@
<li><a href="#Apache+Knox+Directory+Layout">Apache Knox Directory Layout</a></li>
<li><a href="#Supported+Services">Supported Services</a></li>
</ul></li>
+ <li><a href="#Gateway+Samples">Gateway Samples</a></li>
<li><a href="#Gateway+Details">Gateway Details</a>
<ul>
<li><a href="#URL+Mapping">URL Mapping</a></li>
@@ -1488,7 +1489,30 @@ APACHE_HOME/bin/apachectl -k stop
<td>Logging message. Contains additional tracking information.</td>
</tr>
</tbody>
-</table><h4><a id="Audit+log+rotation"></a>Audit log rotation</h4><p>Audit logging is preconfigured with <code>org.apache.log4j.DailyRollingFileAppender</code>. <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a> contains information about other Appenders.</p><h4><a id="How+to+change+audit+level+or+disable+it"></a>How to change audit level or disable it</h4><p>Audit configuration is stored in the <code>conf/gateway-log4j.properties</code> file.</p><p>All audit messages are logged at <code>INFO</code> level and this behavior can’t be changed.</p><p>To change audit configuration <code>log4j.logger.audit*</code> and <code>log4j.appender.auditfile*</code> properties in <code>conf/gateway-log4j.properties</code> file should be modified.</p><p>Their meaning can be found in <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a>.</p><p>Disabling auditing can be done by decreasing log level for appender.</p><h2><a id="Client+Details"></a>Client Details</h2><p>Hadoo
p requires a client that can be used to interact remotely with the services provided by Hadoop cluster. This will also be true when using the Apache Knox Gateway to provide perimeter security and centralized access for these services. The two primary existing clients for Hadoop are the CLI (i.e. Command Line Interface, hadoop) and HUE (i.e. Hadoop User Environment). For several reasons however, neither of these clients can <em>currently</em> be used to access Hadoop services via the Apache Knox Gateway.</p><p>This led to thinking about a very simple client that could help people use and evaluate the gateway. The list below outlines the general requirements for such a client.</p>
+</table><h4><a id="Audit+log+rotation"></a>Audit log rotation</h4><p>Audit logging is preconfigured with <code>org.apache.log4j.DailyRollingFileAppender</code>. <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a> contains information about other Appenders.</p><h4><a id="How+to+change+audit+level+or+disable+it"></a>How to change audit level or disable it</h4><p>Audit configuration is stored in the <code>conf/gateway-log4j.properties</code> file.</p><p>All audit messages are logged at <code>INFO</code> level and this behavior can’t be changed.</p><p>To change audit configuration <code>log4j.logger.audit*</code> and <code>log4j.appender.auditfile*</code> properties in <code>conf/gateway-log4j.properties</code> file should be modified.</p><p>Their meaning can be found in <a href="http://logging.apache.org/log4j/1.2/">Apache log4j</a>.</p><p>Disabling auditing can be done by decreasing log level for appender.</p><h3><a id="Apache+Knox+Samples"></a>Apache Knox Samples</h
3><p>The purpose of the samples within the {GATEWAY_HOME}/samples directory is to demonstrate the capabilities of the Apache Knox Gateway to provide access to the numerous APIs that are available from the service components of a Hadoop cluster.</p><p>Depending on exactly how your Knox installation was done, there will be some number of steps required in order fully install and configure the samples for use.</p><p>This section will help describe the assumptions of the samples and the steps to get them to work in a couple of different deployment scenarios.</p><h4><a id="Assumptions+of+the+Samples"></a>Assumptions of the Samples</h4><p>The samples were initially written with the intent of working out of the box for the various Hadoop demo environments that are deployed as a single node cluster inside of a VM. The following assumptions were made from that context and should be understood in order to get the samples to work in other deployment scenarios:</p>
+<ul>
+ <li>That there is a valid java JDK on the PATH for executing the samples</li>
+ <li>The Knox Demo LDAP server is running on localhost and port 33389 which is the default port for the ApacheDS LDAP server.</li>
+ <li>That the LDAP directory in use has a set of demo users provisioned with the convention of username and username“-password” as the password. Most of the samples have some variation of this pattern with “guest” and “guest-password”.</li>
+ <li>That the Knox Gateway instance is running on the same machine which you will be running the samples from - therefore “localhost” and that the default port of “8443” is being used.</li>
+ <li>Finally, that there is a properly provisioned sandbox.xml topology in the {GATEWAY_HOME}/conf/topologies directory that is configured to point to the actual host and ports of running service components.</li>
+</ul><h4><a id="Steps+for+Demo+Single+Node+Clusters"></a>Steps for Demo Single Node Clusters</h4><p>There should be little to do if anything in a demo environment that has been provisioned with illustrating the use of Apache Knox.</p><p>However, the following items will be worth ensuring before you start:</p>
+<ol>
+ <li>The sandbox.xml topology is configured properly for the deployed services</li>
+ <li>That there is an LDAP server running with guest/guest-password user available in the directory</li>
+</ol><h4><a id="Steps+for+Ambari+Deployed+Knox+Gateway"></a>Steps for Ambari Deployed Knox Gateway</h4><p>Apache Knox instances that are under the management of Ambari are generally assumed not to be demo instances. These instances are in place to facilitate development, testing or production Hadoop clusters.</p><p>The Knox samples can however be made to work with Ambari managed Knox instances with a few steps:</p>
+<ol>
+ <li>You need to have ssh access to the environment in order for the localhost assumption within the samples to be valid.</li>
+ <li>The Knox Demo LDAP Server is started - you can start it from Ambari</li>
+ <li>The default.xml topology file can be copied to sandbox.xml in order to satisfy the topology name assumption in the samples.</li>
+ <li><p>Be sure to use an actual Java JRE to run the sample with something like:</p><p>/usr/jdk64/jdk1.7.0_67/bin/java -jar bin/shell.jar samples/ExampleWebHdfsLs.groovy</p></li>
+</ol><h4><a id="Steps+for+a+Manually+Installed+Knox+Gateway"></a>Steps for a Manually Installed Knox Gateway</h4><p>For manually installed Knox instances, there is really no way for the installer to know how to configure the topology file for you.</p><p>Essentially, these steps are identical to the Amabari deployed instance except that #3 should be replaced with the configuration of the ootb sandbox.xml to point the configuration at the proper hosts and ports.</p>
+<ol>
+ <li>You need to have ssh access to the environment in order for the localhost assumption within the samples to be valid.</li>
+ <li>The Knox Demo LDAP Server is started - you can start it from Ambari</li>
+ <li>Change the hosts and ports within the {GATEWAY_HOME}/conf/topologies/sandbox.xml to reflect your actual cluster service locations.</li>
+ <li><p>Be sure to use an actual Java JRE to run the sample with something like:</p><p>/usr/jdk64/jdk1.7.0_67/bin/java -jar bin/shell.jar samples/ExampleWebHdfsLs.groovy</p></li>
+</ol><h2><a id="Client+Details"></a>Client Details</h2><p>Hadoop requires a client that can be used to interact remotely with the services provided by Hadoop cluster. This will also be true when using the Apache Knox Gateway to provide perimeter security and centralized access for these services. The two primary existing clients for Hadoop are the CLI (i.e. Command Line Interface, hadoop) and HUE (i.e. Hadoop User Environment). For several reasons however, neither of these clients can <em>currently</em> be used to access Hadoop services via the Apache Knox Gateway.</p><p>This led to thinking about a very simple client that could help people use and evaluate the gateway. The list below outlines the general requirements for such a client.</p>
<ul>
<li>Promote the evaluation and adoption of the Apache Knox Gateway</li>
<li>Simple to deploy and use on data worker desktops to access to remote Hadoop clusters</li>
Modified: knox/trunk/books/0.5.0/book.md
URL: http://svn.apache.org/viewvc/knox/trunk/books/0.5.0/book.md?rev=1638209&r1=1638208&r2=1638209&view=diff
==============================================================================
--- knox/trunk/books/0.5.0/book.md (original)
+++ knox/trunk/books/0.5.0/book.md Tue Nov 11 16:26:49 2014
@@ -30,6 +30,7 @@
* #[Apache Knox Details]
* #[Apache Knox Directory Layout]
* #[Supported Services]
+* #[Gateway Samples]
* #[Gateway Details]
* #[URL Mapping]
* #[Configuration]
@@ -76,6 +77,7 @@ In general the goals of the gateway are
<<quick_start.md>>
<<book_getting-started.md>>
<<book_gateway-details.md>>
+<<book_knox-samples.md>>
<<book_client-details.md>>
<<book_service-details.md>>
<<book_limitations.md>>