git commit: FLUME-1845. Document plugin.d directory structure

[hs...@apache.org]

Updated Branches:
  refs/heads/trunk 40043fe2f -> dca895d80


FLUME-1845. Document plugin.d directory structure

(Mike Percy via Hari Shreedharan)


Project: http://git-wip-us.apache.org/repos/asf/flume/repo
Commit: http://git-wip-us.apache.org/repos/asf/flume/commit/dca895d8
Tree: http://git-wip-us.apache.org/repos/asf/flume/tree/dca895d8
Diff: http://git-wip-us.apache.org/repos/asf/flume/diff/dca895d8

Branch: refs/heads/trunk
Commit: dca895d80e68513ac2b6840d116824b4d6d0e182
Parents: 40043fe
Author: Hari Shreedharan <ha...@gmail.com>
Authored: Fri Jan 25 19:41:03 2013 -0800
Committer: Hari Shreedharan <ha...@gmail.com>
Committed: Fri Jan 25 19:41:03 2013 -0800

----------------------------------------------------------------------
 flume-ng-doc/sphinx/FlumeUserGuide.rst |   45 +++++++++++++++++++++++++++
 1 files changed, 45 insertions(+), 0 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/flume/blob/dca895d8/flume-ng-doc/sphinx/FlumeUserGuide.rst
----------------------------------------------------------------------
diff --git a/flume-ng-doc/sphinx/FlumeUserGuide.rst b/flume-ng-doc/sphinx/FlumeUserGuide.rst
index 898de23..8eb3734 100644
--- a/flume-ng-doc/sphinx/FlumeUserGuide.rst
+++ b/flume-ng-doc/sphinx/FlumeUserGuide.rst
@@ -215,6 +215,51 @@ The original Flume terminal will output the event in a log message.
 
 Congratulations - you've successfully configured and deployed a Flume agent! Subsequent sections cover agent configuration in much more detail.
 
+Installing third-party plugins
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Flume has a fully plugin-based architecture. While Flume ships with many
+out-of-the-box sources, channels, sinks, serializers, and the like, many
+implementations exist which ship separately from Flume.
+
+While it has always been possible to include custom Flume components by
+adding their jars to the FLUME_CLASSPATH variable in the flume-env.sh file,
+Flume now supports a special directory called ``plugins.d`` which automatically
+picks up plugins that are packaged in a specific format. This allows for easier
+management of plugin packaging issues as well as simpler debugging and
+troubleshooting of several classes of issues, especially library dependency
+conflicts.
+
+The plugins.d directory
+'''''''''''''''''''''''
+
+The ``plugins.d`` directory is located at ``$FLUME_HOME/plugins.d``. At startup
+time, the ``flume-ng`` start script looks in the ``plugins.d`` directory for
+plugins that conform to the below format and includes them in proper paths when
+starting up ``java``.
+
+Directory layout for plugins
+''''''''''''''''''''''''''''
+
+Each plugin (subdirectory) within ``plugins.d`` can have up to three
+sub-directories:
+
+#. lib - the plugin's jar(s)
+#. libext - the plugin's dependency jar(s)
+#. native - any required native libraries, such as ``.so`` files
+
+Example of two plugins within the plugins.d directory:
+
+.. code-block:: none
+
+  plugins.d/
+  plugins.d/custom-source-1/
+  plugins.d/custom-source-1/lib/my-source.jar
+  plugins.d/custom-source-1/libext/spring-core-2.5.6.jar
+  plugins.d/custom-source-2/
+  plugins.d/custom-source-2/lib/custom.jar
+  plugins.d/custom-source-2/native/gettext.so
+
 Data ingestion
 --------------