From 3f6bc3195ffbfb5d6c382d04c96fda9a2327bf69 Mon Sep 17 00:00:00 2001 From: Next Turn <45985406+nxtn@users.noreply.github.com> Date: Wed, 17 Mar 2021 02:00:57 +0800 Subject: [PATCH] Revise docs for 3.0.0-alpha.8 (#768) --- README.md | 1 - docs/extensions/shared-directory-mapper.md | 38 ---------------------- docs/migrate-to-3-x.md | 2 ++ docs/project/milestone-management.md | 7 ++++ docs/xml-config-file.md | 25 +++++++++++++- 5 files changed, 33 insertions(+), 40 deletions(-) delete mode 100644 docs/extensions/shared-directory-mapper.md create mode 100644 docs/project/milestone-management.md diff --git a/README.md b/README.md index 9d52478..74bcfd5 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,6 @@ Most commands require Administrator privileges to execute. WinSW will prompt for * [XML configuration file](docs/xml-config-file.md) * [Logging and error reporting](docs/logging-and-error-reporting.md) * [Extensions](docs/extensions/extensions.md) - * [Shared Directory Mapper](docs/extensions/shared-directory-mapper.md) * Use cases: * [Self-restarting services](docs/self-restarting-service.md) * [Deferred file operations](docs/deferred-file-operations.md) diff --git a/docs/extensions/shared-directory-mapper.md b/docs/extensions/shared-directory-mapper.md deleted file mode 100644 index 402ada4..0000000 --- a/docs/extensions/shared-directory-mapper.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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. - -This extension allows mapping external shared directories before starting up the executable. - -Since: WinSW 2.0. - -## Usage - -The extension can be configured via the [XML configuration file](../xml-config-file.md). -Configuration sample: - -```xml - - - sampleService - Sample service - This is a stub service. - %BASE%\sleep.bat - - - - - - - - - - - - -``` - -## Notes - -* If the extension fails to map the drive, the startup fails diff --git a/docs/migrate-to-3-x.md b/docs/migrate-to-3-x.md index ed4015c..98bdaed 100644 --- a/docs/migrate-to-3-x.md +++ b/docs/migrate-to-3-x.md @@ -19,3 +19,5 @@ TODO 1. Replace `` with `true`. 1. Replace `` with `true`. 1. Replace `` with `true`. +1. Remove the `RunawayProcessKiller` extension. +1. Move `.` to `..`. Remove the `SharedDirectoryMapper` extension. diff --git a/docs/project/milestone-management.md b/docs/project/milestone-management.md new file mode 100644 index 0000000..c1028eb --- /dev/null +++ b/docs/project/milestone-management.md @@ -0,0 +1,7 @@ +# Milestone management + +[Milestones](https://github.com/winsw/winsw/milestones) are used to prioritize items. + +- Place unplanned issues in `Future`. +- Place planned/WIP/done issues in `major.x`. +- When a new version is released, create a corresponding milestone `major.minor.patch` and move closed issues there. diff --git a/docs/xml-config-file.md b/docs/xml-config-file.md index 0335e82..1514ad1 100644 --- a/docs/xml-config-file.md +++ b/docs/xml-config-file.md @@ -42,27 +42,32 @@ The default working directory of the wrapper and it's child processes is the dir ### id +**Required** 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. ### executable +**Required** 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.) ### name +**Optional** Short display name of the service, which can contain spaces and other characters. This shouldn't be too long, like ``, and this also needs to be unique among all the services in a given system. ### description +**Optional** Long human-readable description of the service. This gets displayed in Windows service manager when the service is selected. ### startmode +**Optional** This element specifies the start mode of the Windows service. It can be one of the following values: Automatic, or Manual. For more information, see the [ChangeStartMode method](https://docs.microsoft.com/windows/win32/cimwin32prov/changestartmode-method-in-class-win32-service). @@ -70,6 +75,7 @@ The default value is `Automatic`. ### delayedAutoStart +**Optional** This Boolean option enables the delayed start mode if the `Automatic` start mode is defined. For more information, see [Startup Processes and Delayed Automatic Start](https://techcommunity.microsoft.com/t5/ask-the-performance-team/ws2008-startup-processes-and-delayed-automatic-start/ba-p/372692). @@ -82,6 +88,7 @@ Windows service installation may fail in such case. ### depend +**Optional** 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. @@ -94,12 +101,14 @@ Multiple elements can be used to specify multiple dependencies. ### logging +**Optional** Optionally set a different logging directory with `` and startup `mode`: append (default), reset (clear log), ignore, roll (move to `\*.old`). See the [Logging and error reporting](logging-and-error-reporting.md) page for more info. ### Arguments +**Optional** The `` element specifies the arguments to be passed to the executable. ```xml @@ -118,6 +127,7 @@ The `` element specifies the arguments to be passed to the executable ### stopargument/stopexecutable +**Optional** ~~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 the `` element is present, winsw will instead launch another process of `` (or `` if that's specified) with the specified arguments, and expects that to initiate the graceful shutdown of the service process. @@ -446,6 +456,19 @@ Automatically refreshes the service properties when the service starts or the fo - [start](cli-commands.md#start-command) - [stop](cli-commands.md#stop-command) - [restart](cli-commands.md#restart-command) -- [test](cli-commands.md#test-command) The default value is `true`. + +### `sharedDirectoryMapping` + +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. + +This allows mapping external shared directories before starting up the executable. + +```xml + + + + +```