From 0f354b42ac38cc1cbd37085ddfd562b718142086 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Fri, 2 Dec 2016 13:59:26 +0100 Subject: [PATCH] Document the extension engine and exisitng extensions (#141) * Document the extension engine and exisitng extensions * Add the link to Extensions in ToC --- CHANGELOG.md | 10 ++--- README.md | 3 +- doc/extensions/extensions.md | 32 +++++++++++++++ doc/extensions/runawayProcessKiller.md | 52 +++++++++++++++++++++++++ doc/extensions/sharedDirectoryMapper.md | 39 +++++++++++++++++++ 5 files changed, 130 insertions(+), 6 deletions(-) create mode 100644 doc/extensions/extensions.md create mode 100644 doc/extensions/runawayProcessKiller.md create mode 100644 doc/extensions/sharedDirectoryMapper.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5df6b1e..5910153 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index edec1e4..e4be36e 100644 --- a/README.md +++ b/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 diff --git a/doc/extensions/extensions.md b/doc/extensions/extensions.md new file mode 100644 index 0000000..8b1efbf --- /dev/null +++ b/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*. diff --git a/doc/extensions/runawayProcessKiller.md b/doc/extensions/runawayProcessKiller.md new file mode 100644 index 0000000..e566ff8 --- /dev/null +++ b/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 + + + sampleService + Sample service + This is a stub service. + %BASE%\sleep.bat + + rotate + + + + + + %BASE%\pid.txt + + 5000 + + false + + + +``` + +### 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. \ No newline at end of file diff --git a/doc/extensions/sharedDirectoryMapper.md b/doc/extensions/sharedDirectoryMapper.md new file mode 100644 index 0000000..626fc89 --- /dev/null +++ b/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 + + + sampleService + Sample service + This is a stub service. + %BASE%\sleep.bat + + rotate + + + + + + + + + + +``` + +### Notes + +* If the extension fails to map the drive, the startup fails \ No newline at end of file