mirror of https://github.com/winsw/winsw
Clean up documentation
NextTurn
parent
5fcfe177af
commit
f0ec34ba63
218
CHANGELOG.md
218
CHANGELOG.md
|
|
@ -1,217 +1,3 @@
|
|||
Release Notes
|
||||
====
|
||||
# Release Notes
|
||||
|
||||
##### Newer 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).
|
||||
This content has been moved to the [Releases](https://github.com/winsw/winsw/releases).
|
||||
|
|
|
|||
20
DEVELOPER.md
20
DEVELOPER.md
|
|
@ -1,12 +1,11 @@
|
|||
WinSW Developer Information
|
||||
===
|
||||
# WinSW Developer Information
|
||||
|
||||
### Build Environment
|
||||
|
||||
* *winsw_key.snk* should be available in the project's root in order to build the executable
|
||||
* You can generate the certificate by running *generate-key.ps1*
|
||||
* The certificate is in *.gitignore* list. Please do not add it to the repository
|
||||
|
||||
|
||||
### Continuous Integration
|
||||
|
||||
Project has a continuous integration flow being hosted by AppVeyor ([project page](https://ci.appveyor.com/project/winsw/winsw)).
|
||||
|
|
@ -23,16 +22,15 @@ For all these releases we use binaries being created by the special AppVeyor Job
|
|||
Here are the release steps:
|
||||
|
||||
1. Integrate all pull requests you want to release to the master branch.
|
||||
2. 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.
|
||||
4. 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`
|
||||
6. Run the [winsw-release](https://ci.appveyor.com/project/oleg-nenashev/winsw-g2fwp) build.
|
||||
1. Update [CHANGELOG](./CHANGELOG.md) and push changes to the master.
|
||||
1. Wait till the [AppVeyor build](https://ci.appveyor.com/project/winsw/winsw) finishes for the last commit.
|
||||
1. Go to the [winsw-release job page](https://ci.appveyor.com/project/oleg-nenashev/winsw-g2fwp).
|
||||
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`
|
||||
1. Run the [winsw-release](https://ci.appveyor.com/project/oleg-nenashev/winsw-g2fwp) build.
|
||||
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.
|
||||
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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
@ -13,4 +12,4 @@ Whether you like this or not depends on your taste, so I wouldn't claim mine is
|
|||
It's just different.
|
||||
|
||||
> As the name implies, this is for Windows only.
|
||||
Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using `launchd/upstart/SMF/etc`, instead of custom service wrapper.
|
||||
Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using `launchd/upstart/SMF/etc`, instead of custom service wrapper.
|
||||
|
|
|
|||
45
README.md
45
README.md
|
|
@ -1,13 +1,13 @@
|
|||
winsw: Windows service wrapper in less restrictive license
|
||||
=========================
|
||||
# winsw: Windows service wrapper in less restrictive license
|
||||
|
||||
[](https://github.com/winsw/winsw/releases)
|
||||
[](https://www.nuget.org/packages/WinSW/)
|
||||
[](https://ci.appveyor.com/project/winsw/winsw)
|
||||
[](https://gitter.im/winsw/winsw?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
[](https://github.com/winsw/winsw/releases)
|
||||
[](https://www.nuget.org/packages/WinSW/)
|
||||
[](https://ci.appveyor.com/project/winsw/winsw)
|
||||
[](https://gitter.im/winsw/winsw?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
|
||||
[](LICENSE.txt)
|
||||
|
||||
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?
|
||||
|
||||
|
|
@ -15,9 +15,9 @@ See the [project manifest](MANIFEST.md).
|
|||
|
||||
### 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/).
|
||||
|
||||
The executables in all sources are [strong-named assemblies](https://msdn.microsoft.com/en-us/library/wd40t7ad%28v=vs.110%29.aspx), which are being signed by randomly generated keys.
|
||||
|
|
@ -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).
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
#### 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.
|
||||
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`.
|
||||
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.
|
||||
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.
|
||||
|
||||
### Documentation
|
||||
|
|
@ -80,24 +80,27 @@ Developer documentation:
|
|||
|
||||
### Release lines
|
||||
|
||||
#### WinSW 2.x
|
||||
#### WinSW v2
|
||||
|
||||
This is a new baseline of WinSW with several major changes:
|
||||
* 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)
|
||||
* New release hosting: GitHub and NuGet
|
||||
* Migration of the logging subsystem to Apache log4net
|
||||
* 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.
|
||||
|
||||
#### WinSW 1.x
|
||||
#### WinSW v1
|
||||
|
||||
This is an old baseline of WinSW.
|
||||
Currently it is in the maintenance-only state.
|
||||
New versions with fixes may be released on-demand.
|
||||
|
||||
## License
|
||||
|
||||
WinSW is licensed under the [MIT](LICENSE.txt) license.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
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`
|
||||
(that is, it's in the same directory as `myapp.xml` and `myapp.exe` but with a different file extension),
|
||||
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),
|
||||
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.
|
||||
|
|
@ -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.
|
||||
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.
|
||||
|
||||
The `<download>` element in the configuration file also provides an useful building block for a self updating service.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
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:
|
||||
* 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.
|
||||
* etc.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
### Available extensions
|
||||
|
|
@ -11,7 +10,7 @@ These extensions allow to alter the behavior of the Windows service in order to
|
|||
|
||||
### 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
|
||||
|
||||
|
|
@ -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.
|
||||
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**.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
It happens when WinSW gets terminated without executing the shutdown logic.
|
||||
|
|
@ -49,4 +48,4 @@ The extension can be configured via the [XML Configuration File](../xmlConfigFil
|
|||
* 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.
|
||||
* If the force kill fails, the WinSW startup continues with a warning.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
And sometimes it is impossible to workaround it due to the domain policies.
|
||||
|
|
@ -36,4 +35,4 @@ Configuration sample:
|
|||
|
||||
### Notes
|
||||
|
||||
* If the extension fails to map the drive, the startup fails
|
||||
* If the extension fails to map the drive, the startup fails
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
WinSW Installation Guide
|
||||
======
|
||||
# WinSW Installation Guide
|
||||
|
||||
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:
|
||||
|
||||
0. 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)
|
||||
0. 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.
|
||||
0. Optional - Perform additional configuration in the Windows Service Manager.
|
||||
0. 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**)
|
||||
* Enable the WinSW offline mode
|
||||
0. Run the service from the Windows Service Manager.
|
||||
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. Place those two files side by side, because that's how WinSW discovers its configuration.
|
||||
1. Run `myapp.exe install <OPTIONS>` in order to install the service wrapper.
|
||||
1. Optional - Perform additional configuration in the Windows Service Manager.
|
||||
1. Optional - Perform extra configurations if required (guidelines are available below).
|
||||
* Declare that the executable is compatible with .NET 4 or above (**for WinSW v1 only**)
|
||||
* Enable the WinSW offline mode
|
||||
1. Run the service from the Windows Service Manager.
|
||||
|
||||
There are some details for each step available below.
|
||||
|
||||
|
|
@ -26,16 +25,16 @@ There are some details for each step available below.
|
|||
You write the configuration file that defines your service.
|
||||
The example below is a primitive example being used in the Jenkins project:
|
||||
|
||||
```
|
||||
<service>
|
||||
<id>jenkins</id>
|
||||
<name>Jenkins</name>
|
||||
<description>This service runs Jenkins continuous integration system.</description>
|
||||
<env name="JENKINS_HOME" value="%BASE%"/>
|
||||
<executable>java</executable>
|
||||
<arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
|
||||
<logmode>rotate</logmode>
|
||||
</service>
|
||||
```xml
|
||||
<service>
|
||||
<id>jenkins</id>
|
||||
<name>Jenkins</name>
|
||||
<description>This service runs Jenkins continuous integration system.</description>
|
||||
<env name="JENKINS_HOME" value="%BASE%"/>
|
||||
<executable>java</executable>
|
||||
<arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
|
||||
<logmode>rotate</logmode>
|
||||
</service>
|
||||
```
|
||||
|
||||
The full specification of the configuration file is available [here](xmlConfigFile.md).
|
||||
|
|
@ -45,7 +44,7 @@ The full specification of the configuration file is available [here](xmlConfigFi
|
|||
You can then install the service like:
|
||||
|
||||
```
|
||||
myapp.exe install <OPTIONS>
|
||||
myapp.exe install <OPTIONS>
|
||||
```
|
||||
|
||||
... and you can use the exit code from these processes to determine whether the operation was successful.
|
||||
|
|
@ -68,50 +67,50 @@ 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`.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
#### Making WinSW 1.x 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.
|
||||
Such configuration is no longer required._
|
||||
#### Making WinSW v1 compatible with .NET runtime 4.0+
|
||||
|
||||
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.
|
||||
**IMPORTANT:** *Starting from WinSW v2 the release offers a new binary, which targets the .NET Framework 4.0.
|
||||
Such configuration is no longer required.*
|
||||
|
||||
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.
|
||||
|
||||
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*.
|
||||
|
||||
```
|
||||
<configuration>
|
||||
<startup>
|
||||
<supportedRuntime version="v2.0.50727" />
|
||||
<supportedRuntime version="v4.0" />
|
||||
</startup>
|
||||
</configuration>
|
||||
```xml
|
||||
<configuration>
|
||||
<startup>
|
||||
<supportedRuntime version="v2.0.50727" />
|
||||
<supportedRuntime version="v4.0" />
|
||||
</startup>
|
||||
</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.
|
||||
None of the other flags are needed.
|
||||
|
||||
#### 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 (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 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:
|
||||
|
||||
```
|
||||
<configuration>
|
||||
<runtime>
|
||||
<generatePublisherEvidence enabled="false"/>
|
||||
</runtime>
|
||||
</configuration>
|
||||
```xml
|
||||
<configuration>
|
||||
<runtime>
|
||||
<generatePublisherEvidence enabled="false"/>
|
||||
</runtime>
|
||||
</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).
|
||||
|
|
|
|||
|
|
@ -1,64 +1,75 @@
|
|||
|
||||
WinSW Logging and Error Reporting
|
||||
=======
|
||||
# WinSW Logging and Error Reporting
|
||||
|
||||
### Logging
|
||||
|
||||
Winsw supports several different ways to capture stdout and stderr from the process you launch.
|
||||
|
||||
### 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.
|
||||
|
||||
### 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.
|
||||
|
||||
<log mode="append"/>
|
||||
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"/>
|
||||
```
|
||||
|
||||
### Reset mode
|
||||
|
||||
Works like the append mode, except that every time the service starts, the old log files are truncated.
|
||||
|
||||
<log mode="reset"/>
|
||||
```xml
|
||||
<log mode="reset"/>
|
||||
```
|
||||
|
||||
### Ignore mode
|
||||
|
||||
Throw away stdout and stderr, and do not produce any log files at all.
|
||||
|
||||
<log mode="none"/>
|
||||
```xml
|
||||
<log mode="none"/>
|
||||
```
|
||||
|
||||
### 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.)
|
||||
|
||||
```
|
||||
<log mode="roll-by-size">
|
||||
<sizeThreshold>10240</sizeThreshold>
|
||||
<keepFiles>8</keepFiles>
|
||||
</log>
|
||||
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">
|
||||
<sizeThreshold>10240</sizeThreshold>
|
||||
<keepFiles>8</keepFiles>
|
||||
</log>
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
This configuration must accompany a nested `<pattern>` element, which specifies the timestamp pattern used as the log file name.
|
||||
|
||||
```
|
||||
<log mode="roll-by-time">
|
||||
<pattern>yyyyMMdd</pattern>
|
||||
</log>
|
||||
```xml
|
||||
<log mode="roll-by-time">
|
||||
<pattern>yyyyMMdd</pattern>
|
||||
</log>
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
<log mode="roll-by-size-time">
|
||||
<sizeThreshold>10240</sizeThreshold>
|
||||
<pattern>yyyyMMdd</pattern>
|
||||
<autoRollAtTime>00:00:00</autoRollAtTime>
|
||||
<zipOlderThanNumDays>5</zipOlderThanNumDays>
|
||||
<zipDateFormat>yyyyMM</zipDateFormat>
|
||||
</log>
|
||||
```xml
|
||||
<log mode="roll-by-size-time">
|
||||
<sizeThreshold>10240</sizeThreshold>
|
||||
<pattern>yyyyMMdd</pattern>
|
||||
<autoRollAtTime>00:00:00</autoRollAtTime>
|
||||
<zipOlderThanNumDays>5</zipOlderThanNumDays>
|
||||
<zipDateFormat>yyyyMM</zipDateFormat>
|
||||
</log>
|
||||
```
|
||||
|
||||
The syntax of the pattern string is specified by [DateTime.ToString()](http://msdn.microsoft.com/en-us/library/zdtaw1bw.aspx).
|
||||
|
|
@ -67,24 +78,27 @@ 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).
|
||||
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.
|
||||
```
|
||||
<log mode="roll-by-size-time">
|
||||
<autoRollAtTime>00:00:00</autoRollAtTime>
|
||||
<zipOlderThanNumDays>5</zipOlderThanNumDays>
|
||||
</log>
|
||||
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">
|
||||
<autoRollAtTime>00:00:00</autoRollAtTime>
|
||||
<zipOlderThanNumDays>5</zipOlderThanNumDays>
|
||||
</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).
|
||||
```
|
||||
<log mode="roll-by-size-time">
|
||||
<autoRollAtTime>00:00:00</autoRollAtTime>
|
||||
<zipDateFormat>yyyyMM</zipDateFormat>
|
||||
</log>
|
||||
|
||||
```xml
|
||||
<log mode="roll-by-size-time">
|
||||
<autoRollAtTime>00:00:00</autoRollAtTime>
|
||||
<zipDateFormat>yyyyMM</zipDateFormat>
|
||||
</log>
|
||||
```
|
||||
|
||||
### Error reporting
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
When winsw is running as a service, more detailed error information is reported to the Windows event log.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,9 @@
|
|||
Self-restarting Windows services
|
||||
=======
|
||||
# Self-restarting Windows services
|
||||
|
||||
### Restarting 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.
|
||||
which refers to the full path of *WinSW.exe* that's managing the service.
|
||||
To restart the service from within, execute `%WINSW_EXECUTABLE% restart!`.
|
||||
Note that you are invoking `restart!` command, not `restart` command.
|
||||
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.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Actual samples are being also published as a part of releases in GitHub and NuGet.
|
||||
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 on GitHub and NuGet.
|
||||
|
||||
## File structure
|
||||
|
||||
|
|
@ -12,16 +11,16 @@ The root element of this XML file must be `<service>`, and it supports the follo
|
|||
|
||||
Example:
|
||||
|
||||
```
|
||||
<service>
|
||||
<id>jenkins</id>
|
||||
<name>Jenkins</name>
|
||||
<description>This service runs Jenkins continuous integration system.</description>
|
||||
<env name="JENKINS_HOME" value="%BASE%"/>
|
||||
<executable>java</executable>
|
||||
<arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
|
||||
<logmode>rotate</logmode>
|
||||
</service>
|
||||
```xml
|
||||
<service>
|
||||
<id>jenkins</id>
|
||||
<name>Jenkins</name>
|
||||
<description>This service runs Jenkins continuous integration system.</description>
|
||||
<env name="JENKINS_HOME" value="%BASE%"/>
|
||||
<executable>java</executable>
|
||||
<arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
|
||||
<logmode>rotate</logmode>
|
||||
</service>
|
||||
```
|
||||
|
||||
## Environment Variable Expansion in Configuration File
|
||||
|
|
@ -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.
|
||||
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.
|
||||
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
|
||||
|
||||
### id
|
||||
|
||||
Specifies the ID that Windows uses internally to identify the service.
|
||||
This has to be unique among all the services installed in a system,
|
||||
and it should consist entirely out of alpha-numeric characters.
|
||||
|
||||
### name
|
||||
|
||||
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.
|
||||
|
||||
### description
|
||||
|
||||
Long human-readable description of the service.
|
||||
This gets displayed in Windows service manager when the service is selected.
|
||||
|
||||
### executable
|
||||
|
||||
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.)
|
||||
|
||||
### startmode
|
||||
|
||||
This element specifies the start mode of the Windows service.
|
||||
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`.
|
||||
|
||||
### delayedAutoStart
|
||||
|
|
@ -68,7 +72,7 @@ Please note that this startup mode will not take affect on old Windows versions
|
|||
Windows service installation may fail in such case.
|
||||
|
||||
```xml
|
||||
<delayedAutoStart/>
|
||||
<delayedAutoStart/>
|
||||
```
|
||||
|
||||
### depend
|
||||
|
|
@ -77,9 +81,9 @@ When service `X` depends on service `Y`, `X` can only run if `Y` is running.
|
|||
|
||||
Multiple elements can be used to specify multiple dependencies.
|
||||
|
||||
```
|
||||
<depend>Eventlog</depend>
|
||||
<depend>W32Time</depend>
|
||||
```xml
|
||||
<depend>Eventlog</depend>
|
||||
<depend>W32Time</depend>
|
||||
```
|
||||
|
||||
### logging
|
||||
|
|
@ -89,73 +93,79 @@ Optionally set a different logging directory with `<logpath>` and startup `<logm
|
|||
See the [Logging and Error reporting page](loggingAndErrorReporting.md) for more info.
|
||||
|
||||
### argument
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
<argument>arg1</argument>
|
||||
<argument>arg2</argument>
|
||||
<argument>arg3</argument>
|
||||
```xml
|
||||
<argument>arg1</argument>
|
||||
<argument>arg2</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
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
<executable>catalina.sh</executable>
|
||||
<startargument>jpda</startargument>
|
||||
<startargument>run</startargument>
|
||||
|
||||
<stopexecutable>catalina.sh</stopexecutable>
|
||||
<stopargument>stop</stopargument>
|
||||
```xml
|
||||
<executable>catalina.sh</executable>
|
||||
<startargument>jpda</startargument>
|
||||
<startargument>run</startargument>
|
||||
|
||||
<stopexecutable>catalina.sh</stopexecutable>
|
||||
<stopargument>stop</stopargument>
|
||||
```
|
||||
|
||||
Note that the name of the element is `startargument` and not `startarguments`.
|
||||
As such, to specify multiple arguments, you'll specify multiple elements.
|
||||
|
||||
### 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.
|
||||
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.
|
||||
See `<onfailure>` below for how to specify time duration:
|
||||
|
||||
```
|
||||
<stoptimeout>10sec</stoptimeout>
|
||||
```xml
|
||||
<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:
|
||||
|
||||
```
|
||||
<env name="HOME" value="c:\abc" />
|
||||
```xml
|
||||
<env name="HOME" value="c:\abc" />
|
||||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
<interactive />
|
||||
```xml
|
||||
<interactive />
|
||||
```
|
||||
|
||||
Note that since the introduction UAC (Windows Vista and onward), services are no longer really allowed to interact with the desktop.
|
||||
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
|
||||
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.
|
||||
|
||||
### 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 operation runs when the service is started, before the application specified by `<executable>` is launched.
|
||||
|
||||
|
|
@ -170,7 +180,7 @@ For servers requiring authentication some parameters must be specified depending
|
|||
|
||||
The parameter “unsecureAuth” is only effective when the transfer protocol is HTTP - unencrypted data transfer. This is a security vulnerability because the credentials are send in clear text! For a SSPI authentication this is not relevant because the authentication tokens are encrypted.
|
||||
|
||||
For target servers using the HTTPS transfer protocol it is necessary, that the CA which issued the server certificate is trusted by the client. This is normally the situation when the server ist located in the Internet. When an organisation is using a self issued CA for the intranet this probably is not the case. In this case it is necessary to import the CA to the Certificate MMC of the Windows client. Have a look to the instructions on this [site](https://technet.microsoft.com/en-us/library/cc754841.aspx). The self issued CA must be imported to the Trusted Root Certification Authorities for the computer.
|
||||
For target servers using the HTTPS transfer protocol it is necessary, that the CA which issued the server certificate is trusted by the client. This is normally the situation when the server ist located in the Internet. When an organisation is using a self issued CA for the intranet this probably is not the case. In this case it is necessary to import the CA to the Certificate MMC of the Windows client. Have a look to the instructions on this [site](https://technet.microsoft.com/en-us/library/cc754841.aspx). The self issued CA must be imported to the Trusted Root Certification Authorities for the computer.
|
||||
|
||||
By default, the `download` command does not fail the service startup if the operation fails (e.g. `from` is not available).
|
||||
In order to force the download failure in such case, it is possible to specify the `failOnError` boolean attribute.
|
||||
|
|
@ -178,32 +188,34 @@ In order to force the download failure in such case, it is possible to specify t
|
|||
Examples:
|
||||
|
||||
```xml
|
||||
<download from="http://example.com/some.dat" to="%BASE%\some.dat" />
|
||||
|
||||
<download from="http://example.com/some.dat" to="%BASE%\some.dat" failOnError="true"/>
|
||||
<download from="http://example.com/some.dat" to="%BASE%\some.dat" />
|
||||
|
||||
<download from="https://example.com/some.dat" to="%BASE%\some.dat" auth="sspi" />
|
||||
<download from="http://example.com/some.dat" to="%BASE%\some.dat" failOnError="true"/>
|
||||
|
||||
<download from="https://example.com/some.dat" to="%BASE%\some.dat" failOnError="true"
|
||||
auth="basic" user="aUser" password="aPassw0rd" />
|
||||
<download from="https://example.com/some.dat" to="%BASE%\some.dat" auth="sspi" />
|
||||
|
||||
<download from="http://example.com/some.dat" to="%BASE%\some.dat"
|
||||
auth="basic" unsecureAuth="true"
|
||||
user="aUser" password="aPassw0rd" />
|
||||
<download from="https://example.com/some.dat" to="%BASE%\some.dat" failOnError="true"
|
||||
auth="basic" user="aUser" password="aPassw0rd" />
|
||||
|
||||
<download from="http://example.com/some.dat" to="%BASE%\some.dat"
|
||||
auth="basic" unsecureAuth="true"
|
||||
user="aUser" password="aPassw0rd" />
|
||||
```
|
||||
|
||||
This is another useful building block for developing a self-updating service.
|
||||
|
||||
### log
|
||||
|
||||
See the "Logging" section above for more details.
|
||||
|
||||
### onfailure
|
||||
|
||||
This optional repeatable element controls the behaviour when the process launched by winsw fails (i.e., exits with non-zero exit code).
|
||||
|
||||
```
|
||||
<onfailure action="restart" delay="10 sec"/>
|
||||
<onfailure action="restart" delay="20 sec"/>
|
||||
<onfailure action="reboot" />
|
||||
```xml
|
||||
<onfailure action="restart" delay="10 sec"/>
|
||||
<onfailure action="restart" delay="20 sec"/>
|
||||
<onfailure action="reboot" />
|
||||
```
|
||||
|
||||
For example, the above configuration causes the service to restart in 10 seconds after the first failure, restart in 20 seconds after the second failure, then Windows will reboot if the service fails one more time.
|
||||
|
|
@ -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.
|
||||
Therefore, if you just want to always restart the service automatically, simply specify one `<onfailure>` element like this:
|
||||
|
||||
<onfailure action="restart" />
|
||||
```xml
|
||||
<onfailure action="restart" />
|
||||
```
|
||||
|
||||
### resetfailure
|
||||
|
||||
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.
|
||||
This affects the behaviour of the failure actions (see `<onfailure>` above).
|
||||
|
|
@ -242,15 +257,16 @@ For more information, see [Security Descriptor Definition Language](https://docs
|
|||
```
|
||||
|
||||
### 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:
|
||||
|
||||
```
|
||||
<serviceaccount>
|
||||
<domain>YOURDOMAIN</domain>
|
||||
<user>useraccount</user>
|
||||
<password>Pa55w0rd</password>
|
||||
<allowservicelogon>true</allowservicelogon>
|
||||
</serviceaccount>
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<domain>YOURDOMAIN</domain>
|
||||
<user>useraccount</user>
|
||||
<password>Pa55w0rd</password>
|
||||
<allowservicelogon>true</allowservicelogon>
|
||||
</serviceaccount>
|
||||
```
|
||||
|
||||
The `<allowservicelogon>` is optional.
|
||||
|
|
@ -258,39 +274,42 @@ 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:
|
||||
|
||||
```
|
||||
<serviceaccount>
|
||||
<domain>YOURDOMAIN</domain>
|
||||
<user>gmsa_account$</user>
|
||||
<allowservicelogon>true</allowservicelogon>
|
||||
</serviceaccount>
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<domain>YOURDOMAIN</domain>
|
||||
<user>gmsa_account$</user>
|
||||
<allowservicelogon>true</allowservicelogon>
|
||||
</serviceaccount>
|
||||
```
|
||||
|
||||
### Working directory
|
||||
|
||||
Some services need to run with a working directory specified.
|
||||
To do this, specify a `<workingdirectory>` element like this:
|
||||
|
||||
```
|
||||
<workingdirectory>C:\application</workingdirectory>
|
||||
```xml
|
||||
<workingdirectory>C:\application</workingdirectory>
|
||||
```
|
||||
|
||||
### priority
|
||||
### Priority
|
||||
|
||||
Optionally specify the scheduling priority of the service process (equivalent of Unix nice)
|
||||
Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `realtime` (case insensitive.)
|
||||
|
||||
```
|
||||
<priority>idle</priority>
|
||||
```xml
|
||||
<priority>idle</priority>
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### stopparentprocessfirst
|
||||
### Stop parent process first
|
||||
|
||||
Optionally specify the order of service shutdown.
|
||||
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.
|
||||
|
||||
```
|
||||
```xml
|
||||
<stopparentprocessfirst>true</stopparentprocessfirst>
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue