Document the extension engine and exisitng extensions (#141)

* Document the extension engine and exisitng extensions

* Add the link to Extensions in ToC

CHANGELOG.md

@@ -8,13 +8,13 @@ Below you can find release notes for the trunk version of WinSW.
 Release date: Coming Soon
 
 Improvements:
-* Introduced a concept of WinSW extensions, which allows extending the wrapper's behavior
+* Introduced the [WinSW extension engine](doc/extensions/extensions.md), which allows extending the wrapper's behavior.
 ([PR #42](https://github.com/kohsuke/winsw/pull/42)).
- * The extension binary backward comparability is not guaranteed
-  * The engine does not support extensions in external DLLs (but you can repackage the executable if you want to extend WinSW)
-* `SharedDirectoriesMapper` extension for mapping shared directories when the Windows service starts 
+* [SharedDirectoriesMapper extension](doc/extensions/sharedDirectoryMapper.md)
 ([PR #42](https://github.com/kohsuke/winsw/pull/42)).
-* Migrate event logging to log4j
+* [RunawayProcessKiller extension](doc/extensions/runawayProcessKiller.md)
+([PR #133](https://github.com/kohsuke/winsw/pull/133)).
+* Migrate event logging to `log4j`
 ([PR #73](https://github.com/kohsuke/winsw/pull/73)).
 
 ##### 1.19.1

README.md

@@ -37,6 +37,7 @@ Your renamed `winsw.exe` binary also accepts the following commands:
  * [Main XML Configuration file](doc/xmlConfigFile.md)
  * [EXE Configuration File](doc/exeConfigFile.md)
  * [Logging and Error Reporting](doc/loggingAndErrorReporting.md)
+ * [Extensions](doc/extensions/extensions.md)
 * Use-cases:
  * [Self-restarting services](doc/selfRestartingService.md)
  * [Deferred File Operations](doc/deferredFileOperations.md)
@@ -53,7 +54,7 @@ API stability is not guaranteed till the first release, the project structure is
 Major changes since 1.x:
 * Rework of the project structure
 * Better logging
-* Internal plugin engine, which allows extending the WinSW behavior
+* [Internal extension engine](doc/extensions/extensions.md), which allows extending the WinSW behavior
 
 #### WinSW 1.x
 

doc/extensions/extensions.md

@@ -0,0 +1,32 @@
+WinSW extensions
+===
+
+Starting from WinSW `2.0`, the wrapper provides an internal extension engine and several extensions.
+These extensions allow to alter the behavior of the Windows service in order to setup the required service environment.
+
+### Available extensions
+
+* [Shared Directory Mapper](sharedDirectoriesMapper.md) - Allows mapping shared drives before starting the executable
+* [Runaway Process Killer](runawayProcessKiller.md) - Termination of processes started by the previous runs of WinSW
+
+### Developer guide
+
+In WinSW `2.x` the extension does not support inclusion of external extension DLLs.
+
+#### Adding external extensions
+
+The only way to create an external extension is to create a new extension DLL and 
+  then to merge this DLL into the executable using tools like `ILMerge`.
+See the example in `src/Core/ServiceWrapper/winsw.csproj`.
+
+Generic extension creation guideline:
+* Extension DLL should reference the `WinSWCore` library.
+* The extension should extend the `AbstractWinSWExtension` class.
+* The extension then can override event handlers offered by the upper class.
+* The extension should implement the configuration parsing from the `XmlNode`.
+* The extension should support disabling from the configuration file.
+
+WinSW engine will automatically locate your extension using the class name in the [XML Configuration File](../xmlConfigFile.md).
+See configuration samples provided for the extensions in the core.
+
+Please note that in the current versions of WinSW `2.x` the binary compatibility of extension APIs *is not guaranteed*.

doc/extensions/runawayProcessKiller.md

@@ -0,0 +1,52 @@
+Runaway Process Killer Extension
+===
+
+In particular cases Windows service wrapper may leak the process after the service completion.
+It happens when WinSW gets terminated without executing the shutdown logic.
+Examples: force kill of the service process, .NET Runtime crash, missing permissions to kill processes or a bug in the logic.
+
+Such runaway processes may conflict with the service process once it restarts.
+This extension allows preventing it by running the runaway process termination on startup before the executable gets started.
+
+Since: [WinSW 2.0](../../CHANGELOG.md).
+
+### Usage
+
+The extension can be configured via the [XML Configuration File](../xmlConfigFile.md). Configuration sample:
+
+```xml
+<?xml version="1.0" encoding="utf-8" ?>
+<service>
+  <id>sampleService</id>
+  <name>Sample service</name>
+  <description>This is a stub service.</description>
+  <executable>%BASE%\sleep.bat</executable>
+  <arguments></arguments>
+  <logmode>rotate</logmode>
+
+  <extensions>
+	<!-- This is a sample configuration for the RunawayProcessKiller extension. -->
+  <extension enabled="true" 
+             className="winsw.Plugins.RunawayProcessKiller.RunawayProcessKillerExtension"
+             id="killOnStartup">
+      <!-- Absolute path to the PID file, which stores ID of the previously launched process. -->
+      <pidfile>%BASE%\pid.txt</pidfile>
+      <!-- Defines the process termination timeout in milliseconds. 
+           This timeout will be applied multiple times for each child process.
+           After the timeout WinSW will try to force kill the process.
+      -->
+      <stopTimeout>5000</stopTimeout>
+      <!-- If true, the parent process will be terminated first if the runaway process gets terminated. -->
+      <stopParentFirst>false</stopParentFirst>
+    </extension>
+  </extensions>
+</service>
+```
+
+### Notes
+
+* The current implementation of the the extension checks only the root process (started executable)
+* If the runaway process is detected the entire, the entire process tree gets terminated
+* WinSW gives the runaway process a chance to the gracefully terminate. 
+If it does not do it within the timeout, the process will be force-killed.
+* If the force kill fails, the WinSW startup continues with a warning.

doc/extensions/sharedDirectoryMapper.md

@@ -0,0 +1,39 @@
+Shared Directory Mapper extension
+====
+
+By default Windows does not establish shared drive mapping for services even if it is configured in the Windows service profile.
+And sometimes it is impossible to workaround it due to the domain policies.
+
+This extension allows mapping external shared directories before starting up the executable.
+
+Since: [WinSW 2.0](../../CHANGELOG.md).
+
+### Usage
+
+The extension can be configured via the [XML Configuration File](../xmlConfigFile.md). 
+Configuration sample:
+
+```xml
+<?xml version="1.0" encoding="utf-8" ?>
+<service>
+  <id>sampleService</id>
+  <name>Sample service</name>
+  <description>This is a stub service.</description>
+  <executable>%BASE%\sleep.bat</executable>
+  <arguments></arguments>
+  <logmode>rotate</logmode>
+
+  <extensions>
+    <extension enabled="true" className="winsw.Plugins.SharedDirectoryMapper.SharedDirectoryMapper" id="mapNetworDirs">
+      <mapping>
+        <map enabled="false" label="N:" uncpath="\\UNC"/>
+        <map enabled="false" label="M:" uncpath="\\UNC2"/>
+      </mapping>
+    </extension>
+  </extensions>
+</service>
+```
+
+### Notes
+
+* If the extension fails to map the drive, the startup fails