github
/
winsw
mirror of https://github.com/winsw/winsw
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #473 from NextTurn/headers 

Update documentation headers
pull/476/head
Oleg Nenashev 2020-04-03 00:15:54 +02:00 committed by GitHub
parent e655f5c489 26360ea696
commit d00fc32833
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
11 changed files with 64 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@ -1,3 +1,3 @@
# Release Notes
# Release notes
This content has been moved to the [Releases](https://github.com/winsw/winsw/releases).

41
README.md
View File

@ -1,4 +1,4 @@
# winsw: Windows service wrapper in less restrictive license
# winsw: Windows Service Wrapper in less restrictive license
[![Github All Releases](https://img.shields.io/github/downloads/winsw/winsw/total?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/)
@ -9,11 +9,11 @@
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*.
### Why?
## Why?
See the [project manifest](MANIFEST.md).
### Download
## Download
Starting from WinSW v2, the releases are being hosted on [GitHub](https://github.com/winsw/winsw/releases) and [NuGet](https://www.nuget.org/packages/WinSW/).
@ -24,14 +24,14 @@ The executables in all sources are [strong-named assemblies](https://msdn.micros
Do not rely on such strong names for security (as well as on other strong names as it recommended by Microsoft).
They provide a unique identity only.
### Usage
## Usage
WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE Config file](doc/exeConfigFile.md).
WinSW is being managed by configuration files: [Main XML configuration file](doc/xmlConfigFile.md) and [EXE configuration file](doc/exeConfigFile.md).
Your renamed *WinSW.exe* binary also accepts the following commands:
* `install` to install the service to Windows Service Controller.
This command requires some preliminary steps described in the [Installation Guide](doc/installation.md).
This command requires some preliminary steps described in the [Installation guide](doc/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.
@ -42,45 +42,44 @@ Your renamed *WinSW.exe* binary also accepts the following commands:
* `Started` to indicate the service is currently running
* `Stopped` to indicate that the service is installed but not currently running.
### Supported .NET versions
## Supported .NET versions
#### WinSW v2
### WinSW v2
WinSW v2 offers two executables, which declare .NET Frameworks 2.0 and 4.0 as targets.
More executables can be added on-demand.
Please create an issue if you need such executables.
#### WinSW v1
### WinSW v1
WinSW v1 Executable is being built with a .NET Framework 2.0 target, and by defaut it will work only for .NET Framework versions below 3.5.
On the other hand, the code is known to be compatible with .NET Framework 4.0 and above.
It is possible to declare the support of this framework via the *.exe.config* file.
See the [Installation Guide](doc/installation.md) for more details.
See the [Installation guide](doc/installation.md) for more details.
### Documentation
## Documentation
User documentation:
* [Installation Guide](doc/installation.md) - Describes the installation process for different systems and .NET versions
* [Release notes](CHANGELOG.md)
* [Installation guide](doc/installation.md) - Describes the installation process for different systems and .NET versions
* Configuration:
* [Main XML Configuration file](doc/xmlConfigFile.md)
* [EXE Configuration File](doc/exeConfigFile.md)
* [Logging and Error Reporting](doc/loggingAndErrorReporting.md)
* [Main XML configuration file](doc/xmlConfigFile.md)
* [EXE configuration file](doc/exeConfigFile.md)
* [Logging and error reporting](doc/loggingAndErrorReporting.md)
* [Extensions](doc/extensions/extensions.md)
* Use-cases:
* [Self-restarting services](doc/selfRestartingService.md)
* [Deferred File Operations](doc/deferredFileOperations.md)
* [Deferred file operations](doc/deferredFileOperations.md)
* Configuration Management:
* [Puppet Forge Module](doc/puppetWinSW.md)
Developer documentation:
* [Developer Guide](DEVELOPER.md)
* [Developer guide](DEVELOPER.md)
### Release lines
## Release lines
#### WinSW v2
### WinSW v2
This is a new baseline of WinSW with several major changes:
* Major documentation rework and update
@ -95,7 +94,7 @@ See the full changelog in the [release notes](CHANGELOG.md).
The version v2 is **fully compatible** with the v1 configuration file format,
hence the upgrade procedure just requires replacement of the executable file.
#### WinSW v1
### WinSW v1
This is an old baseline of WinSW.
Currently it is in the maintenance-only state.

1
doc/deferredFileOperations.md
View File

@ -18,6 +18,7 @@ example:
```
c:\soft\sshd.exe.new>c:\bin\ssh.exe
```
Note that it is apparently possible to [rename executables even when it's running](http://superuser.com/questions/488127/why-can-i-rename-a-running-executable-but-not-delete-it), which makes sense if you think about file handles.
Kohsuke has failed to find any authoritative source of information about this, but experimentally this even works on Windows XP and presumably on all the later Windows versions.
This behavior can be used to update *WinSW.exe* itself.

8
doc/exeConfigFile.md
View File

@ -1,9 +1,9 @@
# WinSW EXE Configuration File
# EXE configuration file
In addition to the [XML Configuration File](xmlConfigFile.md), WinSW uses a standard .NET *WinSW.exe.config* file, which allows setting up some custom settings.
In addition to the [XML configuration file](xmlConfigFile.md), WinSW uses a standard .NET *WinSW.exe.config* file, which allows setting up some custom settings.
Use-cases:
* Declaring compatibility with newer .NET versions (see the [Installation Guide](installation.md))
* Managing custom behavior for the offline mode (see the [Installation Guide](installation.md))
* Declaring compatibility with newer .NET versions (see the [Installation guide](installation.md))
* Managing custom behavior for the offline mode (see the [Installation guide](installation.md))
* Managing Logging levels of log4j
* etc.

8
doc/extensions/extensions.md
View File

@ -3,16 +3,16 @@
Starting from WinSW 2.0, the wrapper provides an internal extension engine and several extensions.
These extensions allow to alter the behavior of the Windows service in order to setup the required service environment.
### Available extensions
## Available extensions
* [Shared Directory Mapper](sharedDirectoryMapper.md) - Allows mapping shared drives before starting the executable
* [Runaway Process Killer](runawayProcessKiller.md) - Termination of processes started by the previous runs of WinSW
### Developer guide
## Developer guide
In WinSW v2 the extension does not support inclusion of external extension DLLs.
#### Adding external extensions
### Adding external extensions
The only way to create an external extension is to create a new extension DLL and
then to merge this DLL into the executable using tools like `ILMerge`.
@ -25,7 +25,7 @@ Generic extension creation guideline:
* The extension should implement the configuration parsing from the `XmlNode`.
* The extension should support disabling from the configuration file.
WinSW engine will automatically locate your extension using the class name in the [XML Configuration File](../xmlConfigFile.md).
WinSW engine will automatically locate your extension using the class name in the [XML configuration file](../xmlConfigFile.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.
It can be done via fully qualified class name or just by the `${CLASS_NAME}, ${ASSEMBLY_NAME}` declaration.

10
doc/extensions/runawayProcessKiller.md
View File

@ -1,4 +1,4 @@
# Runaway Process Killer Extension
# Runaway Process Killer extension
In particular cases Windows service wrapper may leak the process after the service completion.
It happens when WinSW gets terminated without executing the shutdown logic.
@ -7,11 +7,11 @@ Examples: force kill of the service process, .NET Runtime crash, missing permiss
Such runaway processes may conflict with the service process once it restarts.
This extension allows preventing it by running the runaway process termination on startup before the executable gets started.
Since: [WinSW 2.0](../../CHANGELOG.md).
Since: WinSW 2.0.
### Usage
## Usage
The extension can be configured via the [XML Configuration File](../xmlConfigFile.md). Configuration sample:
The extension can be configured via the [XML configuration file](../xmlConfigFile.md). Configuration sample:
```xml
<?xml version="1.0" encoding="utf-8" ?>
@ -42,7 +42,7 @@ The extension can be configured via the [XML Configuration File](../xmlConfigFil
</service>
```
### Notes
## Notes
* The current implementation of the the extension checks only the root process (started executable)
* If the runaway process is detected the entire, the entire process tree gets terminated

8
doc/extensions/sharedDirectoryMapper.md
View File

@ -5,11 +5,11 @@ 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](../../CHANGELOG.md).
Since: WinSW 2.0.
### Usage
## Usage
The extension can be configured via the [XML Configuration File](../xmlConfigFile.md).
The extension can be configured via the [XML configuration file](../xmlConfigFile.md).
Configuration sample:
```xml
@ -33,6 +33,6 @@ Configuration sample:
</service>
```
### Notes
## Notes
* If the extension fails to map the drive, the startup fails

20
doc/installation.md
View File

@ -1,13 +1,13 @@
# WinSW Installation Guide
# Installation guide
This page provides WinSW installation guidelines for different cases.
### Installation steps
## Installation steps
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 [XML Config File specification](xmlConfigFile.md) for more details)
1. Write *myapp.xml* (see [XML config file specification](xmlConfigFile.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. Optional - Perform additional configuration in the Windows Service Manager.
@ -18,9 +18,9 @@ In order to setup WinSW, you commonly need to perform the following steps:
There are some details for each step available below.
### Installation step details
## Installation step details
#### Step 2. Configuration file
### Step 2. Configuration file
You write the configuration file that defines your service.
The example below is a primitive example being used in the Jenkins project:
@ -39,7 +39,7 @@ The example below is a primitive example being used in the Jenkins project:
The full specification of the configuration file is available [here](xmlConfigFile.md).
#### Step 3. Service registration
### Step 3. Service registration
You can then install the service like:
@ -54,7 +54,7 @@ Beyond these error codes, all the non-zero exit code should be assumed as a fail
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.
#### Step 4. Windows Service Manager
### Step 4. Windows Service Manager
Once the service is installed, you can start it from Windows Service Manager.
If you open `Properties` for the service, you can also configure how the service should be launched.
@ -71,9 +71,9 @@ Once the start button is clicked, Windows will start *myapp.exe*,
then *myapp.exe* will launch the executable specified in the configuration file (Java in this case).
If this process dies, *myapp.exe* will exit itself, and the service will be considered stopped.
### Extra configuration options
## Extra configuration options
#### Making WinSW v1 compatible with .NET runtime 4.0+
### Making WinSW v1 compatible with .NET runtime 4.0+
**IMPORTANT:** *Starting from WinSW v2 the release offers a new binary, which targets the .NET Framework 4.0.
Such configuration is no longer required.*
@ -96,7 +96,7 @@ The way the runtime finds this file is by naming convention, so don't forget to
See [this post](http://www.davidmoore.info/2010/12/17/running-net-2-runtime-applications-under-the-net-4-runtime/) for more about this.
None of the other flags are needed.
#### WinSW Offline mode and Authenticode
### WinSW Offline mode and Authenticode
To work with UAC-enabled Windows, winsw ships with a digital signature.
This causes Windows to automatically verify this digital signature when the application is launched.

20
doc/loggingAndErrorReporting.md
View File

@ -1,14 +1,14 @@
# WinSW Logging and Error Reporting
# Logging and error reporting
### Logging
## Logging
Winsw supports several different ways to capture stdout and stderr from the process you launch.
### Log directory
## Log directory
The `<logpath>` element specifies the directory in which the log files are created. If this element is absent, it'll default to the same directory where the configuration file resides.
### Append mode (default)
## Append mode (default)
In this mode, *myapp.out.log* and *myapp.err.log* (where *myapp* is the base name of the executable and the configuration file) are created and outputs are simply appended to these files. Note that the file can get quite big.
@ -16,7 +16,7 @@ In this mode, *myapp.out.log* and *myapp.err.log* (where *myapp* is the base nam
<log mode="append"/>
```
### Reset mode
## Reset mode
Works like the append mode, except that every time the service starts, the old log files are truncated.
@ -24,7 +24,7 @@ Works like the append mode, except that every time the service starts, the old l
<log mode="reset"/>
```
### Ignore mode
## Ignore mode
Throw away stdout and stderr, and do not produce any log files at all.
@ -32,7 +32,7 @@ Throw away stdout and stderr, and do not produce any log files at all.
<log mode="none"/>
```
### Rotate mode
## Rotate mode
Works like the append mode, but in addition, if the log file gets bigger than a set size, it gets rotated to *myapp.1.out.log*, *myapp.2.out.log* and so on. The nested `<sizeThreshold>` element specifies the rotation threshold in KB (defaults to 10MB), and the nested `<keepFiles>` element specifies the number of rotated files to keep (defaults to 8.)
@ -43,7 +43,7 @@ Works like the append mode, but in addition, if the log file gets bigger than a
</log>
```
### Rotate by time mode
## Rotate by time mode
Works like the rotate mode, except that instead of using the size as a threshold, use the time period as the threshold.
@ -58,7 +58,7 @@ This configuration must accompany a nested `<pattern>` element, which specifies
The syntax of the pattern string is specified by [DateTime.ToString()](http://msdn.microsoft.com/en-us/library/zdtaw1bw.aspx).
For example, in the above example, the log of Jan 1, 2013 gets written to `myapp.20130101.out.log` and `myapp.20130101.err.log`.
### Rotate by size and time mode
## Rotate by size and time mode
Works in a combination of rotate size mode and rotate time mode, if the log file gets bigger than a set size, it gets rotated using `<pattern>` provided.
@ -96,7 +96,7 @@ The zipDateFormat can only be used in conjection with autoRollAtTime, provide th
</log>
```
### Error reporting
## Error reporting
WinSW uses WMI underneath, and as such it uses its error code as the exit code.
See [Create method of the Win32_Service class](https://docs.microsoft.com/windows/win32/cimwin32prov/create-method-in-class-win32-service) for the complete list of exit code.

2
doc/selfRestartingService.md
View File

@ -1,6 +1,6 @@
# Self-restarting Windows services
### Restarting from the spawned process
## Restart from the spawned 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.

7
doc/xmlConfigFile.md
View File

@ -1,4 +1,4 @@
# WinSW XML Configuration File
# XML configuration file
This page describes the configuration file, which controls the behavior of the Windows service.
@ -23,7 +23,7 @@ Example:
</service>
```
## Environment Variable Expansion in Configuration File
## 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.
@ -90,7 +90,7 @@ Multiple elements can be used to specify multiple dependencies.
Optionally set a different logging directory with `<logpath>` and startup `<logmode>`: reset (clear log), roll (move to \*.old) or append (default).
See the [Logging and Error reporting page](loggingAndErrorReporting.md) for more info.
See the [Logging and error reporting](loggingAndErrorReporting.md) page for more info.
### argument
@ -149,6 +149,7 @@ 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 your program requires GUI, set this like the following: