github
/
winsw
mirror of https://github.com/winsw/winsw
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #458 from NextTurn/docs 

Clean up documentation, move changelog to GitHub releases
pull/473/head
Oleg Nenashev 2020-04-01 10:54:11 +02:00 committed by GitHub
parent d326654381 f0ec34ba63
commit e655f5c489
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 254 additions and 442 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

218
CHANGELOG.md
View File

@ -1,217 +1,3 @@
Release Notes # Release Notes
====
##### Newer releases This content has been moved to the [Releases](https://github.com/winsw/winsw/releases).
See [GitHub Releases](https://github.com/winsw/winsw/releases)
##### 2.3.0
Release date: Aug 19, 2019
* [PR #315](https://github.com/kohsuke/winsw/pull/315) -
Prevent application crash when `roll-by-size-time` is enabled
* [PR #321](https://github.com/kohsuke/winsw/pull/321) -
Add a new `hidewindow` option to suppress windows popup on legacy platforms
* [PR #330](https://github.com/kohsuke/winsw/pull/330) -
Fix duplicate startup log entries
* [PR #299](https://github.com/kohsuke/winsw/pull/299),
[PR #303](https://github.com/kohsuke/winsw/pull/303),
[PR #311](https://github.com/kohsuke/winsw/pull/311),
[PR #316](https://github.com/kohsuke/winsw/pull/316),
[PR #318](https://github.com/kohsuke/winsw/pull/318) -
Documentation cleanup
Internal changes:
* [PR #331](https://github.com/kohsuke/winsw/pull/331) -
Add a Release Drafter configuration for the repository. Will be enabled in the future
##### 2.2.0
Release date: Jan 06, 2019
* [PR #247](https://github.com/kohsuke/winsw/pull/247) -
Intoduce new logging configuration options to allow renaming and disabling logs
(`logname`, `outfiledisabled`, `errfiledisabled`, `outfilepattern`, `errfilepattern`)
* [PR #259](https://github.com/kohsuke/winsw/pull/259) -
Add support of archiving old log files to the 'roll-by-size-time' log appender
(`zipOlderThanNumDays` and `zipDateFormat` options)
* [PR #239](https://github.com/kohsuke/winsw/pull/239) -
Improve logging for process termination by Runaway Process Killer
* [PR #254](https://github.com/kohsuke/winsw/pull/254) -
Performance: prevent double loading of the service descriptors on startup
##### 2.1.2
Release date: July 8, 2017
Fixed issues:
* [PR #228](https://github.com/kohsuke/winsw/pull/228) -
Runaway Process Killer extension was not using the `stopTimeoutMs` parameter.
##### 2.1.1
Release date: June 12, 2017
Fixed issues:
* [Issue #206](https://github.com/kohsuke/winsw/issues/206) -
Prevent printing of log entries in the `status` command.
([PR #214](https://github.com/kohsuke/winsw/pull/214))
* [Issue #218](https://github.com/kohsuke/winsw/issues/218) -
Prevent hanging of the `stopexecutable` when its logs are not being drained do the parent process.
([PR #220](https://github.com/kohsuke/winsw/pull/220), [PR #224](https://github.com/kohsuke/winsw/pull/224))
##### 2.1.0
Release date: April 19, 2017
Improvements:
* [Issue #183](https://github.com/kohsuke/winsw/issues/183) -
Add support of the Delayed Automatic Start mode definition in config XML.
[More Info](doc/xmlConfigFile.md#delayedautostart).
([PR #205](https://github.com/kohsuke/winsw/pull/205))
* [Issue #126](https://github.com/kohsuke/winsw/issues/126) -
Add support of BASIC and [SSPI](https://en.wikipedia.org/wiki/Security_Support_Provider_Interface) authentication in the `<download>` action.
[More Info](https://github.com/kohsuke/winsw/blob/master/doc/xmlConfigFile.md#download).
([PR #194](https://github.com/kohsuke/winsw/pull/194), [PR #203](https://github.com/kohsuke/winsw/pull/203))
* Introduce the `failOnError` option in the `<download>` action.
[More Info](https://github.com/kohsuke/winsw/blob/master/doc/xmlConfigFile.md#download).
([PR #195](https://github.com/kohsuke/winsw/pull/195))
##### 2.0.3
Release date: Apr 01, 2017
Fixed issues:
* [Issue #201](https://github.com/kohsuke/winsw/issues/201) -
Prevent conversion of environment variables to lowercase in the started executable.
([PR #202](https://github.com/kohsuke/winsw/pull/202))
##### 2.0.2
Release date: Feb 13, 2017
Fixed issues:
* [Issue #181](https://github.com/kohsuke/winsw/issues/181) -
Fix metadata of the `WinSW.NET2.exe` executable to make it really running on .NET Framework 2.
([PR #188](https://github.com/kohsuke/winsw/pull/188))
* [Issue #95](https://github.com/kohsuke/winsw/issues/95) -
During process tree termination rebuild the child process tree after the termination if `stopparentprocessfirst` is set.
Enhances the fix of [Issue #59](https://github.com/kohsuke/winsw/issues/59) in WinSW 2.0.
([PR #186](https://github.com/kohsuke/winsw/pull/186))
##### 2.0.1
Release date: Jan 06, 2017
Fixed issues:
* [Issue #178](https://github.com/kohsuke/winsw/issues/178) -
Fix processing of the legacy `arguments` parameter.
Regression in `2.0`.
([PR #179](https://github.com/kohsuke/winsw/pull/179))
##### 2.0
Release date: Dec 30, 2016
Improvements:
* [Issue #103](https://github.com/kohsuke/winsw/issues/103) -
Provide the executable for `.NET Framework 4.0`.
([PR #147](https://github.com/kohsuke/winsw/pull/147))
* With this binary patching of `exe.config` is no longer required to get WinSW running on newest systems.
* [Issue #154](https://github.com/kohsuke/winsw/issues/154) -
Provide WinSW configuration file samples.
([PR #170](https://github.com/kohsuke/winsw/pull/170))
* Samples are available within release packages
* Introduce the new [WinSW Extension Engine](doc/extensions/extensions.md).
([PR #42](https://github.com/kohsuke/winsw/pull/42))
* Add new `SharedDirectoriesMapper` extension. See the docs [here](doc/extensions/sharedDirectoryMapper.md)
([PR #42](https://github.com/kohsuke/winsw/pull/42)).
* [Issue #125](https://github.com/kohsuke/winsw/issues/125) -
Add new `RunawayProcessKiller` extension. See the docs [here](doc/extensions/runawayProcessKiller.md).
([PR #133](https://github.com/kohsuke/winsw/pull/133))
* [Issue #69](https://github.com/kohsuke/winsw/issues/69) -
Migrate event logging to [Apache log4net](https://logging.apache.org/log4net/).
([PR #145](https://github.com/kohsuke/winsw/pull/145), [PR #73](https://github.com/kohsuke/winsw/pull/73) and others).
* [Issue #85](https://github.com/kohsuke/winsw/issues/85) -
Use `FileStream#SafeFileHandle` the deprecated `FileStream#Handle` in the CLI `redirect` mode.
([PR #167](https://github.com/kohsuke/winsw/pull/167))
Fixed issues:
* [Issue #124](https://github.com/kohsuke/winsw/issues/124) -
Prevent CPU overutilization when waiting for the process to exit.
([PR #135](https://github.com/kohsuke/winsw/pull/135))
* [Issue #159](https://github.com/kohsuke/winsw/issues/159) -
Properly retrieve `waithint`, `sleeptime`, `resetfailure`, and `stoptimeout` options from XML configs with metadata before `settings`.
([PR #175](https://github.com/kohsuke/winsw/pull/175))
* [Issue #164](https://github.com/kohsuke/winsw/issues/164) -
Print warnings in the `uninstall` command when the service cannot be uninstalled immediately.
([PR #165](https://github.com/kohsuke/winsw/pull/165))
* [Issue #171](https://github.com/kohsuke/winsw/issues/171) -
Prevent failure when `stoparguments` are defined without `stopexecutable` in the XML file.
([PR #170](https://github.com/kohsuke/winsw/pull/170))
* [Issue #59](https://github.com/kohsuke/winsw/issues/59) -
Prevent failure during process termination if child processes cannot be retrieved due to the pending system shutdown.
([PR #172](https://github.com/kohsuke/winsw/pull/172))
* [Issue #54](https://github.com/kohsuke/winsw/issues/54) -
Security: Do not dump WinSW environment variables to the Event log.
([PR #173](https://github.com/kohsuke/winsw/pull/173))
* Do not propagate exceptions from `Process.Kill()` if the process actually exits.
([PR #166](https://github.com/kohsuke/winsw/pull/166))
Non-code changes:
* Major documentation refactoring and update.
* Use [GitHub Releases](https://github.com/kohsuke/winsw/releases) as a main release source.
* Jenkins [Maven repository](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/) is no longer the main release source
* It will be periodically updated on-demand
* [Issue #65](https://github.com/kohsuke/winsw/issues/65) -
Introduce NuGet packaging and publishing.
* Releases are being published on `www.nuget.org`.
[Package page](https://www.nuget.org/packages/WinSW/)
* [Issue #80](https://github.com/kohsuke/winsw/issues/80) -
Maven releases now pick releases from GitHub Releases.
The package version is guaranteed to be same as the assembly version.
([PR #162](https://github.com/kohsuke/winsw/pull/162))
* [Issue #142](https://github.com/kohsuke/winsw/issues/142) -
Introduce the CI/CD flow being hosted on AppVeyor. The project page is [here](https://ci.appveyor.com/project/oleg-nenashev/winsw).
Compatibility notes:
* WinSW `2.x` is **fully compatible** with WinSW `1.x` in terms of the command-line interface and configuration files.
* Any behavior difference will be considered as a bug
* New features like [WinSW extensions](doc/extensions/extensions.md) are disabled by default.
They can be enabled via the configuration file.
##### 1.19.1
Release date: Nov 05, 2016
Fixed issues:
* Fix the version number in the executable file metadata and CLI
##### 1.19
Release date: Aug 02, 2016
* No functional changes.
##### 1.18
Fixed issues: Aug 23, 2015
* [Issue #91](https://github.com/kohsuke/winsw/issues/91) - `%BASE%` contained the executable path instead of the directory path (regression in `1.17`)
##### 1.17
Release date: Mar 29, 2015
Changes: See the [winsw-1.17 milestone](https://github.com/kohsuke/winsw/milestone/1).
##### Previous versions
WinSW versions older than `1.17` have no explicit changelog.
If you need such info, see the [commit history](https://github.com/kohsuke/winsw/commits/master).

18
DEVELOPER.md
View File

@ -1,5 +1,4 @@
WinSW Developer Information # WinSW Developer Information
===
### Build Environment ### Build Environment
@ -23,16 +22,15 @@ For all these releases we use binaries being created by the special AppVeyor Job
Here are the release steps: Here are the release steps:
1. Integrate all pull requests you want to release to the master branch. 1. Integrate all pull requests you want to release to the master branch.
2. Update [CHANGELOG](./CHANGELOG.md) and push changes to the master. 1. Update [CHANGELOG](./CHANGELOG.md) and push changes to the master.
3. Wait till the [AppVeyor build](https://ci.appveyor.com/project/winsw/winsw) finishes for the last commit. 1. Wait till the [AppVeyor build](https://ci.appveyor.com/project/winsw/winsw) finishes for the last commit.
4. Go to the [winsw-release job page](https://ci.appveyor.com/project/oleg-nenashev/winsw-g2fwp). 1. Go to the [winsw-release job page](https://ci.appveyor.com/project/oleg-nenashev/winsw-g2fwp).
5. If you are doing a release with a new feature, bump the second digit in the _Version_ setting (e.g. to `2.N.${build}`) and change the next build number to `0`. In such case the version in assembly info will be `2.N.0` 1. If you are doing a release with a new feature, bump the second digit in the _Version_ setting (e.g. to `2.N.${build}`) and change the next build number to `0`. In such case the version in assembly info will be `2.N.0`
6. Run the [winsw-release](https://ci.appveyor.com/project/oleg-nenashev/winsw-g2fwp) build. 1. Run the [winsw-release](https://ci.appveyor.com/project/oleg-nenashev/winsw-g2fwp) build.
Once it completes, ensure the version is correct. Once it completes, ensure the version is correct.
7. Click on the _Deploy_ button for the build. 1. Click on the _Deploy_ button for the build.
Then deploy changes to _GitHub Releases_ and NuGet using the available publishers. Then deploy changes to _GitHub Releases_ and NuGet using the available publishers.
8. Go to [GitHub Releases](https://github.com/kohsuke/winsw/releases), find the published Release, click on _Edit release_ and then uncheck the _This is a pre-release_ checkbox to make the release public. 1. Go to [GitHub Releases](https://github.com/winsw/winsw/releases), find the published Release, click on *Edit release* and then uncheck the *This is a pre-release* checkbox to make the release public.
### Releasing to the Maven repository (legacy) ### Releasing to the Maven repository (legacy)

3
MANIFEST.md
View File

@ -1,5 +1,4 @@
Project manifest # Project manifest
===
Here is a cite from [Kohsuke Kawaguchi](https://github.com/kohsuke/), who is the original author of this project: Here is a cite from [Kohsuke Kawaguchi](https://github.com/kohsuke/), who is the original author of this project:

43
README.md
View File

@ -1,13 +1,13 @@
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.svg)](https://github.com/winsw/winsw/releases) [![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.svg)](https://www.nuget.org/packages/WinSW/) [![NuGet](https://img.shields.io/nuget/v/WinSW?style=flat-square)](https://www.nuget.org/packages/WinSW/)
[![Build status](https://ci.appveyor.com/api/projects/status/rspft8kdb33g6cis?svg=true)](https://ci.appveyor.com/project/winsw/winsw) [![Build Status](https://img.shields.io/appveyor/build/winsw/winsw?style=flat-square)](https://ci.appveyor.com/project/winsw/winsw)
[![Gitter](https://badges.gitter.im/winsw/winsw.svg)](https://gitter.im/winsw/winsw?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Gitter](https://img.shields.io/gitter/room/winsw/winsw?style=flat-square)](https://gitter.im/winsw/winsw?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
[![License](https://img.shields.io/github/license/winsw/winsw?style=flat-square)](LICENSE.txt)
WinSW is an executable binary, which can be used to wrap and manage a custom process as a Windows service. 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`. Once you download the installation package, you can rename *WinSW.exe* to any name, e.g. *MyService.exe*.
### Why? ### Why?
@ -15,7 +15,7 @@ See the [project manifest](MANIFEST.md).
### Download ### Download
Starting from WinSW `2.x`, the releases are being hosted on [GitHub](https://github.com/winsw/winsw/releases) and [nuget.org](https://www.nuget.org/packages/WinSW/). 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/).
Due to historical reasons, the project also uses [Jenkins Maven repository](https://jenkins.io/index.html) as a secondary source. Due to historical reasons, the project also uses [Jenkins Maven repository](https://jenkins.io/index.html) as a secondary source.
Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/). Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/).
@ -28,7 +28,7 @@ They provide a unique identity only.
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 Config file](doc/exeConfigFile.md).
Your renamed `winsw.exe` binary also accepts the following commands: Your renamed *WinSW.exe* binary also accepts the following commands:
* `install` to install the service to Windows Service Controller. * `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).
@ -44,17 +44,17 @@ Your renamed `winsw.exe` binary also accepts the following commands:
### Supported .NET versions ### Supported .NET versions
#### WinSW 2.x #### WinSW v2
WinSW `2.x` offers two executables, which declare .NET Frameworks `2.0` and `4.0` as targets. WinSW v2 offers two executables, which declare .NET Frameworks 2.0 and 4.0 as targets.
More executables can be added on-demand. More executables can be added on-demand.
Please create an issue if you need such executables. Please create an issue if you need such executables.
#### WinSW 1.x #### WinSW v1
WinSW `1.x` 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`. 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. 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. 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
@ -80,24 +80,27 @@ Developer documentation:
### Release lines ### Release lines
#### WinSW 2.x #### WinSW v2
This is a new baseline of WinSW with several major changes: This is a new baseline of WinSW with several major changes:
* Major documentation rework and update * Major documentation rework and update
* New executable package targeting the .NET Framework `4.0`. .NET Framework `2.0` is still supported. * New executable package targeting the .NET Framework 4.0. .NET Framework 2.0 is still supported.
* [Extension engine](doc/extensions/extensions.md), which allows extending the wrapper's behavior. And a couple of extensions for it (Shared Directory Mapper, Runaway Process Killer) * [Extension engine](doc/extensions/extensions.md), which allows extending the wrapper's behavior. And a couple of extensions for it (Shared Directory Mapper, Runaway Process Killer)
* New release hosting: GitHub and NuGet * New release hosting: GitHub and NuGet
* Migration of the logging subsystem to Apache log4net * Migration of the logging subsystem to Apache log4net
* Bugfixes * Bugfixes
See the full changelog in the [release notes](CHANGELOG.md#20). See the full changelog in the [release notes](CHANGELOG.md).
The version `2.x` is **fully compatible** with the `1.x` configuration file format, The version v2 is **fully compatible** with the v1 configuration file format,
hence the upgrade procedure just requires replacement of the executable file. hence the upgrade procedure just requires replacement of the executable file.
#### WinSW 1.x #### WinSW v1
This is an old baseline of WinSW. This is an old baseline of WinSW.
Currently it is in the maintenance-only state. Currently it is in the maintenance-only state.
New versions with fixes may be released on-demand. New versions with fixes may be released on-demand.
## License
WinSW is licensed under the [MIT](LICENSE.txt) license.

9
doc/deferredFileOperations.md
View File

@ -1,11 +1,10 @@
Deferred file operations # Deferred file operations
====
To support self updating services, winsw offers a mechanism to perform file operations before the process you specified in the configuration file gets launched. To support self updating services, winsw offers a mechanism to perform file operations before the process you specified in the configuration file gets launched.
This is often necessary because Windows prevents a file from being overwritten while it's in use. This is often necessary because Windows prevents a file from being overwritten while it's in use.
To perform file operations, write a text file (in the UTF-8 encoding) at `myapp.copies` To perform file operations, write a text file (in the UTF-8 encoding) at *myapp.copies*
(that is, it's in the same directory as `myapp.xml` and `myapp.exe` but with a different file extension), (that is, it's in the same directory as *myapp.xml* and *myapp.exe* but with a different file extension),
and for each operation add one line: and for each operation add one line:
* To move a file, write a line `src>dst`. If the `dst` file already exists it will be overwritten. * To move a file, write a line `src>dst`. If the `dst` file already exists it will be overwritten.
@ -21,7 +20,7 @@ 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. 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. 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. This behavior can be used to update *WinSW.exe* itself.
Also see `WINSW_EXECUTABLE` environment variable. Also see `WINSW_EXECUTABLE` environment variable.
The `<download>` element in the configuration file also provides an useful building block for a self updating service. The `<download>` element in the configuration file also provides an useful building block for a self updating service.

5
doc/exeConfigFile.md
View File

@ -1,7 +1,6 @@
WinSW EXE Configuration File # WinSW 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: Use-cases:
* Declaring compatibility with newer .NET versions (see the [Installation Guide](installation.md)) * Declaring compatibility with newer .NET versions (see the [Installation Guide](installation.md))

9
doc/extensions/extensions.md
View File

@ -1,7 +1,6 @@
WinSW extensions # WinSW extensions
===
Starting from WinSW `2.0`, the wrapper provides an internal extension engine and several 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. These extensions allow to alter the behavior of the Windows service in order to setup the required service environment.
### Available extensions ### Available extensions
@ -11,7 +10,7 @@ These extensions allow to alter the behavior of the Windows service in order to
### Developer guide ### Developer guide
In WinSW `2.x` the extension does not support inclusion of external extension DLLs. In WinSW v2 the extension does not support inclusion of external extension DLLs.
#### Adding external extensions #### Adding external extensions
@ -31,4 +30,4 @@ See configuration samples provided for the extensions in the core.
For extensions from external DLLs, the `className` field should also specify the assembly name. 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. It can be done via fully qualified class name or just by the `${CLASS_NAME}, ${ASSEMBLY_NAME}` declaration.
Please note that in the current versions of WinSW `2.x` the binary compatibility of extension APIs *is not guaranteed*. Please note that in the current versions of WinSW v2 the binary compatibility of extension APIs **is not guaranteed**.

3
doc/extensions/runawayProcessKiller.md
View File

@ -1,5 +1,4 @@
Runaway Process Killer Extension # Runaway Process Killer Extension
===
In particular cases Windows service wrapper may leak the process after the service completion. 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. It happens when WinSW gets terminated without executing the shutdown logic.

3
doc/extensions/sharedDirectoryMapper.md
View File

@ -1,5 +1,4 @@
Shared Directory Mapper extension # 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. 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. And sometimes it is impossible to workaround it due to the domain policies.

49
doc/installation.md
View File

@ -1,5 +1,4 @@
WinSW Installation Guide # WinSW Installation Guide
======
This page provides WinSW installation guidelines for different cases. This page provides WinSW installation guidelines for different cases.
@ -7,15 +6,15 @@ This page provides WinSW installation guidelines for different cases.
In order to setup WinSW, you commonly need to perform the following steps: In order to setup WinSW, you commonly need to perform the following steps:
0. Take `winsw.exe` from the distribution, and rename it to your taste (such as `myapp.exe`) 1. Take *WinSW.exe* from the distribution, and rename it to your taste (such as *myapp.exe*)
0. 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)
0. Place those two files side by side, because that's how WinSW discovers its configuration. 1. Place those two files side by side, because that's how WinSW discovers its configuration.
0. Run `myapp.exe install <OPTIONS>` in order to install the service wrapper. 1. Run `myapp.exe install <OPTIONS>` in order to install the service wrapper.
0. Optional - Perform additional configuration in the Windows Service Manager. 1. Optional - Perform additional configuration in the Windows Service Manager.
0. Optional - Perform extra configurations if required (guidelines are available below). 1. Optional - Perform extra configurations if required (guidelines are available below).
* Declare that the executable is compatible with .NET 4 or above (for WinSW 1.x **only**) * Declare that the executable is compatible with .NET 4 or above (**for WinSW v1 only**)
* Enable the WinSW offline mode * Enable the WinSW offline mode
0. Run the service from the Windows Service Manager. 1. Run the service from the Windows Service Manager.
There are some details for each step available below. There are some details for each step available below.
@ -26,7 +25,7 @@ There are some details for each step available below.
You write the configuration file that defines your service. You write the configuration file that defines your service.
The example below is a primitive example being used in the Jenkins project: The example below is a primitive example being used in the Jenkins project:
``` ```xml
<service> <service>
<id>jenkins</id> <id>jenkins</id>
<name>Jenkins</name> <name>Jenkins</name>
@ -68,23 +67,23 @@ In particular, the following option can be set up:
In addition to the service manager, it is possible to make some additional configurations in the `Windows Registry Editor`. In addition to the service manager, it is possible to make some additional configurations in the `Windows Registry Editor`.
Once the start button is clicked, Windows will start `myapp.exe`, 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). 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. If this process dies, *myapp.exe* will exit itself, and the service will be considered stopped.
### Extra configuration options ### Extra configuration options
#### Making WinSW 1.x compatible with .NET runtime 4.0+ #### Making WinSW v1 compatible with .NET runtime 4.0+
**NOTE.** _Starting from WinSW `2.0` the release offers a new binary, which targets the .NET Framework 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._ Such configuration is no longer required.*
Modern versions of Windows (e.g. Windows Server 2012 or Windows 10) do not ship with .NET runtime `2.0`, which is what `winsw.exe` is built against. Modern versions of Windows (e.g. Windows Server 2012 or Windows 10) do not ship with .NET Framework 2.0, which is what *WinSW.exe* is built against.
This is because unlike Java, where a newer runtime can host apps developed against earlier runtime, .NET apps need version specific runtimes. This is because unlike Java, where a newer runtime can host apps developed against earlier runtime, .NET apps need version specific runtimes.
One way to deal with this is to ensure that `.NET 2.0` runtime is installed through your installer, but another way is to declare that `winsw.exe` can be hosted on `.NET 4.0` runtime by creating an app config file `winsw.exe.config`. One way to deal with this is to ensure that .NET Framework 2.0 is installed through your installer, but another way is to declare that *WinSW.exe* can be hosted on .NET Framework 4.0 by creating an app config file *WinSW.exe.config*.
``` ```xml
<configuration> <configuration>
<startup> <startup>
<supportedRuntime version="v2.0.50727" /> <supportedRuntime version="v2.0.50727" />
@ -93,20 +92,20 @@ One way to deal with this is to ensure that `.NET 2.0` runtime is installed thro
</configuration> </configuration>
``` ```
The way the runtime finds this file is by naming convention, so don't forget to rename a file based on your actual executable name (e.g. `myapp.exe`). The way the runtime finds this file is by naming convention, so don't forget to rename a file based on your actual executable name (e.g. *myapp.exe*).
See [this post](http://www.davidmoore.info/2010/12/17/running-net-2-runtime-applications-under-the-net-4-runtime/) for more about this. 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. 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. 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 (see [more discussions](http://msdn.microsoft.com/en-us/library/bb629393.aspx)). This causes Windows to automatically verify this digital signature when the application is launched.
This adds some delay to the launch of the service, and more importantly, it prevents winsw from running in a server that has no internet connection. This adds some delay to the launch of the service, and more importantly, it prevents winsw from running in a server that has no internet connection.
This is because a part of the signature verification involves checking certificate revocation list. This is because a part of the signature verification involves checking certificate revocation list.
To prevent this problem, create `myapp.exe.config` in the same directory as `myapp.exe` (renamed `winsw.exe`) and put the following in it: To prevent this problem, create *myapp.exe.config* in the same directory as *myapp.exe* (renamed *WinSW.exe*) and put the following in it:
``` ```xml
<configuration> <configuration>
<runtime> <runtime>
<generatePublisherEvidence enabled="false"/> <generatePublisherEvidence enabled="false"/>
@ -114,4 +113,4 @@ To prevent this problem, create `myapp.exe.config` in the same directory as `mya
</configuration> </configuration>
``` ```
See [KB 936707](http://support.microsoft.com/kb/936707) for more details. For more information, see [\<generatePublisherEvidence\> Element](https://docs.microsoft.com/dotnet/framework/configure-apps/file-schema/runtime/generatepublisherevidence-element).

40
doc/loggingAndErrorReporting.md
View File

@ -1,33 +1,42 @@
# WinSW Logging and Error Reporting
WinSW Logging and Error Reporting
=======
### Logging ### Logging
Winsw supports several different ways to capture stdout and stderr from the process you launch. Winsw supports several different ways to capture stdout and stderr from the process you launch.
### Log directory ### Log directory
The `<logpath>` 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. The `<logpath>` 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.
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.
```xml
<log mode="append"/> <log mode="append"/>
```
### Reset mode ### Reset mode
Works like the append mode, except that every time the service starts, the old log files are truncated. Works like the append mode, except that every time the service starts, the old log files are truncated.
```xml
<log mode="reset"/> <log mode="reset"/>
```
### Ignore mode ### Ignore mode
Throw away stdout and stderr, and do not produce any log files at all. Throw away stdout and stderr, and do not produce any log files at all.
```xml
<log mode="none"/> <log mode="none"/>
```
### 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 `<sizeThreshold>` element specifies the rotation threshold in KB (defaults to 10MB), and the nested `<keepFiles>` element specifies the number of rotated files to keep (defaults to 8.)
``` 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 `<sizeThreshold>` element specifies the rotation threshold in KB (defaults to 10MB), and the nested `<keepFiles>` element specifies the number of rotated files to keep (defaults to 8.)
```xml
<log mode="roll-by-size"> <log mode="roll-by-size">
<sizeThreshold>10240</sizeThreshold> <sizeThreshold>10240</sizeThreshold>
<keepFiles>8</keepFiles> <keepFiles>8</keepFiles>
@ -35,11 +44,12 @@ 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. Works like the rotate mode, except that instead of using the size as a threshold, use the time period as the threshold.
This configuration must accompany a nested `<pattern>` element, which specifies the timestamp pattern used as the log file name. This configuration must accompany a nested `<pattern>` element, which specifies the timestamp pattern used as the log file name.
``` ```xml
<log mode="roll-by-time"> <log mode="roll-by-time">
<pattern>yyyyMMdd</pattern> <pattern>yyyyMMdd</pattern>
</log> </log>
@ -49,9 +59,10 @@ The syntax of the pattern string is specified by [DateTime.ToString()](http://ms
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`. 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 `<pattern>` provided. 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 `<pattern>` provided.
``` ```xml
<log mode="roll-by-size-time"> <log mode="roll-by-size-time">
<sizeThreshold>10240</sizeThreshold> <sizeThreshold>10240</sizeThreshold>
<pattern>yyyyMMdd</pattern> <pattern>yyyyMMdd</pattern>
@ -67,15 +78,18 @@ For example, in the above example, the log of Jan 1, 2013 gets written to `myapp
The syntax of the autoRollAtTime is specified by [TimeSpan.ToString()](https://msdn.microsoft.com/en-us/library/1ecy8h51(v=vs.110).aspx). The syntax of the autoRollAtTime is specified by [TimeSpan.ToString()](https://msdn.microsoft.com/en-us/library/1ecy8h51(v=vs.110).aspx).
For example, in the above example, at the start of the day it will roll the file over. For example, in the above example, at the start of the day it will roll the file over.
The zipOlderThanNumDays can only be used in conjection with autoRollAtTime, provide the number of days of files to keep. The `zipOlderThanNumDays` can only be used in conjection with autoRollAtTime, provide the number of days of files to keep.
```
```xml
<log mode="roll-by-size-time"> <log mode="roll-by-size-time">
<autoRollAtTime>00:00:00</autoRollAtTime> <autoRollAtTime>00:00:00</autoRollAtTime>
<zipOlderThanNumDays>5</zipOlderThanNumDays> <zipOlderThanNumDays>5</zipOlderThanNumDays>
</log> </log>
``` ```
The zipDateFormat can only be used in conjection with autoRollAtTime, provide the zip file format using the [DateTime.ToString()](http://msdn.microsoft.com/en-us/library/zdtaw1bw.aspx). The zipDateFormat can only be used in conjection with autoRollAtTime, provide the zip file format using the [DateTime.ToString()](http://msdn.microsoft.com/en-us/library/zdtaw1bw.aspx).
```
```xml
<log mode="roll-by-size-time"> <log mode="roll-by-size-time">
<autoRollAtTime>00:00:00</autoRollAtTime> <autoRollAtTime>00:00:00</autoRollAtTime>
<zipDateFormat>yyyyMM</zipDateFormat> <zipDateFormat>yyyyMM</zipDateFormat>
@ -84,7 +98,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. WinSW uses WMI underneath, and as such it uses its error code as the exit code.
See the MSDN article [Create method of the Win32_Service class](http://msdn.microsoft.com/en-us/library/aa389390%28VS.85%29.aspx) for the complete list of 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.
When winsw is running as a service, more detailed error information is reported to the Windows event log. When winsw is running as a service, more detailed error information is reported to the Windows event log.

7
doc/selfRestartingService.md
View File

@ -1,10 +1,9 @@
Self-restarting Windows services # Self-restarting Windows services
=======
### Restarting from the spawned process ### Restarting from the spawned process
To support self-restarting services, winsw exposes `WINSW_EXECUTABLE` environment variable into the forked 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. which refers to the full path of *WinSW.exe* that's managing the service.
To restart the service from within, execute `%WINSW_EXECUTABLE% restart!`. To restart the service from within, execute `%WINSW_EXECUTABLE% restart!`.
Note that you are invoking `restart!` command, not `restart` command. Note that you are invoking `restart!` command, not `restart` command.
This hidden command is a flavor of the `restart` operation, This hidden command is a flavor of the `restart` operation,
@ -13,4 +12,4 @@ This hidden command is a flavor of the `restart` operation,
This additional indirection is necessary because Windows Service Control Manager (SCM) will kill child processes recursively when it stops a service. This additional indirection is necessary because Windows Service Control Manager (SCM) will kill child processes recursively when it stops a service.
SCM doesn't provide the restart operation as an atomic operation either, so winsw implements restart by a sequence of stop and start. SCM doesn't provide the restart operation as an atomic operation either, so winsw implements restart by a sequence of stop and start.
The 2nd winsw process in a separate process group ensures that winsw can survive this massacre to execute the start call. The second winsw process in a separate process group ensures that winsw can survive this massacre to execute the start call.

77
doc/xmlConfigFile.md
View File

@ -1,10 +1,9 @@
WinSW XML Configuration File # WinSW XML Configuration File
====
This page describes the configuration file, which controls the behavior of the Jenkins service. This page describes the configuration file, which controls the behavior of the Windows service.
You can find configuration file samples in the `examples` directory of the source code repository. You can find configuration file samples in the [examples](../examples) directory of the source code repository.
Actual samples are being also published as a part of releases in GitHub and NuGet. Actual samples are being also published as a part of releases on GitHub and NuGet.
## File structure ## File structure
@ -12,7 +11,7 @@ The root element of this XML file must be `<service>`, and it supports the follo
Example: Example:
``` ```xml
<service> <service>
<id>jenkins</id> <id>jenkins</id>
<name>Jenkins</name> <name>Jenkins</name>
@ -30,33 +29,38 @@ Configuration XML files can include environment variable expansions of the form
Such occurrences, if found, will be automatically replaced by the actual values of the variables. Such occurrences, if found, will be automatically replaced by the actual values of the variables.
If an undefined environment variable is referenced, no substitution occurs. If an undefined environment variable is referenced, no substitution occurs.
Also, the service wrapper sets the environment variable `BASE` by itself, which points to a directory that contains the renamed `winsw.exe`. Also, the service wrapper sets the environment variable `BASE` by itself, which points to a directory that contains the renamed *WinSW.exe*.
This is useful to refer to other files in the same directory. This is useful to refer to other files in the same directory.
Since this is an environment variable by itself, this value can be also accessed from the child process launched from the service wrapper. Since this is an environment variable by itself, this value can be also accessed from the child process launched from the service wrapper.
## Configuration entries ## Configuration entries
### id ### id
Specifies the ID that Windows uses internally to identify the service. Specifies the ID that Windows uses internally to identify the service.
This has to be unique among all the services installed in a system, This has to be unique among all the services installed in a system,
and it should consist entirely out of alpha-numeric characters. and it should consist entirely out of alpha-numeric characters.
### name ### name
Short display name of the service, which can contain spaces and other characters. Short display name of the service, which can contain spaces and other characters.
This shouldn't be too long, like `<id>`, and this also needs to be unique among all the services in a given system. This shouldn't be too long, like `<id>`, and this also needs to be unique among all the services in a given system.
### description ### description
Long human-readable description of the service. Long human-readable description of the service.
This gets displayed in Windows service manager when the service is selected. This gets displayed in Windows service manager when the service is selected.
### executable ### executable
This element specifies the executable to be launched. This element specifies the executable to be launched.
It can be either absolute path, or you can just specify the executable name and let it be searched from `PATH` (although note that the services often run in a different user account and therefore it might have different `PATH` than your shell does.) It can be either absolute path, or you can just specify the executable name and let it be searched from `PATH` (although note that the services often run in a different user account and therefore it might have different `PATH` than your shell does.)
### startmode ### startmode
This element specifies the start mode of the Windows service. This element specifies the start mode of the Windows service.
It can be one of the following values: Boot, System, Automatic, or Manual. It can be one of the following values: Boot, System, Automatic, or Manual.
See [MSDN](https://msdn.microsoft.com/en-us/library/aa384896%28v=vs.85%29.aspx) for details. For more information, see [ChangeStartMode method](https://docs.microsoft.com/windows/win32/cimwin32prov/changestartmode-method-in-class-win32-service).
The default value is `Automatic`. The default value is `Automatic`.
### delayedAutoStart ### delayedAutoStart
@ -77,7 +81,7 @@ When service `X` depends on service `Y`, `X` can only run if `Y` is running.
Multiple elements can be used to specify multiple dependencies. Multiple elements can be used to specify multiple dependencies.
``` ```xml
<depend>Eventlog</depend> <depend>Eventlog</depend>
<depend>W32Time</depend> <depend>W32Time</depend>
``` ```
@ -89,26 +93,28 @@ Optionally set a different logging directory with `<logpath>` and startup `<logm
See the [Logging and Error reporting page](loggingAndErrorReporting.md) for more info. See the [Logging and Error reporting page](loggingAndErrorReporting.md) for more info.
### argument ### argument
This element specifies the arguments to be passed to the executable. This element specifies the arguments to be passed to the executable.
Winsw will quote each argument if necessary, so do not put quotes in `<argument>` to avoid double quotation. Winsw will quote each argument if necessary, so do not put quotes in `<argument>` to avoid double quotation.
``` ```xml
<argument>arg1</argument> <argument>arg1</argument>
<argument>arg2</argument> <argument>arg2</argument>
<argument>arg3</argument> <argument>arg3</argument>
``` ```
For backward compatibility, `<arguments>` element can be used instead to specify the whole command line in a single element. `<arguments>` element can be used instead to specify the whole command line in a single element.
### stopargument/stopexecutable ### stopargument/stopexecutable
When the service is requested to stop, winsw simply calls [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx ) API to kill the service instantly.
When the service is requested to stop, winsw simply calls [TerminateProcess function](https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminateprocess) to kill the service instantly.
However, if `<stopargument>` elements are present, winsw will instead launch another process of `<executable>` (or `<stopexecutable>` if that's specified) with the `<stopargument>` arguments, and expects that to initiate the graceful shutdown of the service process. However, if `<stopargument>` elements are present, winsw will instead launch another process of `<executable>` (or `<stopexecutable>` if that's specified) with the `<stopargument>` arguments, and expects that to initiate the graceful shutdown of the service process.
Winsw will then wait for the two processes to exit on its own, before reporting back to Windows that the service has terminated. Winsw will then wait for the two processes to exit on its own, before reporting back to Windows that the service has terminated.
When you use the `<stopargument>`, you must use `<startargument>` instead of `<argument>`. See the complete example below: When you use the `<stopargument>`, you must use `<startargument>` instead of `<argument>`. See the complete example below:
``` ```xml
<executable>catalina.sh</executable> <executable>catalina.sh</executable>
<startargument>jpda</startargument> <startargument>jpda</startargument>
<startargument>run</startargument> <startargument>run</startargument>
@ -121,22 +127,24 @@ Note that the name of the element is `startargument` and not `startarguments`.
As such, to specify multiple arguments, you'll specify multiple elements. As such, to specify multiple arguments, you'll specify multiple elements.
### stoptimeout ### stoptimeout
When the service is requested to stop, winsw first attempts to [GenerateConsoleCtrlEvent function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%29.aspx) (similar to Ctrl+C),
When the service is requested to stop, winsw first attempts to [GenerateConsoleCtrlEvent function](https://docs.microsoft.com/windows/console/generateconsolectrlevent) (similar to Ctrl+C),
then wait for up to 15 seconds for the process to exit by itself gracefully. then wait for up to 15 seconds for the process to exit by itself gracefully.
A process failing to do that (or if the process does not have a console), A process failing to do that (or if the process does not have a console),
then winsw resorts to calling [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714%28v=vs.85%29.aspx ) API to kill the service instantly. then winsw resorts to calling [TerminateProcess function](https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminateprocess) to kill the service instantly.
This optional element allows you to change this "15 seconds" value, so that you can control how long winsw gives the service to shut itself down. This optional element allows you to change this "15 seconds" value, so that you can control how long winsw gives the service to shut itself down.
See `<onfailure>` below for how to specify time duration: See `<onfailure>` below for how to specify time duration:
``` ```xml
<stoptimeout>10sec</stoptimeout> <stoptimeout>10sec</stoptimeout>
``` ```
### env ### Environment
This optional element can be specified multiple times if necessary to specify environment variables to be set for the child process. The syntax is: This optional element can be specified multiple times if necessary to specify environment variables to be set for the child process. The syntax is:
``` ```xml
<env name="HOME" value="c:\abc" /> <env name="HOME" value="c:\abc" />
``` ```
@ -144,7 +152,7 @@ This optional element can be specified multiple times if necessary to specify en
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 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: If your program requires GUI, set this like the following:
``` ```xml
<interactive /> <interactive />
``` ```
@ -152,10 +160,12 @@ Note that since the introduction UAC (Windows Vista and onward), services are no
In those OSes, all that this does is to allow the user to switch to a separate window station to interact with the service. In those OSes, all that this does is to allow the user to switch to a separate window station to interact with the service.
### beeponshutdown ### beeponshutdown
This optional element is to emit [simple tone](http://msdn.microsoft.com/en-us/library/ms679277%28VS.85%29.aspx) when the service shuts down.
This optional element is to emit [simple tone](https://docs.microsoft.com/windows/win32/api/utilapiset/nf-utilapiset-beep) when the service shuts down.
This feature should be used only for debugging, as some operating systems and hardware do not support this functionality. This feature should be used only for debugging, as some operating systems and hardware do not support this functionality.
### download ### download
This optional element can be specified multiple times to have the service wrapper retrieve resources from URL and place it locally as a file. This optional element can be specified multiple times to have the service wrapper retrieve resources from URL and place it locally as a file.
This operation runs when the service is started, before the application specified by `<executable>` is launched. This operation runs when the service is started, before the application specified by `<executable>` is launched.
@ -195,12 +205,14 @@ Examples:
This is another useful building block for developing a self-updating service. This is another useful building block for developing a self-updating service.
### log ### log
See the "Logging" section above for more details. See the "Logging" section above for more details.
### onfailure ### onfailure
This optional repeatable element controls the behaviour when the process launched by winsw fails (i.e., exits with non-zero exit code). This optional repeatable element controls the behaviour when the process launched by winsw fails (i.e., exits with non-zero exit code).
``` ```xml
<onfailure action="restart" delay="10 sec"/> <onfailure action="restart" delay="10 sec"/>
<onfailure action="restart" delay="20 sec"/> <onfailure action="restart" delay="20 sec"/>
<onfailure action="reboot" /> <onfailure action="reboot" />
@ -220,9 +232,12 @@ The possible suffix for the delay attribute is sec/secs/min/mins/hour/hours/day/
If the service keeps failing and it goes beyond the number of `<onfailure>` configured, the last action will be repeated. If the service keeps failing and it goes beyond the number of `<onfailure>` configured, the last action will be repeated.
Therefore, if you just want to always restart the service automatically, simply specify one `<onfailure>` element like this: Therefore, if you just want to always restart the service automatically, simply specify one `<onfailure>` element like this:
```xml
<onfailure action="restart" /> <onfailure action="restart" />
```
### resetfailure ### resetfailure
This optional element controls the timing in which Windows SCM resets the failure count. This optional element controls the timing in which Windows SCM resets the failure count.
For example, if you specify `<resetfailure>1 hour</resetfailure>` and your service continues to run longer than one hour, then the failure count is reset to zero. For example, if you specify `<resetfailure>1 hour</resetfailure>` and your service continues to run longer than one hour, then the failure count is reset to zero.
This affects the behaviour of the failure actions (see `<onfailure>` above). This affects the behaviour of the failure actions (see `<onfailure>` above).
@ -242,9 +257,10 @@ For more information, see [Security Descriptor Definition Language](https://docs
``` ```
### Service account ### Service account
It is possible to specify the useraccount (and password) that the service will run as. To do this, specify a `<serviceaccount>` element like this: It is possible to specify the useraccount (and password) that the service will run as. To do this, specify a `<serviceaccount>` element like this:
``` ```xml
<serviceaccount> <serviceaccount>
<domain>YOURDOMAIN</domain> <domain>YOURDOMAIN</domain>
<user>useraccount</user> <user>useraccount</user>
@ -258,7 +274,7 @@ If set to `true`, will automatically set the "Allow Log On As A Service" right t
To use [(Group) Managed Service Accounts](https://technet.microsoft.com/en-us/library/hh831782.aspx) append `$` to the account name and remove `<password>` element: To use [(Group) Managed Service Accounts](https://technet.microsoft.com/en-us/library/hh831782.aspx) append `$` to the account name and remove `<password>` element:
``` ```xml
<serviceaccount> <serviceaccount>
<domain>YOURDOMAIN</domain> <domain>YOURDOMAIN</domain>
<user>gmsa_account$</user> <user>gmsa_account$</user>
@ -267,30 +283,33 @@ To use [(Group) Managed Service Accounts](https://technet.microsoft.com/en-us/li
``` ```
### Working directory ### Working directory
Some services need to run with a working directory specified. Some services need to run with a working directory specified.
To do this, specify a `<workingdirectory>` element like this: To do this, specify a `<workingdirectory>` element like this:
``` ```xml
<workingdirectory>C:\application</workingdirectory> <workingdirectory>C:\application</workingdirectory>
``` ```
### priority ### Priority
Optionally specify the scheduling priority of the service process (equivalent of Unix nice) Optionally specify the scheduling priority of the service process (equivalent of Unix nice)
Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `realtime` (case insensitive.) Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `realtime` (case insensitive.)
``` ```xml
<priority>idle</priority> <priority>idle</priority>
``` ```
Specifying a priority higher than normal has unintended consequences. Specifying a priority higher than normal has unintended consequences.
See the MSDN article [ProcessPriorityClass Enumeration](http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass%28v=vs.110%29.aspx) for details. For more information, see [ProcessPriorityClass Enumeration](https://docs.microsoft.com/dotnet/api/system.diagnostics.processpriorityclass) in .NET docs.
This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage. This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage.
### stopparentprocessfirst ### Stop parent process first
Optionally specify the order of service shutdown. Optionally specify the order of service shutdown.
If `true`, the parent process is shutdown first. If `true`, the parent process is shutdown first.
This is useful when the main process is a console, which can respond to Ctrl+C command and will gracefully shutdown child processes. This is useful when the main process is a console, which can respond to Ctrl+C command and will gracefully shutdown child processes.
``` ```xml
<stopparentprocessfirst>true</stopparentprocessfirst> <stopparentprocessfirst>true</stopparentprocessfirst>
``` ```