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
|
||||
```
|
||||
|
||||
|
|
|
|||
16
MANIFEST.md
16
MANIFEST.md
|
|
@ -3,13 +3,13 @@
|
|||
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.
|
||||
|
||||
> 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.
|
||||
|
||||
> 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.
|
||||
> 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.
|
||||
|
|
|
|||
31
README.md
31
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:
|
||||
|
||||
* 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/).
|
||||
Binaries are available [here](https://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/). (2.x)
|
||||
|
||||
## Usage
|
||||
|
||||
|
|
@ -42,7 +50,7 @@ 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 |
|
||||
| ----------- | ----------- |
|
||||
| ------- | ----------- |
|
||||
| [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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -37,15 +45,5 @@ The full specification of the configuration file is available [here](xml-config-
|
|||
|
||||
### 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.
|
||||
|
|
|
|||
|
|
@ -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>`.
|
||||
|
|
|
|||
|
|
@ -10,6 +10,6 @@ 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.
|
||||
|
|
|
|||
|
|
@ -33,6 +33,11 @@ Also, the service wrapper sets the environment variable `BASE` by itself, which
|
|||
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
|
||||
|
|
@ -72,10 +77,11 @@ 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.
|
||||
When service `X` depends on service `Y`, `X` can only run if `Y` is running.
|
||||
|
||||
|
|
@ -108,6 +114,7 @@ The `<arguments>` element specifies the arguments to be passed to the executable
|
|||
arg2
|
||||
arg3
|
||||
</arguments>
|
||||
```
|
||||
|
||||
### stopargument/stopexecutable
|
||||
|
||||
|
|
@ -129,26 +136,63 @@ 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,
|
||||
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.
|
||||
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.
|
||||
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.
|
||||
See `<onfailure>` below for how to specify time duration:
|
||||
|
|
@ -171,7 +215,7 @@ If this optional element is specified, the service will be allowed to interact w
|
|||
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.
|
||||
|
|
@ -182,6 +226,10 @@ In those OSes, all that this does is to allow the user to switch to a separate w
|
|||
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.
|
||||
|
|
@ -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/`.
|
||||
|
||||
|
|
@ -272,7 +321,6 @@ 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.
|
||||
Defaults to 1 day.
|
||||
|
||||
|
||||
### Security descriptor
|
||||
|
||||
The security descriptor string for the service in SDDL form.
|
||||
|
|
|
|||
Loading…
Reference in New Issue