mirror of https://github.com/winsw/winsw
Revise docs for 3.0.0-alpha.3 (#608)
* Mention optional settings * Mention removed settings * Add links to system requirements * markdownlint fixes * Remove trailing spaces * Mention boolean elements * Add preshutdown * Add `dev ps` command * Stop misleading * Why aren't you using Windows 10? * Add `stdoutPath`/`stderrPath` * Relative paths and the default working directory * Send a close message to Windows (GUI) apps * Use valid XML * Add `customize` and `dev kill` commands * Update README.md * Add commands * Fix spacing * Update installation.md * Update README.mdpull/651/head v3.0.0-alpha.3
Next Turn
GitHub
parent
1f188cf20b
commit
dcf3013f75
|
|
@ -17,13 +17,13 @@ You can open `src\winsw.sln` and then build and run tests from within Visual Stu
|
|||
|
||||
### Building
|
||||
|
||||
```
|
||||
```console
|
||||
dotnet build src\winsw.sln
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
```
|
||||
```console
|
||||
dotnet test src\Test\winswTests\winswTests.csproj
|
||||
```
|
||||
|
||||
|
|
|
|||
22
MANIFEST.md
22
MANIFEST.md
|
|
@ -2,14 +2,14 @@
|
|||
|
||||
Here is a cite from [Kohsuke Kawaguchi](https://github.com/kohsuke/), who is the original author of this project:
|
||||
|
||||
> Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available.
|
||||
The main reason for writing my own was the license — Java Service Wrapper project is in GPL (so that they can sell their commercial version in a different license), and that made it difficult for [Jenkins](http://jenkins-ci.org/) (which is under the MIT license) to use it.
|
||||
|
||||
> Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation.
|
||||
You basically write a configuration file specifying how you'd like your process to be launched, and we provide programmatic means to install/uninstall/start/stop services.
|
||||
Another notable difference is that winsw can host any executable, whereas Java Service Wrapper can only host Java apps.
|
||||
Whether you like this or not depends on your taste, so I wouldn't claim mine is better.
|
||||
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.
|
||||
> Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available.
|
||||
> The main reason for writing my own was the license — Java Service Wrapper project is in GPL (so that they can sell their commercial version in a different license), and that made it difficult for [Jenkins](http://jenkins-ci.org/) (which is under the MIT license) to use it.
|
||||
>
|
||||
> Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation.
|
||||
> You basically write a configuration file specifying how you'd like your process to be launched, and we provide programmatic means to install/uninstall/start/stop services.
|
||||
> Another notable difference is that winsw can host any executable, whereas Java Service Wrapper can only host Java apps.
|
||||
> Whether you like this or not depends on your taste, so I wouldn't claim mine is better.
|
||||
> 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.
|
||||
|
|
|
|||
35
README.md
35
README.md
|
|
@ -8,10 +8,9 @@
|
|||
[](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*.
|
||||
WinSW wraps and manages any application as a Windows service.
|
||||
|
||||
**We are actively developing WinSW v3. Please refer to the v2 branch for previous version documentation.**
|
||||
**We are actively developing WinSW 3. Please refer to the v2 branch for previous version documentation.**
|
||||
|
||||
**Please help us prioritize items by voting or commenting on the issues!**
|
||||
|
||||
|
|
@ -26,14 +25,23 @@ For systems without .NET Framework, the project provides native 64-bit and 32-bi
|
|||
|
||||
More executables can be added upon request.
|
||||
|
||||
[.NET Framework system requirements](https://docs.microsoft.com/dotnet/framework/get-started/system-requirements)\
|
||||
Preinstalled on Windows 10, version 1511 and Windows Server 2016.\
|
||||
Installable on Windows 7 SP1 and Windows Server 2008 R2 SP1.
|
||||
|
||||
[.NET 5 system requirements](https://github.com/dotnet/core/blob/master/release-notes/5.0/5.0-supported-os.md)\
|
||||
Supported on Windows 7 SP1, Windows Server (Core) 2012 R2 and Nano Server, version 1809.
|
||||
|
||||
## Download
|
||||
|
||||
WinSW binaries are available on [GitHub Releases](https://github.com/winsw/winsw/releases) and [NuGet](https://www.nuget.org/packages/WinSW/).
|
||||
Latest release and pre-release WinSW binaries are available on [GitHub Releases](https://github.com/winsw/winsw/releases).
|
||||
|
||||
Alternative sources:
|
||||
|
||||
* [Maven packaging](https://github.com/jenkinsci/winsw-maven-packaging) for executables, hosted by the [Jenkins project](https://jenkins.io/).
|
||||
Binaries are available [here](https://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/).
|
||||
* CI builds are available on [Azure Pipelines](https://dev.azure.com/winsw/winsw/_build?definitionId=1).
|
||||
* [NuGet](https://www.nuget.org/packages/WinSW/). (2.x)
|
||||
* [Maven packaging](https://github.com/jenkinsci/winsw-maven-packaging) for executables, hosted by the [Jenkins project](https://jenkins.io/).
|
||||
Binaries are available [here](https://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/). (2.x)
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -41,8 +49,8 @@ WinSW is being managed by the [XML configuration file](docs/xml-config-file.md).
|
|||
|
||||
Your renamed *WinSW.exe* binary also accepts the following commands:
|
||||
|
||||
| Command | Description |
|
||||
| ----------- | ----------- |
|
||||
| Command | Description |
|
||||
| ------- | ----------- |
|
||||
| [install](docs/cli-commands.md#install-command) | Installs the service. This command requires some preliminary steps described in the [installation guide](docs/installation.md). |
|
||||
| [uninstall](docs/cli-commands.md#uninstall-command) | Uninstalls the service. |
|
||||
| [start](docs/cli-commands.md#start-command) | Starts the service. |
|
||||
|
|
@ -51,8 +59,17 @@ Your renamed *WinSW.exe* binary also accepts the following commands:
|
|||
| [status](docs/cli-commands.md#status-command) | Checks the status of the service. |
|
||||
| [test](docs/cli-commands.md#test-command) | Checks if the service can be started and then stopped without installation. |
|
||||
| [refresh](docs/cli-commands.md#refresh-command) | Refreshes the service properties without reinstallation. |
|
||||
| [customize](docs/cli-commands.md#customize-command) | Customizes the wrapper executable. |
|
||||
| dev | Experimental commands. |
|
||||
|
||||
Most commands require Administrator privileges to execute. Since 2.8, WinSW will prompt for UAC in non-elevated sessions.
|
||||
Experimental commands:
|
||||
|
||||
| Command | Description |
|
||||
| ------- | ----------- |
|
||||
| dev ps | Draws the process tree associated with the service. |
|
||||
| dev kill | Terminates the service if it has stopped responding. |
|
||||
|
||||
Most commands require Administrator privileges to execute. WinSW will prompt for UAC in non-elevated sessions.
|
||||
|
||||
## Documentation
|
||||
|
||||
|
|
|
|||
|
|
@ -10,6 +10,7 @@
|
|||
- [status](#status-command)
|
||||
- [test](#test-command)
|
||||
- [refresh](#refresh-command)
|
||||
- [customize](#customize-command)
|
||||
|
||||
## `install` command
|
||||
|
||||
|
|
@ -17,7 +18,7 @@ Installs the service.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw install [<path-to-config>] [--no-elevate] [--user|--username <username>] [--pass|--password <password>]
|
||||
```
|
||||
|
||||
|
|
@ -48,7 +49,7 @@ Uninstalls the service.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw uninstall [<path-to-config>] [--no-elevate]
|
||||
```
|
||||
|
||||
|
|
@ -71,7 +72,7 @@ Starts the service.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw start [<path-to-config>] [--no-elevate]
|
||||
```
|
||||
|
||||
|
|
@ -94,7 +95,7 @@ Stops the service.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw stop [<path-to-config>] [--no-elevate] [--no-wait]
|
||||
```
|
||||
|
||||
|
|
@ -125,7 +126,7 @@ Stops and then starts the service.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw restart [<path-to-config>] [--no-elevate]
|
||||
```
|
||||
|
||||
|
|
@ -152,7 +153,7 @@ Checks the status of the service.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw status [<path-to-config>]
|
||||
```
|
||||
|
||||
|
|
@ -169,7 +170,7 @@ Checks if the service can be started and then stopped without installation.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw test [<path-to-config>] [--no-elevate] [--timeout <timeout>] [--no-break]
|
||||
```
|
||||
|
||||
|
|
@ -202,7 +203,7 @@ Refreshes the service properties without reinstallation.
|
|||
|
||||
### Usage
|
||||
|
||||
```
|
||||
```console
|
||||
winsw refresh [<path-to-config>] [--no-elevate]
|
||||
```
|
||||
|
||||
|
|
@ -218,3 +219,33 @@ If a file isn't specified, WinSW searches the executable directory for a *.xml*
|
|||
- `--no-elevate`
|
||||
|
||||
Doesn't automatically trigger a UAC prompt.
|
||||
|
||||
## `customize` command
|
||||
|
||||
Customizes the wrapper executable.
|
||||
|
||||
### Usage
|
||||
|
||||
```console
|
||||
winsw customize -o|--output <output> --manufacturer <manufacturer>
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
- `-o|--output <output>`
|
||||
|
||||
Required. Specifies the path to the output file.
|
||||
|
||||
- `--manufacturer <manufacturer>`
|
||||
|
||||
Specifies the manufacturer name of the customized executable.
|
||||
|
||||
## `dev ps` command
|
||||
|
||||
Draws the process tree associated with the service.
|
||||
|
||||
### Usage
|
||||
|
||||
```console
|
||||
winsw dev [<path-to-config>] ps
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# 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.
|
||||
|
||||
To perform file operations, write a text file (in the UTF-8 encoding) at *myapp.copies*
|
||||
|
|
|
|||
|
|
@ -18,6 +18,7 @@ The only way to create an external extension is to create a new extension DLL an
|
|||
See the example in `src/Core/ServiceWrapper/winsw.csproj`.
|
||||
|
||||
Generic extension creation guideline:
|
||||
|
||||
* Extension DLL should reference the `WinSWCore` library.
|
||||
* The extension should extend the `AbstractWinSWExtension` class.
|
||||
* The extension then can override event handlers offered by the upper class.
|
||||
|
|
@ -26,7 +27,7 @@ Generic extension creation guideline:
|
|||
|
||||
WinSW engine will automatically locate your extension using the class name in the [XML configuration file](../xml-config-file.md).
|
||||
See configuration samples provided for the extensions in the core.
|
||||
For extensions from external DLLs, the `className` field should also specify the assembly name.
|
||||
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 the binary compatibility of extension APIs **is not guaranteed**.
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ Since: WinSW 2.0.
|
|||
|
||||
## Usage
|
||||
|
||||
The extension can be configured via the [XML configuration file](../xml-config-file.md).
|
||||
The extension can be configured via the [XML configuration file](../xml-config-file.md).
|
||||
Configuration sample:
|
||||
|
||||
```xml
|
||||
|
|
|
|||
|
|
@ -1,16 +1,24 @@
|
|||
# Installation guide
|
||||
# Get started
|
||||
|
||||
This page provides WinSW installation guidelines for different cases.
|
||||
|
||||
## Installation steps
|
||||
## Use WinSW as a global tool
|
||||
|
||||
1. Take *WinSW.exe* or *WinSW.zip* from the distribution.
|
||||
1. Write *myapp.xml* (see the [XML config file specification](xml-config-file.md) for more details)
|
||||
1. Run [`winsw install myapp.xml [options]`](cli-commands.md#install-command) to install the service.
|
||||
1. Run [`winsw start myapp.xml`](cli-commands.md#start-command) to start the service.
|
||||
1. Run [`winsw status myapp.xml`](cli-commands.md#status-command) to see if your service is up and running.
|
||||
|
||||
## Use WinSW as a bundled tool
|
||||
|
||||
In order to setup WinSW, you commonly need to perform the following steps:
|
||||
|
||||
1. Take *WinSW.exe* from the distribution, and rename it to your taste (such as *myapp.exe*)
|
||||
1. Write *myapp.xml* (see the [XML config file specification](xml-config-file.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. Run `myapp.exe start` to start the service.
|
||||
1. Run [`myapp.exe install [options]`](cli-commands.md#install-command) to install the service.
|
||||
1. Run [`myapp.exe start`](cli-commands.md#start-command) to start the service.
|
||||
|
||||
There are some details for each step available below.
|
||||
|
||||
|
|
@ -18,7 +26,7 @@ There are some details for each step available below.
|
|||
|
||||
### Step 2. Configuration file
|
||||
|
||||
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:
|
||||
|
||||
```xml
|
||||
|
|
@ -36,16 +44,6 @@ The example below is a primitive example being used in the Jenkins project:
|
|||
The full specification of the configuration file is available [here](xml-config-file.md).
|
||||
|
||||
### Step 3. Service registration
|
||||
|
||||
You can then install the service like:
|
||||
|
||||
```
|
||||
myapp.exe install <OPTIONS>
|
||||
```
|
||||
|
||||
... and you can use the exit code from these processes to determine whether the operation was successful.
|
||||
Possible exit codes are described [here](https://docs.microsoft.com/windows/win32/cimwin32prov/create-method-in-class-win32-service#return-value).
|
||||
Beyond these error codes, all the non-zero exit code should be assumed as a failure.
|
||||
|
||||
The Installer can be also started with the `/p` option.
|
||||
In such case it will prompt for an account name and password, which should be used as a service account.
|
||||
|
|
|
|||
|
|
@ -55,8 +55,8 @@ This configuration must accompany a nested `<pattern>` element, which specifies
|
|||
</log>
|
||||
```
|
||||
|
||||
The syntax of the pattern string is specified by [DateTime.ToString(String)](https://docs.microsoft.com/dotnet/api/system.datetime.tostring#System_DateTime_ToString_System_String_).
|
||||
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`.
|
||||
The syntax of the pattern string is specified by [DateTime.ToString(String)](https://docs.microsoft.com/dotnet/api/system.datetime.tostring#System_DateTime_ToString_System_String_).
|
||||
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`.
|
||||
|
||||
## Roll by size and time mode
|
||||
|
||||
|
|
@ -70,8 +70,8 @@ Works in a combination of roll size mode and roll time mode, if the log file get
|
|||
</log>
|
||||
```
|
||||
|
||||
The syntax of the pattern string is specified by [DateTime.ToString(String)](https://docs.microsoft.com/dotnet/api/system.datetime.tostring#System_DateTime_ToString_System_String_).
|
||||
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`.
|
||||
The syntax of the pattern string is specified by [DateTime.ToString(String)](https://docs.microsoft.com/dotnet/api/system.datetime.tostring#System_DateTime_ToString_System_String_).
|
||||
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`.
|
||||
|
||||
The syntax of the autoRollAtTime is specified by [TimeSpan.ToString(String)](https://docs.microsoft.com/dotnet/api/system.timespan.tostring#System_TimeSpan_ToString_System_String_).
|
||||
For example, in the above example, at the start of the day it will roll the file over.
|
||||
|
|
@ -81,7 +81,6 @@ For example, in the above example, at the start of the day it will roll the file
|
|||
:warning: This feature is reported to be broken in recent WinSW versions.
|
||||
It is a potential subject for removal.
|
||||
|
||||
|
||||
```xml
|
||||
<log mode="roll-by-size-time">
|
||||
<zipOlderThanNumDays>5</zipOlderThanNumDays>
|
||||
|
|
|
|||
|
|
@ -6,8 +6,16 @@ TODO
|
|||
|
||||
## Manual migration
|
||||
|
||||
1. Remove `<name>` if you don't want it.
|
||||
1. Remove `<description>` if you don't want it.
|
||||
1. Merge `<argument>` into `<arguments>`.
|
||||
1. Merge `<startargument>` into `<startarguments>`.
|
||||
1. Merge `<stopargument>` into `<stoparguments>`.
|
||||
1. Remove `<stopparentprocessfirst>`.
|
||||
1. Merge `<domain>DomainName</domain>` and `<user>UserName</user>` into `<username>DomainName\UserName</username>`. If the user account belongs to the built-in domain, you can specify `<username>.\UserName</username>`.
|
||||
- Consider removing `<username>` and `<password>` from config file and using `<prompt>` in interactive context, or `--username` and `--password` command-line options in non-interactive context.
|
||||
1. Remove `<waithint>`.
|
||||
1. Remove `<sleeptime>`.
|
||||
1. Replace `<delayedAutoStart />` with `<delayedAutoStart>true</delayedAutoStart>`.
|
||||
1. Replace `<interactive />` with `<interactive>true</interactive>`.
|
||||
1. Replace `<beeponshutdown />` with `<beeponshutdown>true</beeponshutdown>`.
|
||||
|
|
|
|||
|
|
@ -2,14 +2,14 @@
|
|||
|
||||
## Restart 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.
|
||||
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,
|
||||
where winsw creates another winsw process in a separate process group,
|
||||
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,
|
||||
where winsw creates another winsw process in a separate process group,
|
||||
and restarts the service from there.
|
||||
|
||||
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.
|
||||
This additional indirection is necessary because WinSW will kill child processes recursively when it stops a service.
|
||||
Windows Service Control Manager (SCM) doesn't provide the restart operation as an atomic operation either, so winsw implements restart by a sequence of stop and start.
|
||||
The second winsw process in a separate process group ensures that winsw can survive this massacre to execute the start call.
|
||||
|
|
|
|||
|
|
@ -25,20 +25,25 @@ Example:
|
|||
|
||||
## Environment variable expansion
|
||||
|
||||
Configuration XML files can include environment variable expansions of the form `%Name%`.
|
||||
Such occurrences, if found, will be automatically replaced by the actual values of the variables.
|
||||
Configuration XML files can include environment variable expansions of the form `%Name%`.
|
||||
Such occurrences, if found, will be automatically replaced by the actual values of the variables.
|
||||
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*.
|
||||
This is useful to refer to other files in the same directory.
|
||||
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.
|
||||
|
||||
## Relative paths and the default working directory
|
||||
|
||||
Relative paths are resolved based on the [working directory](#working-directory).
|
||||
The default working directory of the wrapper and it's child processes is the directory where the configuration file is located.
|
||||
|
||||
## 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,
|
||||
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
|
||||
|
|
@ -53,13 +58,13 @@ This gets displayed in Windows service manager when the service is selected.
|
|||
|
||||
### 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.)
|
||||
|
||||
### startmode
|
||||
|
||||
This element specifies the start mode of the Windows service.
|
||||
It can be one of the following values: Boot, System, Automatic, or Manual.
|
||||
This element specifies the start mode of the Windows service.
|
||||
It can be one of the following values: Boot, System, Automatic, or Manual.
|
||||
For more information, see the [ChangeStartMode method](https://docs.microsoft.com/windows/win32/cimwin32prov/changestartmode-method-in-class-win32-service).
|
||||
The default value is `Automatic`.
|
||||
|
||||
|
|
@ -72,11 +77,12 @@ 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>true</delayedAutoStart>
|
||||
```
|
||||
|
||||
### depend
|
||||
Specify IDs of other services that this service depends on.
|
||||
|
||||
Specify IDs of other services that this service depends on.
|
||||
When service `X` depends on service `Y`, `X` can only run if `Y` is running.
|
||||
|
||||
Multiple elements can be used to specify multiple dependencies.
|
||||
|
|
@ -94,7 +100,7 @@ See the [Logging and error reporting](logging-and-error-reporting.md) page for m
|
|||
|
||||
### Arguments
|
||||
|
||||
The `<arguments>` element specifies the arguments to be passed to the executable.
|
||||
The `<arguments>` element specifies the arguments to be passed to the executable.
|
||||
|
||||
```xml
|
||||
<arguments>arg1 arg2 arg3</arguments>
|
||||
|
|
@ -108,6 +114,7 @@ The `<arguments>` element specifies the arguments to be passed to the executable
|
|||
arg2
|
||||
arg3
|
||||
</arguments>
|
||||
```
|
||||
|
||||
### stopargument/stopexecutable
|
||||
|
||||
|
|
@ -129,28 +136,65 @@ When you use the `<stoparguments>`, you must use `<startarguments>` instead of `
|
|||
### Additional commands
|
||||
|
||||
```xml
|
||||
<prestart|poststart|prestop|poststop>
|
||||
<prestart>
|
||||
<executable></executable>
|
||||
<arguments></arguments>
|
||||
</prestart|poststart|prestop|poststop>
|
||||
<stdoutPath></stdoutPath>
|
||||
<stderrPath></stderrPath>
|
||||
</prestart>
|
||||
```
|
||||
|
||||
The pre-start command is executed when the service is starting and before the main process is started.
|
||||
|
||||
The post-start command is executed when the service is running and after the main process is started.
|
||||
```xml
|
||||
<poststart>
|
||||
<!-- ... -->
|
||||
</poststart>
|
||||
```
|
||||
|
||||
The post-start command is executed when the service is starting and after the main process is started.
|
||||
|
||||
```xml
|
||||
<prestop>
|
||||
<!-- ... -->
|
||||
</prestop>
|
||||
```
|
||||
|
||||
The pre-stop command is executed when the service is stopping and before the main process is stopped.
|
||||
|
||||
```xml
|
||||
<poststop>
|
||||
<!-- ... -->
|
||||
</poststop>
|
||||
```
|
||||
|
||||
The post-stop command is executed when the service is stopping and after the main process is stopped.
|
||||
|
||||
`stdoutPath` specifies the path to redirect the standard output to.
|
||||
|
||||
`stderrPath` specifies the path to redirect the standard error output to.
|
||||
|
||||
Specify `NUL` in `stdoutPath` or `stderrPath` to dispose of the corresponding stream.
|
||||
|
||||
### Preshutdown
|
||||
|
||||
```xml
|
||||
<preshutdown>false</preshutdown>
|
||||
<preshutdownTimeout>3 min</preshutdown>
|
||||
```
|
||||
|
||||
Gives the service more time to stop when the system is being shut down.
|
||||
|
||||
The system default preshutdown timeout is there minutes.
|
||||
|
||||
### stoptimeout
|
||||
|
||||
When the service is requested to stop, winsw first attempts to send a Ctrl+C signal,
|
||||
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](https://docs.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminateprocess) to kill the service instantly.
|
||||
When the service is requested to stop, winsw first attempts to send a Ctrl+C signal to a console application, or post a close message to a Windows application,
|
||||
then wait for up to 15 seconds for the process to exit by itself gracefully.
|
||||
If the timeout expires or the signal or message can't be sent,
|
||||
then winsw resorts to terminate 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:
|
||||
|
||||
```xml
|
||||
|
|
@ -167,21 +211,25 @@ This optional element can be specified multiple times if necessary to specify en
|
|||
|
||||
### interactive
|
||||
|
||||
If this optional element is specified, the service will be allowed to interact with the desktop, such as by showing a new window and dialog boxes.
|
||||
If 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:
|
||||
|
||||
```xml
|
||||
<interactive />
|
||||
<interactive>true</interactive>
|
||||
```
|
||||
|
||||
Note that since the introduction UAC (Windows Vista and onward), services are no longer really allowed to interact with the desktop.
|
||||
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 tones](https://docs.microsoft.com/windows/win32/api/utilapiset/nf-utilapiset-beep) when the service shuts down.
|
||||
This optional element is to emit [simple tones](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.
|
||||
|
||||
```xml
|
||||
<beeponshutdown>true</beeponshutdown>
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
|
@ -190,11 +238,11 @@ This operation runs when the service is started, before the application specifie
|
|||
For servers requiring authentication some parameters must be specified depending on the type of authentication. Only the basic authentication requires additional sub-parameters. Supported authentication types are:
|
||||
|
||||
* `none`: default, must not be specified
|
||||
* `sspi`: Windows [Security Support Provider Interface](https://docs.microsoft.com/windows/win32/secauthn/sspi) including Kerberos, NTLM etc.
|
||||
* `sspi`: Windows [Security Support Provider Interface](https://docs.microsoft.com/windows/win32/secauthn/sspi) including Kerberos, NTLM etc.
|
||||
* `basic`: Basic authentication, sub-parameters:
|
||||
* `user="UserName"`
|
||||
* `password="Passw0rd"`
|
||||
* `unsecureAuth="true": default="false"`
|
||||
* `user="UserName"`
|
||||
* `password="Passw0rd"`
|
||||
* `unsecureAuth="true": default="false"`
|
||||
|
||||
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.
|
||||
|
||||
|
|
@ -204,6 +252,7 @@ By default, the `download` command does not fail the service startup if the oper
|
|||
In order to force the download failure in such case, it is possible to specify the `failOnError` boolean attribute.
|
||||
|
||||
To specify a custom proxy use the parameter `proxy` with the following formats:
|
||||
|
||||
- With credentials: `http://USERNAME:PASSWORD@HOST:PORT/`.
|
||||
- Without credentials: `http://HOST:PORT/`.
|
||||
|
||||
|
|
@ -222,7 +271,7 @@ Examples:
|
|||
auth="basic" user="aUser" password="aPassw0rd" />
|
||||
|
||||
<download from="http://example.com/some.dat" to="%BASE%\some.dat"
|
||||
proxy="http://aUser:aPassw0rd@192.168.1.5:80/"
|
||||
proxy="http://aUser:aPassw0rd@192.168.1.5:80/"
|
||||
auth="basic" unsecureAuth="true"
|
||||
user="aUser" password="aPassw0rd" />
|
||||
```
|
||||
|
|
@ -247,7 +296,7 @@ This optional repeatable element controls the behaviour when the process launche
|
|||
|
||||
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.
|
||||
|
||||
Each element contains a mandatory `action` attribute, which controls what Windows SCM will do, and optional `delay` attribute, which controls the delay until the action is taken.
|
||||
Each element contains a mandatory `action` attribute, which controls what Windows SCM will do, and optional `delay` attribute, which controls the delay until the action is taken.
|
||||
The legal values for action are:
|
||||
|
||||
* `restart`: restart the service
|
||||
|
|
@ -256,7 +305,7 @@ The legal values for action are:
|
|||
|
||||
The possible suffix for the delay attribute is sec/secs/min/mins/hour/hours/day/days. If missing, the delay attribute defaults to 0.
|
||||
|
||||
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:
|
||||
|
||||
```xml
|
||||
|
|
@ -265,14 +314,13 @@ Therefore, if you just want to always restart the service automatically, simply
|
|||
|
||||
### 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 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).
|
||||
|
||||
In other words, this is the duration in which you consider the service has been running successfully.
|
||||
In other words, this is the duration in which you consider the service has been running successfully.
|
||||
Defaults to 1 day.
|
||||
|
||||
|
||||
### Security descriptor
|
||||
|
||||
The security descriptor string for the service in SDDL form.
|
||||
|
|
@ -299,7 +347,7 @@ To use a user account, specify a `<serviceaccount>` element like this:
|
|||
|
||||
The `<username>` is in the form `DomainName\UserName` or `UserName@DomainName`. If the account belongs to the built-in domain, you can specify `.\UserName`.
|
||||
|
||||
The `<allowservicelogon>` is optional.
|
||||
The `<allowservicelogon>` is optional.
|
||||
If set to `true`, will automatically set the "Allow Log On As A Service" right to the listed account.
|
||||
|
||||
To use [Group Managed Service Accounts](https://docs.microsoft.com/windows-server/security/group-managed-service-accounts/group-managed-service-accounts-overview), append `$` to the account name and remove `<password>` element:
|
||||
|
|
@ -367,7 +415,7 @@ Optional. Prompts for a user name and a password.
|
|||
|
||||
### 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:
|
||||
|
||||
```xml
|
||||
|
|
|
|||
|
|
@ -27,16 +27,16 @@
|
|||
This is a sample configuration of the Windows Service Wrapper.
|
||||
This configuration file should be placed near the WinSW executable, the name should be the same.
|
||||
E.g. for myapp.exe the configuration file name should be myapp.xml
|
||||
|
||||
|
||||
You can find more information about configuration options here: https://github.com/winsw/winsw/blob/master/docs/xml-config-file.md
|
||||
-->
|
||||
<service>
|
||||
|
||||
<!--
|
||||
|
||||
<!--
|
||||
SECTION: Mandatory options
|
||||
All options in other sections are optional
|
||||
All options in other sections are optional
|
||||
-->
|
||||
|
||||
|
||||
<!-- ID of the service. It should be unique accross the Windows system-->
|
||||
<id>myapp</id>
|
||||
|
||||
|
|
@ -49,7 +49,7 @@ All options in other sections are optional
|
|||
<!--
|
||||
<description>This service is a service created from a sample configuration</description>
|
||||
-->
|
||||
|
||||
|
||||
<!-- Path to the executable, which should be started -->
|
||||
<executable>%BASE%\myExecutable.exe</executable>
|
||||
|
||||
|
|
@ -71,7 +71,7 @@ Their modification will not take affect without the service re-installation.
|
|||
<allowservicelogon>true</allowservicelogon>
|
||||
</serviceaccount>
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: onfailure
|
||||
Defines a sequence of actions, which should be performed if the managed executable fails.
|
||||
|
|
@ -82,7 +82,7 @@ Their modification will not take affect without the service re-installation.
|
|||
<onfailure action="restart" delay="20 sec"/>
|
||||
<onfailure action="reboot" />
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: resetfailure
|
||||
Time, after which the Windows service resets the failure status.
|
||||
|
|
@ -104,7 +104,7 @@ Their modification will not take affect without the service re-installation.
|
|||
SECTION: Executable management
|
||||
-->
|
||||
|
||||
<!--
|
||||
<!--
|
||||
OPTION: arguments
|
||||
Arguments, which should be passed to the executable
|
||||
-->
|
||||
|
|
@ -112,7 +112,7 @@ SECTION: Executable management
|
|||
<arguments>-classpath c:\cygwin\home\kohsuke\ws\hello-world\out\production\hello-world test.Main</arguments>
|
||||
-->
|
||||
|
||||
<!--
|
||||
<!--
|
||||
OPTION: startarguments
|
||||
Arguments, which should be passed to the executable when it starts
|
||||
If specified, overrides 'arguments'.
|
||||
|
|
@ -120,7 +120,7 @@ SECTION: Executable management
|
|||
<!--
|
||||
<startarguments></startarguments>
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: workingdirectory
|
||||
If specified, sets the default working directory of the executable
|
||||
|
|
@ -129,7 +129,7 @@ SECTION: Executable management
|
|||
<!--
|
||||
<workingdirectory>C:\myApp\work</workingdirectory>
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: priority
|
||||
Desired process priority.
|
||||
|
|
@ -137,16 +137,16 @@ SECTION: Executable management
|
|||
Default value: Normal
|
||||
-->
|
||||
<priority>Normal</priority>
|
||||
|
||||
<!--
|
||||
|
||||
<!--
|
||||
OPTION: stoptimeout
|
||||
Time to wait for the service to gracefully shutdown the executable before we forcibly kill it
|
||||
Default value: 15 seconds
|
||||
-->
|
||||
<stoptimeout>15 sec</stoptimeout>
|
||||
|
||||
|
||||
<!--
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: stopexecutable
|
||||
Path to an optional executable, which performs shutdown of the service.
|
||||
This executable will be used if and only if 'stoparguments' are specified.
|
||||
|
|
@ -156,7 +156,7 @@ SECTION: Executable management
|
|||
<stopexecutable>%BASE%\stop.exe</stopexecutable>
|
||||
-->
|
||||
|
||||
<!--
|
||||
<!--
|
||||
OPTION: stoparguments
|
||||
Additional arguments, which should be passed to the stop executable during termination.
|
||||
This OPTION also enables termination of the executable via stop executable
|
||||
|
|
@ -164,8 +164,8 @@ SECTION: Executable management
|
|||
<!--
|
||||
<stoparguments>-stop true</stoparguments>
|
||||
-->
|
||||
<!--
|
||||
SECTION: Service management
|
||||
<!--
|
||||
SECTION: Service management
|
||||
-->
|
||||
<!--
|
||||
OPTION: startmode
|
||||
|
|
@ -174,15 +174,15 @@ SECTION: Service management
|
|||
Default mode: Automatic
|
||||
-->
|
||||
<startmode>Automatic</startmode>
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: delayedAutoStart
|
||||
Enables the Delayed Automatic Start if 'Automatic' is specified in the 'startmode' field.
|
||||
See the WinSW documentation to get info about supported platform versions and limitations.
|
||||
-->
|
||||
<!--<delayedAutoStart>true</delayedAutoStart>-->
|
||||
|
||||
<!--
|
||||
|
||||
<!--
|
||||
OPTION: depend
|
||||
Optionally specifies services that must start before this service starts.
|
||||
-->
|
||||
|
|
@ -190,7 +190,7 @@ SECTION: Service management
|
|||
<depend>Eventlog</depend>
|
||||
<depend>W32Time</depend>
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: interactive
|
||||
Indicates the service can interactwith the desktop.
|
||||
|
|
@ -198,9 +198,9 @@ SECTION: Service management
|
|||
<!--
|
||||
<interactive>true</interactive>
|
||||
-->
|
||||
|
||||
<!--
|
||||
SECTION:Logging
|
||||
|
||||
<!--
|
||||
SECTION:Logging
|
||||
-->
|
||||
|
||||
<!--
|
||||
|
|
@ -211,7 +211,7 @@ SECTION:Logging
|
|||
<!--
|
||||
<logpath>%BASE%\logs</logpath>
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: log
|
||||
Defines logging mode for logs produced by the executable.
|
||||
|
|
@ -223,8 +223,8 @@ SECTION:Logging
|
|||
* roll-by-time - Roll logs based on time
|
||||
* rotate - Rotate logs based on size, (8 logs, 10MB each). This mode is deprecated, use "roll"
|
||||
Default mode: append
|
||||
|
||||
Each mode has different settings.
|
||||
|
||||
Each mode has different settings.
|
||||
See https://github.com/winsw/winsw/blob/master/docs/logging-and-error-reporting.md for more details
|
||||
-->
|
||||
<log mode="append">
|
||||
|
|
@ -233,7 +233,7 @@ SECTION:Logging
|
|||
<setting2/>
|
||||
-->
|
||||
</log>
|
||||
|
||||
|
||||
<!--
|
||||
SECTION: Environment setup
|
||||
-->
|
||||
|
|
@ -254,7 +254,7 @@ SECTION: Environment setup
|
|||
-->
|
||||
<!--
|
||||
<download from="http://www.google.com/" to="%BASE%\index.html" />
|
||||
|
||||
|
||||
Download and fail the service startup on Error:
|
||||
<download from="http://www.nosuchhostexists.com/" to="%BASE%\dummy.html" failOnError="true"/>
|
||||
|
||||
|
|
@ -267,15 +267,15 @@ SECTION: Environment setup
|
|||
<download from="https://example.com/some.dat" to="%BASE%\some.dat"
|
||||
auth="basic" username="aUser" password="aPassw0rd" />
|
||||
|
||||
Secure authentication when the target server and the client are members of the same domain or
|
||||
Secure authentication when the target server and the client are members of the same domain or
|
||||
the server domain and the client domain belong to the same forest with a trust:
|
||||
<download from="https://example.com/some.dat" to="%BASE%\some.dat" auth="sspi" />
|
||||
-->
|
||||
|
||||
<!--
|
||||
SECTION: Other options
|
||||
<!--
|
||||
SECTION: Other options
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
OPTION: beeponshutdown
|
||||
Indicates the service should beep when finished on shutdown (if it's supported by OS).
|
||||
|
|
@ -283,7 +283,7 @@ SECTION: Other options
|
|||
<!--
|
||||
<beeponshutdown>true</beeponshutdown>
|
||||
-->
|
||||
|
||||
|
||||
<!--
|
||||
SECTION: Extensions
|
||||
This configuration section allows specifying custom extensions.
|
||||
|
|
|
|||
|
|
@ -25,18 +25,18 @@
|
|||
|
||||
<!--
|
||||
This is an example of a minimal Windows Service Wrapper configuration, which includes only mandatory options.
|
||||
|
||||
|
||||
This configuration file should be placed near the WinSW executable, the name should be the same.
|
||||
E.g. for myapp.exe the configuration file name should be myapp.xml
|
||||
|
||||
|
||||
You can find more information about the configuration options here: https://github.com/winsw/winsw/blob/master/docs/xml-config-file.md
|
||||
Full example: https://github.com/winsw/winsw/blob/master/samples/sample-complete.xml
|
||||
-->
|
||||
<service>
|
||||
|
||||
|
||||
<!-- ID of the service. It should be unique across the Windows system-->
|
||||
<id>myapp</id>
|
||||
|
||||
|
||||
<!-- Path to the executable, which should be started -->
|
||||
<!-- CAUTION: Don't put arguments here. Use <arguments> instead. -->
|
||||
<executable>%BASE%\myExecutable.exe</executable>
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@ namespace WinSW.Tests
|
|||
private const string AllowServiceAccountLogonRight = "true";
|
||||
|
||||
private readonly ITestOutputHelper output;
|
||||
|
||||
|
||||
private XmlServiceConfig extendedServiceConfig;
|
||||
|
||||
public ServiceConfigTests(ITestOutputHelper output)
|
||||
|
|
|
|||
Loading…
Reference in New Issue