From 3df8461ad922efa958ce5729b29b32c1f6719d22 Mon Sep 17 00:00:00 2001
From: Jonathan Hsieh <jon@cloudera.com>
Date: Wed, 26 Jan 2011 07:18:25 -0800
Subject: [PATCH] FLUME-352: Document running flume on windows

---
 src/docs/Windows/Windows                      |  192 +++++++++++++++++++++++++
 src/docs/Windows/flume-logo.png               |  Bin 0 -> 32773 bytes
 src/docs/Windows/flume-setup-2-license.png    |  Bin 0 -> 24148 bytes
 src/docs/Windows/flume-setup-3-components.png |  Bin 0 -> 22911 bytes
 src/docs/Windows/flume-setup-4-master.png     |  Bin 0 -> 17883 bytes
 src/docs/Windows/flume-setup-5-jre.png        |  Bin 0 -> 19380 bytes
 src/docs/Windows/flume-setup-6-installdir.png |  Bin 0 -> 21547 bytes
 src/docs/Windows/flume-setup-7-complete.png   |  Bin 0 -> 18194 bytes
 src/docs/Windows/flume-setup.png              |  Bin 0 -> 18506 bytes
 src/docs/Windows/flume-tray-icon.png          |  Bin 0 -> 3080 bytes
 src/docs/Windows/flume-tray-menu.png          |  Bin 0 -> 3389 bytes
 11 files changed, 192 insertions(+), 0 deletions(-)
 create mode 100644 src/docs/Windows/Windows
 create mode 100755 src/docs/Windows/flume-logo.png
 create mode 100755 src/docs/Windows/flume-setup-2-license.png
 create mode 100755 src/docs/Windows/flume-setup-3-components.png
 create mode 100755 src/docs/Windows/flume-setup-4-master.png
 create mode 100755 src/docs/Windows/flume-setup-5-jre.png
 create mode 100755 src/docs/Windows/flume-setup-6-installdir.png
 create mode 100755 src/docs/Windows/flume-setup-7-complete.png
 create mode 100755 src/docs/Windows/flume-setup.png
 create mode 100755 src/docs/Windows/flume-tray-icon.png
 create mode 100755 src/docs/Windows/flume-tray-menu.png

