From 26360ea6963167b72a5e3435fa6bdb82407da1c8 Mon Sep 17 00:00:00 2001 From: NextTurn <45985406+NextTurn@users.noreply.github.com> Date: Wed, 28 Nov 2018 00:00:00 +0800 Subject: [PATCH] Update documentation headers --- CHANGELOG.md | 2 +- README.md | 41 ++++++++++++------------- doc/deferredFileOperations.md | 1 + doc/exeConfigFile.md | 8 ++--- doc/extensions/extensions.md | 8 ++--- doc/extensions/runawayProcessKiller.md | 10 +++--- doc/extensions/sharedDirectoryMapper.md | 8 ++--- doc/installation.md | 20 ++++++------ doc/loggingAndErrorReporting.md | 20 ++++++------ doc/selfRestartingService.md | 2 +- doc/xmlConfigFile.md | 7 +++-- 11 files changed, 64 insertions(+), 63 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b2411566..ba8aa01a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,3 @@ -# Release Notes +# Release notes This content has been moved to the [Releases](https://github.com/winsw/winsw/releases). diff --git a/README.md b/README.md index adb953f3..3840a677 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# winsw: Windows service wrapper in less restrictive license +# winsw: Windows Service Wrapper in less restrictive license [![Github All Releases](https://img.shields.io/github/downloads/winsw/winsw/total?style=flat-square)](https://github.com/winsw/winsw/releases) [![NuGet](https://img.shields.io/nuget/v/WinSW?style=flat-square)](https://www.nuget.org/packages/WinSW/) @@ -9,11 +9,11 @@ WinSW is an executable binary, which can be used to wrap and manage a custom process as a Windows service. Once you download the installation package, you can rename *WinSW.exe* to any name, e.g. *MyService.exe*. -### Why? +## Why? See the [project manifest](MANIFEST.md). -### Download +## Download Starting from WinSW v2, the releases are being hosted on [GitHub](https://github.com/winsw/winsw/releases) and [NuGet](https://www.nuget.org/packages/WinSW/). @@ -24,14 +24,14 @@ The executables in all sources are [strong-named assemblies](https://msdn.micros Do not rely on such strong names for security (as well as on other strong names as it recommended by Microsoft). They provide a unique identity only. -### Usage +## Usage -WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE Config file](doc/exeConfigFile.md). +WinSW is being managed by configuration files: [Main XML configuration file](doc/xmlConfigFile.md) and [EXE configuration file](doc/exeConfigFile.md). Your renamed *WinSW.exe* binary also accepts the following commands: * `install` to install the service to Windows Service Controller. - This command requires some preliminary steps described in the [Installation Guide](doc/installation.md). + This command requires some preliminary steps described in the [Installation guide](doc/installation.md). * `uninstall` to uninstall the service. The opposite operation of above. * `start` to start the service. The service must have already been installed. * `stop` to stop the service. @@ -42,45 +42,44 @@ Your renamed *WinSW.exe* binary also accepts the following commands: * `Started` to indicate the service is currently running * `Stopped` to indicate that the service is installed but not currently running. -### Supported .NET versions +## Supported .NET versions -#### WinSW v2 +### WinSW v2 WinSW v2 offers two executables, which declare .NET Frameworks 2.0 and 4.0 as targets. More executables can be added on-demand. Please create an issue if you need such executables. -#### WinSW v1 +### WinSW v1 WinSW v1 Executable is being built with a .NET Framework 2.0 target, and by defaut it will work only for .NET Framework versions below 3.5. On the other hand, the code is known to be compatible with .NET Framework 4.0 and above. It is possible to declare the support of this framework via the *.exe.config* file. -See the [Installation Guide](doc/installation.md) for more details. +See the [Installation guide](doc/installation.md) for more details. -### Documentation +## Documentation User documentation: -* [Installation Guide](doc/installation.md) - Describes the installation process for different systems and .NET versions -* [Release notes](CHANGELOG.md) +* [Installation guide](doc/installation.md) - Describes the installation process for different systems and .NET versions * Configuration: - * [Main XML Configuration file](doc/xmlConfigFile.md) - * [EXE Configuration File](doc/exeConfigFile.md) - * [Logging and Error Reporting](doc/loggingAndErrorReporting.md) + * [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) + * [Deferred file operations](doc/deferredFileOperations.md) * Configuration Management: * [Puppet Forge Module](doc/puppetWinSW.md) Developer documentation: -* [Developer Guide](DEVELOPER.md) +* [Developer guide](DEVELOPER.md) -### Release lines +## Release lines -#### WinSW v2 +### WinSW v2 This is a new baseline of WinSW with several major changes: * Major documentation rework and update @@ -95,7 +94,7 @@ See the full changelog in the [release notes](CHANGELOG.md). The version v2 is **fully compatible** with the v1 configuration file format, hence the upgrade procedure just requires replacement of the executable file. -#### WinSW v1 +### WinSW v1 This is an old baseline of WinSW. Currently it is in the maintenance-only state. diff --git a/doc/deferredFileOperations.md b/doc/deferredFileOperations.md index 2623d635..d3d0999b 100644 --- a/doc/deferredFileOperations.md +++ b/doc/deferredFileOperations.md @@ -18,6 +18,7 @@ example: ``` c:\soft\sshd.exe.new>c:\bin\ssh.exe ``` + Note that it is apparently possible to [rename executables even when it's running](http://superuser.com/questions/488127/why-can-i-rename-a-running-executable-but-not-delete-it), which makes sense if you think about file handles. Kohsuke has failed to find any authoritative source of information about this, but experimentally this even works on Windows XP and presumably on all the later Windows versions. This behavior can be used to update *WinSW.exe* itself. diff --git a/doc/exeConfigFile.md b/doc/exeConfigFile.md index e97ece84..d1ee032d 100644 --- a/doc/exeConfigFile.md +++ b/doc/exeConfigFile.md @@ -1,9 +1,9 @@ -# WinSW EXE Configuration File +# EXE configuration file -In addition to the [XML Configuration File](xmlConfigFile.md), WinSW uses a standard .NET *WinSW.exe.config* file, which allows setting up some custom settings. +In addition to the [XML configuration file](xmlConfigFile.md), WinSW uses a standard .NET *WinSW.exe.config* file, which allows setting up some custom settings. Use-cases: -* Declaring compatibility with newer .NET versions (see the [Installation Guide](installation.md)) -* Managing custom behavior for the offline mode (see the [Installation Guide](installation.md)) +* Declaring compatibility with newer .NET versions (see the [Installation guide](installation.md)) +* Managing custom behavior for the offline mode (see the [Installation guide](installation.md)) * Managing Logging levels of log4j * etc. diff --git a/doc/extensions/extensions.md b/doc/extensions/extensions.md index a2c552b4..d1ad9f02 100644 --- a/doc/extensions/extensions.md +++ b/doc/extensions/extensions.md @@ -3,16 +3,16 @@ 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 +## Available extensions * [Shared Directory Mapper](sharedDirectoryMapper.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 +## Developer guide In WinSW v2 the extension does not support inclusion of external extension DLLs. -#### Adding external extensions +### 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`. @@ -25,7 +25,7 @@ Generic extension creation guideline: * 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). +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. For extensions from external DLLs, the `className` field should also specify the assembly name. It can be done via fully qualified class name or just by the `${CLASS_NAME}, ${ASSEMBLY_NAME}` declaration. diff --git a/doc/extensions/runawayProcessKiller.md b/doc/extensions/runawayProcessKiller.md index 7cdf9052..f5889ff2 100644 --- a/doc/extensions/runawayProcessKiller.md +++ b/doc/extensions/runawayProcessKiller.md @@ -1,4 +1,4 @@ -# Runaway Process Killer Extension +# 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. @@ -7,11 +7,11 @@ Examples: force kill of the service process, .NET Runtime crash, missing permiss 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). +Since: WinSW 2.0. -### Usage +## Usage -The extension can be configured via the [XML Configuration File](../xmlConfigFile.md). Configuration sample: +The extension can be configured via the [XML configuration file](../xmlConfigFile.md). Configuration sample: ```xml @@ -42,7 +42,7 @@ The extension can be configured via the [XML Configuration File](../xmlConfigFil ``` -### Notes +## 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 diff --git a/doc/extensions/sharedDirectoryMapper.md b/doc/extensions/sharedDirectoryMapper.md index e3b189f8..46001a39 100644 --- a/doc/extensions/sharedDirectoryMapper.md +++ b/doc/extensions/sharedDirectoryMapper.md @@ -5,11 +5,11 @@ 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). +Since: WinSW 2.0. -### Usage +## Usage -The extension can be configured via the [XML Configuration File](../xmlConfigFile.md). +The extension can be configured via the [XML configuration file](../xmlConfigFile.md). Configuration sample: ```xml @@ -33,6 +33,6 @@ Configuration sample: ``` -### Notes +## Notes * If the extension fails to map the drive, the startup fails diff --git a/doc/installation.md b/doc/installation.md index e160c712..301d6fa8 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,13 +1,13 @@ -# WinSW Installation Guide +# Installation guide This page provides WinSW installation guidelines for different cases. -### Installation steps +## Installation steps In order to setup WinSW, you commonly need to perform the following steps: 1. Take *WinSW.exe* from the distribution, and rename it to your taste (such as *myapp.exe*) -1. Write *myapp.xml* (see [XML Config File specification](xmlConfigFile.md) for more details) +1. Write *myapp.xml* (see [XML config file specification](xmlConfigFile.md) for more details) 1. Place those two files side by side, because that's how WinSW discovers its configuration. 1. Run `myapp.exe install ` in order to install the service wrapper. 1. Optional - Perform additional configuration in the Windows Service Manager. @@ -18,9 +18,9 @@ In order to setup WinSW, you commonly need to perform the following steps: There are some details for each step available below. -### Installation step details +## Installation step details -#### Step 2. Configuration file +### Step 2. Configuration file You write the configuration file that defines your service. The example below is a primitive example being used in the Jenkins project: @@ -39,7 +39,7 @@ The example below is a primitive example being used in the Jenkins project: The full specification of the configuration file is available [here](xmlConfigFile.md). -#### Step 3. Service registration +### Step 3. Service registration You can then install the service like: @@ -54,7 +54,7 @@ Beyond these error codes, all the non-zero exit code should be assumed as a fail The Installer can be also started with the `/p` option. In such case it will prompt for an account name and password, which should be used as a service account. -#### Step 4. Windows Service Manager +### Step 4. Windows Service Manager Once the service is installed, you can start it from Windows Service Manager. If you open `Properties` for the service, you can also configure how the service should be launched. @@ -71,9 +71,9 @@ Once the start button is clicked, Windows will start *myapp.exe*, then *myapp.exe* will launch the executable specified in the configuration file (Java in this case). If this process dies, *myapp.exe* will exit itself, and the service will be considered stopped. -### Extra configuration options +## Extra configuration options -#### Making WinSW v1 compatible with .NET runtime 4.0+ +### Making WinSW v1 compatible with .NET runtime 4.0+ **IMPORTANT:** *Starting from WinSW v2 the release offers a new binary, which targets the .NET Framework 4.0. Such configuration is no longer required.* @@ -96,7 +96,7 @@ The way the runtime finds this file is by naming convention, so don't forget to See [this post](http://www.davidmoore.info/2010/12/17/running-net-2-runtime-applications-under-the-net-4-runtime/) for more about this. None of the other flags are needed. -#### WinSW Offline mode and Authenticode +### WinSW Offline mode and Authenticode To work with UAC-enabled Windows, winsw ships with a digital signature. This causes Windows to automatically verify this digital signature when the application is launched. diff --git a/doc/loggingAndErrorReporting.md b/doc/loggingAndErrorReporting.md index 7e1260ef..89adeead 100644 --- a/doc/loggingAndErrorReporting.md +++ b/doc/loggingAndErrorReporting.md @@ -1,14 +1,14 @@ -# WinSW Logging and Error Reporting +# Logging and error reporting -### Logging +## Logging Winsw supports several different ways to capture stdout and stderr from the process you launch. -### Log directory +## Log directory The `` element specifies the directory in which the log files are created. If this element is absent, it'll default to the same directory where the configuration file resides. -### Append mode (default) +## Append mode (default) In this mode, *myapp.out.log* and *myapp.err.log* (where *myapp* is the base name of the executable and the configuration file) are created and outputs are simply appended to these files. Note that the file can get quite big. @@ -16,7 +16,7 @@ In this mode, *myapp.out.log* and *myapp.err.log* (where *myapp* is the base nam ``` -### Reset mode +## Reset mode Works like the append mode, except that every time the service starts, the old log files are truncated. @@ -24,7 +24,7 @@ Works like the append mode, except that every time the service starts, the old l ``` -### Ignore mode +## Ignore mode Throw away stdout and stderr, and do not produce any log files at all. @@ -32,7 +32,7 @@ Throw away stdout and stderr, and do not produce any log files at all. ``` -### Rotate mode +## Rotate mode Works like the append mode, but in addition, if the log file gets bigger than a set size, it gets rotated to *myapp.1.out.log*, *myapp.2.out.log* and so on. The nested `` element specifies the rotation threshold in KB (defaults to 10MB), and the nested `` element specifies the number of rotated files to keep (defaults to 8.) @@ -43,7 +43,7 @@ Works like the append mode, but in addition, if the log file gets bigger than a ``` -### Rotate by time mode +## Rotate by time mode Works like the rotate mode, except that instead of using the size as a threshold, use the time period as the threshold. @@ -58,7 +58,7 @@ This configuration must accompany a nested `` element, which specifies The syntax of the pattern string is specified by [DateTime.ToString()](http://msdn.microsoft.com/en-us/library/zdtaw1bw.aspx). For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`. -### Rotate by size and time mode +## Rotate by size and time mode Works in a combination of rotate size mode and rotate time mode, if the log file gets bigger than a set size, it gets rotated using `` provided. @@ -96,7 +96,7 @@ The zipDateFormat can only be used in conjection with autoRollAtTime, provide th ``` -### Error reporting +## Error reporting WinSW uses WMI underneath, and as such it uses its error code as the exit code. See [Create method of the Win32_Service class](https://docs.microsoft.com/windows/win32/cimwin32prov/create-method-in-class-win32-service) for the complete list of exit code. diff --git a/doc/selfRestartingService.md b/doc/selfRestartingService.md index 26e35df2..33801021 100644 --- a/doc/selfRestartingService.md +++ b/doc/selfRestartingService.md @@ -1,6 +1,6 @@ # Self-restarting Windows services -### Restarting from the spawned process +## Restart from the spawned process To support self-restarting services, winsw exposes `WINSW_EXECUTABLE` environment variable into the forked process, which refers to the full path of *WinSW.exe* that's managing the service. diff --git a/doc/xmlConfigFile.md b/doc/xmlConfigFile.md index 84d68efb..62925f79 100644 --- a/doc/xmlConfigFile.md +++ b/doc/xmlConfigFile.md @@ -1,4 +1,4 @@ -# WinSW XML Configuration File +# XML configuration file This page describes the configuration file, which controls the behavior of the Windows service. @@ -23,7 +23,7 @@ Example: ``` -## Environment Variable Expansion in Configuration File +## Environment variable expansion Configuration XML files can include environment variable expansions of the form `%Name%`. Such occurrences, if found, will be automatically replaced by the actual values of the variables. @@ -90,7 +90,7 @@ Multiple elements can be used to specify multiple dependencies. Optionally set a different logging directory with `` and startup ``: reset (clear log), roll (move to \*.old) or append (default). -See the [Logging and Error reporting page](loggingAndErrorReporting.md) for more info. +See the [Logging and error reporting](loggingAndErrorReporting.md) page for more info. ### argument @@ -149,6 +149,7 @@ This optional element can be specified multiple times if necessary to specify en ``` ### interactive + If this optional element is specified, the service will be allowed to interact with the desktop, such as by showing a new window and dialog boxes. If your program requires GUI, set this like the following: