From 1b20d0db125fcd77dfb707b6680bf721a3aba252 Mon Sep 17 00:00:00 2001 From: Next Turn <45985406+NextTurn@users.noreply.github.com> Date: Mon, 20 Jul 2020 01:40:05 -1200 Subject: [PATCH] Revise docs for 3.0.0-alpha.1 (#587) * Add pre-release badge * Update XML spec for `` * Update exit codes * Update XML spec for `` * 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.md --- README.md | 49 ++++++++++++++++++++++------- docs/exe-config-file.md | 7 ----- docs/extensions/extensions.md | 4 +-- docs/logging-and-error-reporting.md | 3 +- docs/migrate-to-3-x.md | 11 +++++++ docs/xml-config-file.md | 36 ++++++++++++++------- 6 files changed, 77 insertions(+), 33 deletions(-) delete mode 100644 docs/exe-config-file.md create mode 100644 docs/migrate-to-3-x.md diff --git a/README.md b/README.md index de96dde..192ccec 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,20 @@ -# Windows Service Wrapper in less restrictive license +# Windows Service Wrapper in a permissive license [![Github All Releases](https://img.shields.io/github/downloads/winsw/winsw/total?style=flat-square)](https://github.com/winsw/winsw/releases) +[![GitHub Release](https://img.shields.io/github/v/release/winsw/winsw?include_prereleases&style=flat-square)](https://github.com/winsw/winsw/releases) [![NuGet](https://img.shields.io/nuget/v/WinSW?style=flat-square)](https://www.nuget.org/packages/WinSW/) [![Build Status](https://img.shields.io/azure-devops/build/winsw/aabe43dd-6f6d-4660-b5dd-5b79e1e2ef4e/1?style=flat-square)](https://dev.azure.com/winsw/winsw/_build?definitionId=1&_a=summary) +[![Deployment Status](https://img.shields.io/azure-devops/release/winsw/aabe43dd-6f6d-4660-b5dd-5b79e1e2ef4e/1/1?style=flat-square)](https://dev.azure.com/winsw/winsw/_release?_a=releases&view=mine&definitionId=1) [![Gitter](https://img.shields.io/gitter/room/winsw/winsw?style=flat-square)](https://gitter.im/winsw/winsw?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![License](https://img.shields.io/github/license/winsw/winsw?style=flat-square)](LICENSE.txt) WinSW is an executable binary, which can be used to wrap and manage a custom process as a Windows service. 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) diff --git a/docs/exe-config-file.md b/docs/exe-config-file.md deleted file mode 100644 index 065547f..0000000 --- a/docs/exe-config-file.md +++ /dev/null @@ -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. diff --git a/docs/extensions/extensions.md b/docs/extensions/extensions.md index 7f5a71c..3e11a7e 100644 --- a/docs/extensions/extensions.md +++ b/docs/extensions/extensions.md @@ -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**. diff --git a/docs/logging-and-error-reporting.md b/docs/logging-and-error-reporting.md index 118a176..777bf29 100644 --- a/docs/logging-and-error-reporting.md +++ b/docs/logging-and-error-reporting.md @@ -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. diff --git a/docs/migrate-to-3-x.md b/docs/migrate-to-3-x.md new file mode 100644 index 0000000..65a753e --- /dev/null +++ b/docs/migrate-to-3-x.md @@ -0,0 +1,11 @@ +# Migrate to 3.x + +## Automatic migration + +TODO + +## Manual migration + +1. Remove ``. +1. Merge `DomainName` and `UserName` into `DomainName\UserName`. If the user account belongs to the built-in domain, you can specify `.\UserName`. + - Consider removing `` from config file and using `` in interactive context. diff --git a/docs/xml-config-file.md b/docs/xml-config-file.md index a49da75..d6e34b7 100644 --- a/docs/xml-config-file.md +++ b/docs/xml-config-file.md @@ -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 `` element like this: ```xml - YOURDOMAIN - useraccount + DomainName\UserName Pa55w0rd true ``` -The `` is optional and defaults to the local computer. +The `` is in the form `DomainName\UserName` or `UserName@DomainName`. If the account belongs to the built-in domain, you can specify `.\UserName`. The `` 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 - YOURDOMAIN - gmsa_account$ + DomainName\GmsaUserName$ true ``` @@ -299,7 +297,7 @@ To explicitly use the [LocalSystem account](https://docs.microsoft.com/windows/w ```xml - LocalSystem + LocalSystem ``` @@ -311,8 +309,7 @@ To use the [LocalService account](https://docs.microsoft.com/windows/win32/servi ```xml - NT AUTHORITY - LocalService + NT AUTHORITY\LocalService ``` @@ -324,13 +321,30 @@ To use the [NetworkService account](https://docs.microsoft.com/windows/win32/ser ```xml - NT AUTHORITY - NetworkService + NT AUTHORITY\NetworkService ``` 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 + + dialog|console + +``` + +- `dialog` + + Prompts using a dialog box. + +- `console` + + Prompts at the console. + ### Working directory Some services need to run with a working directory specified.