mirror of https://github.com/winsw/winsw
Revise docs for 3.0.0-alpha.1 (#587)
* Add pre-release badge * Update XML spec for `<username>` * Update exit codes * Update XML spec for `<prompt>` * Create migration guide * Add a note for the previous version * docs -> documentation * * Format usage * Talk to myself * * Add deployment status badge * Update version strings * Update README title * Link to the migration guide * * Remove .NET Core version number * Delete exe-config-file.md * Update README.md * migration-guide.md -> migrate-to-3-x.mdpull/591/head v3.0.0-alpha.1
Next Turn
GitHub
parent
22c3043862
commit
1b20d0db12
49
README.md
49
README.md
|
|
@ -1,14 +1,20 @@
|
|||
# Windows Service Wrapper in less restrictive license
|
||||
# Windows Service Wrapper in a permissive license
|
||||
|
||||
[](https://github.com/winsw/winsw/releases)
|
||||
[](https://github.com/winsw/winsw/releases)
|
||||
[](https://www.nuget.org/packages/WinSW/)
|
||||
[](https://dev.azure.com/winsw/winsw/_build?definitionId=1&_a=summary)
|
||||
[](https://dev.azure.com/winsw/winsw/_release?_a=releases&view=mine&definitionId=1)
|
||||
[](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*.
|
||||
|
||||
**We are actively developing WinSW v3. Please refer to the v2 branch for previous version documentation.**
|
||||
|
||||
**Please help us prioritize items by voting or commenting on the issues!**
|
||||
|
||||
## Why?
|
||||
|
||||
See the [project manifest](MANIFEST.md).
|
||||
|
|
@ -17,7 +23,7 @@ See the [project manifest](MANIFEST.md).
|
|||
|
||||
WinSW offers executables for .NET Framework 2.0, 4.0 and 4.6.1.
|
||||
It can run on Windows platforms which have these versions of .NET Framework installed.
|
||||
For systems without .NET Framework, the project provides native 64-bit and 32-bit executables which are based on .NET Core 3.1.
|
||||
For systems without .NET Framework, the project provides native 64-bit and 32-bit executables based on .NET Core.
|
||||
|
||||
More executables can be added upon request.
|
||||
|
||||
|
|
@ -32,30 +38,51 @@ Binaries are available [here](https://repo.jenkins-ci.org/releases/com/sun/winsw
|
|||
|
||||
## Usage
|
||||
|
||||
WinSW is being managed by configuration files: [Main XML configuration file](docs/xml-config-file.md) and [EXE configuration file](docs/exe-config-file.md).
|
||||
WinSW is being managed by the [XML configuration file](docs/xml-config-file.md).
|
||||
|
||||
Your renamed *WinSW.exe* binary also accepts the following commands:
|
||||
|
||||
* `install` to install the service to Windows Service Controller.
|
||||
* `install`
|
||||
|
||||
Install the service to Windows Service Controller.
|
||||
This command requires some preliminary steps described in the [Installation guide](docs/installation.md).
|
||||
* `uninstall` to uninstall the service. The opposite operation of above.
|
||||
* `start` to start the service. The service must have already been installed.
|
||||
* `stop` to stop the service.
|
||||
* `stopwait` to stop the service and wait until it's actually stopped.
|
||||
* `restart` to restart the service. If the service is not currently running, this command acts like `start`.
|
||||
* `status` to check the current status of the service.
|
||||
|
||||
* `uninstall`
|
||||
|
||||
Uninstall the service. The opposite operation of above.
|
||||
|
||||
* `start`
|
||||
|
||||
Start the service. The service must have already been installed.
|
||||
|
||||
* `stop`
|
||||
|
||||
Stop the service.
|
||||
|
||||
* `stopwait`
|
||||
|
||||
Stop the service and wait until it's actually stopped.
|
||||
|
||||
* `restart`
|
||||
|
||||
Restart the service. If the service is not currently running, this command acts like `start`.
|
||||
|
||||
* `status`
|
||||
|
||||
Check the current status of the service.
|
||||
* This command prints one line to the console.
|
||||
* `NonExistent` indicates the service is not currently installed
|
||||
* `Started` to indicate the service is currently running
|
||||
* `Stopped` to indicate that the service is installed but not currently running.
|
||||
|
||||
Most commands require Administrator privileges to execute. Since v2.8, WinSW will prompt for UAC in non-elevated sessions.
|
||||
Most commands require Administrator privileges to execute. Since 2.8, WinSW will prompt for UAC in non-elevated sessions.
|
||||
|
||||
## Documentation
|
||||
|
||||
User documentation:
|
||||
|
||||
* [Installation guide](docs/installation.md) - Describes the installation process for different systems and .NET versions
|
||||
* [Migration guide](docs/migrate-to-3-x) - Migrate to WinSW 3.x.
|
||||
* Configuration:
|
||||
* [Main XML configuration file](docs/xml-config-file.md)
|
||||
* [EXE configuration file](docs/exe-config-file.md)
|
||||
|
|
|
|||
|
|
@ -1,7 +0,0 @@
|
|||
# EXE configuration file
|
||||
|
||||
In addition to the [XML configuration file](xml-config-file.md), WinSW uses a standard .NET *WinSW.exe.config* file, which allows setting up some custom settings.
|
||||
|
||||
Use-cases:
|
||||
* Managing Logging levels of log4j
|
||||
* etc.
|
||||
|
|
@ -10,7 +10,7 @@ These extensions allow to alter the behavior of the Windows service in order to
|
|||
|
||||
## Developer guide
|
||||
|
||||
In WinSW v2 the extension does not support inclusion of external extension DLLs.
|
||||
In the current versions of WinSW the extension does not support inclusion of external extension DLLs.
|
||||
|
||||
### Adding external extensions
|
||||
|
||||
|
|
@ -30,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 v2 the binary compatibility of extension APIs **is not guaranteed**.
|
||||
Please note that in the current versions of WinSW the binary compatibility of extension APIs **is not guaranteed**.
|
||||
|
|
|
|||
|
|
@ -109,7 +109,6 @@ The zipDateFormat can only be used in conjection with autoRollAtTime, provide th
|
|||
|
||||
## Error reporting
|
||||
|
||||
WinSW uses WMI underneath, and as such it uses its error code as the exit code.
|
||||
For the complete list of exit codes, see [return values of the Create method of the Win32_Service class](https://docs.microsoft.com/windows/win32/cimwin32prov/create-method-in-class-win32-service#return-value).
|
||||
WinSW exits with code 0 on success. Any positive exit code is a [system error code](https://docs.microsoft.com/windows/win32/debug/system-error-codes).
|
||||
|
||||
When winsw is running as a service, more detailed error information is reported to the Windows event log.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,11 @@
|
|||
# Migrate to 3.x
|
||||
|
||||
## Automatic migration
|
||||
|
||||
TODO
|
||||
|
||||
## Manual migration
|
||||
|
||||
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 `<password>` from config file and using `<prompt>` in interactive context.
|
||||
|
|
@ -209,7 +209,7 @@ Examples:
|
|||
|
||||
This is another useful building block for developing a self-updating service.
|
||||
|
||||
Since v2.7, if the destination file exists, WinSW will send its last write time in the `If-Modified-Since` header and skip downloading if `304 Not Modified` is received.
|
||||
Since 2.7, if the destination file exists, WinSW will send its last write time in the `If-Modified-Since` header and skip downloading if `304 Not Modified` is received.
|
||||
|
||||
### log
|
||||
|
||||
|
|
@ -271,14 +271,13 @@ To use a user account, specify a `<serviceaccount>` element like this:
|
|||
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<domain>YOURDOMAIN</domain>
|
||||
<user>useraccount</user>
|
||||
<username>DomainName\UserName</username>
|
||||
<password>Pa55w0rd</password>
|
||||
<allowservicelogon>true</allowservicelogon>
|
||||
</serviceaccount>
|
||||
```
|
||||
|
||||
The `<domain>` is optional and defaults to the local computer.
|
||||
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.
|
||||
If set to `true`, will automatically set the "Allow Log On As A Service" right to the listed account.
|
||||
|
|
@ -287,8 +286,7 @@ To use [Group Managed Service Accounts](https://docs.microsoft.com/windows-serve
|
|||
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<domain>YOURDOMAIN</domain>
|
||||
<user>gmsa_account$</user>
|
||||
<username>DomainName\GmsaUserName$</username>
|
||||
<allowservicelogon>true</allowservicelogon>
|
||||
</serviceaccount>
|
||||
```
|
||||
|
|
@ -299,7 +297,7 @@ To explicitly use the [LocalSystem account](https://docs.microsoft.com/windows/w
|
|||
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<user>LocalSystem</user>
|
||||
<username>LocalSystem</username>
|
||||
</serviceaccount>
|
||||
```
|
||||
|
||||
|
|
@ -311,8 +309,7 @@ To use the [LocalService account](https://docs.microsoft.com/windows/win32/servi
|
|||
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<domain>NT AUTHORITY</domain>
|
||||
<user>LocalService</user>
|
||||
<username>NT AUTHORITY\LocalService</username>
|
||||
</serviceaccount>
|
||||
```
|
||||
|
||||
|
|
@ -324,13 +321,30 @@ To use the [NetworkService account](https://docs.microsoft.com/windows/win32/ser
|
|||
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<domain>NT AUTHORITY</domain>
|
||||
<user>NetworkService</user>
|
||||
<username>NT AUTHORITY\NetworkService</username>
|
||||
</serviceaccount>
|
||||
```
|
||||
|
||||
Note that this account does not have a password, so any password provided is ignored.
|
||||
|
||||
#### `prompt`
|
||||
|
||||
Optional. Prompts for a user name and a password.
|
||||
|
||||
```xml
|
||||
<serviceaccount>
|
||||
<prompt>dialog|console</prompt>
|
||||
<serviceaccount>
|
||||
```
|
||||
|
||||
- `dialog`
|
||||
|
||||
Prompts using a dialog box.
|
||||
|
||||
- `console`
|
||||
|
||||
Prompts at the console.
|
||||
|
||||
### Working directory
|
||||
|
||||
Some services need to run with a working directory specified.
|
||||
|
|
|
|||
Loading…
Reference in New Issue