diff --git a/src/docs/Windows/Windows b/src/docs/Windows/Windows
new file mode 100644
index 0000000..b3e66f7
--- /dev/null
+++ b/src/docs/Windows/Windows
@@ -0,0 +1,192 @@
+
+////////////////////
+Licensed to Cloudera, Inc. under one
+or more contributor license agreements.  See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership.  Cloudera, Inc. 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.
+////////////////////
+
+== Flume on Microsoft Windows-based Machines
+
+
+image:flume-logo.png[]
+
+Flume v0.9.3 is the first version of Flume to support Windows-based
+Flume nodes.  It has been tested on Window 2k3 and Windows XP machines
+and can be used to collect logs generated from Windows applications
+such as MS IIS.
+
+Requirements:
+
+* Sun/Oracle 32-bit Windows JRE v1.6+
+
+NOTE: We suggest using the 32-bit jvm even on 64 bit machines because
+of lower memory footprint.
+
+=== Installation
+
+Flume for Windows is installed using a executable installer generated
+by NSIS.  It provides a simple wizard which presents basic options for
+a node's configuration settings.  It will install the software and
+optionally start a Flume node as a Windows service (daemon).
+
+NOTE: If reinstalling, make sure that flumenode.exe is closed.
+(service shutdown).
+
+When you execute the installation package you will initially see this
+installation dialog.
+
+image:flume-setup.png[]
+
+Click "Next >" to see the license,
+
+image:flume-setup-2-license.png[]
+
+and then "I Agree" to proceed. 
+
+image:flume-setup-3-components.png[]
+
+The next screen will give you the option of installing a the Flume
+Node core, or installing the core as a Windows service (daemon).  You
+can select the components you would like to install.
+
+image:flume-setup-4-master.png[]
+
+Next the installer will ask you some basic Flume Node configuration
+setting values.  This basically is asking for where the Node's master
+host and master port is.  By default it assumes localhost and the
+default node-master communications port.
+
+image:flume-setup-5-jre.png[]
+
+Next the installer attempts to auto-detect the localtion of an
+installed Java Runtime Environment (JRE).  
+
+WARNING: Currently the installer expects a 32-bit jvm -- pointing it
+to a 64-bit JVM is currently not supported.
+
+image:flume-setup-6-installdir.png[]
+
+Finally the installer asks for a directory to install the Flume
+components.  You can finally click on "Install" and the software will
+be copied and installed at the target location.
+
+image:flume-setup-7-complete.png[]
+
+After copying completes, you should see the final completion and
+confirmation screen.
+
+You can confirming that the Flume Node is up by
+
+* pointing a local browser to http://localhost:35862
+* viewing the services list in the Task Manager or Service Manager.
+* looking for a small Apache tray icon
+
+image:flume-tray-icon.png[]
+
+=== Administering Windows Flume Nodes
+
+Installation by default will set up the Flume Node to automatically
+start when the Windows machine is booted.  You can manually start and
+stop the Flume Node service several ways.
+
+* Via the tray icon applet
+* Via the +sc+ (service controller) windows command line program 
+* Via the service manager
+
+The tray icon is the most accessable way to start/stop or restart the
+FlumeNode.  You can access commands by right clicking on the tray
+icon:
+
+image:flume-tray-menu.png[]
+
+If you click "Configure..." you can tweak the settings such as JVM
+parameters and restart-on-reboot mode that the Flume Node uses.
+
+NOTE: Flume relies on Apache Common Daemon's +prunmgr.exe+ and
++prunsvr.exe+ programs.  By convention, these have been renamed to
++flumenode.exe+ and +flumenodew.exe+.  The first runs the Flume Node
+as a Windows Service, and the second provides the tray icon
+configuration interface.
+
+You can also use the service manager to start/stop Flume using the
+following Windows command line (as Administrator):
+
+----
+C:\> sc FlumeNode start
+C:\> sc FlumeNode stop
+----
+
+Run +sc+ for more details and options.
+
+Unfortuntely, the +install+, +delete+, and +create+ methods do not
+always work.  To manual install and uninstall the FlumeNode service,
+you can run the following scripts from the command prompt, as administrator:
+
+----
+%FLUME_HOME%> flumenode-service.bat install
+
+$FLUME_HOME%> flumenode-service.bat remove
+----
+
+WARNING: Uninstalling Flume Node may not complete cleanly.  You may
+need to kill +flumenode.exe+ and +flumenodew.exe+, and may need to
+search for java processes to kill as well.
+
+=== Default Directories.
+
+By default FlumeNode will be installed to +C:\Program
+Files\Cloudera\Flume 0.9.3\+.  We will denote this as +%FLUME_HOME%+.
+
+[width="50%",options="header"]
+|==========================================================================
+|Directory          |Purpose
+|%FLUME_HOME%/logs  |Dir where Flume Node logs are written to.
+|%FLUME_HOME%/conf  |Dir where flume-site.xml and flume-conf.xml reside
+|==========================================================================
+
+The +FLUME_CONF_DIR+ environment variable is respected -- you can keep
+xml configs in a separate directory pointed to by this variable for
+customized configurations.
+
+=== Building Flume for windows.
+
+To build flume, you will need:
+
+* Sun/Oracle JDK v1.6.x+
+* cygwin (http://www.cygwin.com/)
+* ant (http://ant.apache.org/bindownload.cgi, .zip version)
+* NSIS (we are using v2.46, http://nsis.sourceforge.net/Main_Page)
+
+With cygwin the normal build process can be used. (Let's assume you
+are in the flume project dir.)
+
+----
+~/flume$ ant 
+-----
+
+To generaate the Flume installer executable, a special ant filter
+needs to be run to inject proper build specific versions information.
+
+----
+~/flume$ ant winstall-filter
+----
+
+Finally, you can build the windows installer manually.  First start
+NSIS, and then click on "Compile NSI script".  This will open a new
+dialog.  In this dialog's menu select "File | Load script...".  Select
+flume/flume.nsi, and then click "Open".  This will compile the script
+and generate the intsaller, flume-installer.exe.  This file should
+live in main flume project directory.
+
diff --git a/src/docs/Windows/flume-logo.png b/src/docs/Windows/flume-logo.png
new file mode 100755
index 0000000000000000000000000000000000000000..bd119fa07886edf5781ae136b8c7473baedcf73e
GIT binary patch
diff --git a/src/docs/Windows/flume-setup-2-license.png b/src/docs/Windows/flume-setup-2-license.png
new file mode 100755
index 0000000000000000000000000000000000000000..b6ad9143b8f41a0c4a21dba87e859f47ca5abe36
GIT binary patch
diff --git a/src/docs/Windows/flume-setup-3-components.png b/src/docs/Windows/flume-setup-3-components.png
new file mode 100755
index 0000000000000000000000000000000000000000..1010f754de68fbcc73169212a18a4431e40b95ca
GIT binary patch
diff --git a/src/docs/Windows/flume-setup-4-master.png b/src/docs/Windows/flume-setup-4-master.png
new file mode 100755
index 0000000000000000000000000000000000000000..5a85cbb6759dd52cef40f0246849a2e8a1246d3d
GIT binary patch
diff --git a/src/docs/Windows/flume-setup-5-jre.png b/src/docs/Windows/flume-setup-5-jre.png
new file mode 100755
index 0000000000000000000000000000000000000000..f7ea379c21a49951ffa3f24b49d064d4388b72b7
GIT binary patch
diff --git a/src/docs/Windows/flume-setup-6-installdir.png b/src/docs/Windows/flume-setup-6-installdir.png
new file mode 100755
index 0000000000000000000000000000000000000000..289e4f81f9059e78f6d45b390b73a43eccf74783
GIT binary patch
diff --git a/src/docs/Windows/flume-setup-7-complete.png b/src/docs/Windows/flume-setup-7-complete.png
new file mode 100755
index 0000000000000000000000000000000000000000..9ad3128545e44fcc6a8e9c87921c885d0f361725
GIT binary patch
diff --git a/src/docs/Windows/flume-setup.png b/src/docs/Windows/flume-setup.png
new file mode 100755
index 0000000000000000000000000000000000000000..4b75eb85c40a54d09c99e575bc6cc4c4e96ab1d1
GIT binary patch
diff --git a/src/docs/Windows/flume-tray-icon.png b/src/docs/Windows/flume-tray-icon.png
new file mode 100755
index 0000000000000000000000000000000000000000..46b023bc7bbf2516320e2247bc654b8e22198622
GIT binary patch
diff --git a/src/docs/Windows/flume-tray-menu.png b/src/docs/Windows/flume-tray-menu.png
new file mode 100755
index 0000000000000000000000000000000000000000..8dc5f757c34096a8704cd8808de413998ed3891a
GIT binary patch
-- 
1.7.0.4

