mirror of https://github.com/winsw/winsw
Rename docs for SEO
NextTurn
Next Turn
parent
700f45cb84
commit
f43e3bb6ab
|
|
@ -29,4 +29,4 @@ dotnet test src\Test\winswTests\winswTests.csproj
|
|||
|
||||
## Project Structure
|
||||
|
||||
You can find the project structure guideline [here](doc/developer/projectStructure.md).
|
||||
You can find the project structure guideline [here](docs/developer/project-structure.md).
|
||||
|
|
|
|||
23
README.md
23
README.md
|
|
@ -29,16 +29,15 @@ Alternative sources:
|
|||
|
||||
* [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/).
|
||||
* [Puppet](./doc/puppetWinSW.md), currently outdated (WinSW 1.x). Binaries are available on [Puppet Forge](https://forge.puppet.com/kenmaglio/winsw)
|
||||
|
||||
## Usage
|
||||
|
||||
WinSW is being managed by configuration files: [Main XML configuration file](doc/xmlConfigFile.md) and [EXE configuration file](doc/exeConfigFile.md).
|
||||
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).
|
||||
|
||||
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](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.
|
||||
|
|
@ -56,17 +55,17 @@ Most commands require Administrator privileges to execute. Since v2.8, WinSW wil
|
|||
|
||||
User documentation:
|
||||
|
||||
* [Installation guide](doc/installation.md) - Describes the installation process for different systems and .NET versions
|
||||
* [Installation guide](docs/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)
|
||||
* [Extensions](doc/extensions/extensions.md)
|
||||
* [Main XML configuration file](docs/xml-config-file.md)
|
||||
* [EXE configuration file](docs/exe-config-file.md)
|
||||
* [Logging and error reporting](docs/logging-and-error-reporting.md)
|
||||
* [Extensions](docs/extensions/extensions.md)
|
||||
* Use-cases:
|
||||
* [Self-restarting services](doc/selfRestartingService.md)
|
||||
* [Deferred file operations](doc/deferredFileOperations.md)
|
||||
* [Self-restarting services](docs/self-restarting-service.md)
|
||||
* [Deferred file operations](docs/deferred-file-operations.md)
|
||||
* Configuration Management:
|
||||
* [Puppet Forge Module](doc/puppetWinSW.md)
|
||||
* [Puppet Forge Module](docs/puppetWinSW.md)
|
||||
|
||||
Developer documentation:
|
||||
|
||||
|
|
@ -76,7 +75,7 @@ Developer documentation:
|
|||
|
||||
Contributions are welcome!
|
||||
No Contributor License Agreement is needed, just submit your pull requests.
|
||||
See the [contributing guidelines](./CONTRIBUTING.md) for more information.
|
||||
See the [contributing guidelines](CONTRIBUTING.md) for more information.
|
||||
|
||||
## License
|
||||
|
||||
|
|
|
|||
|
|
@ -26,6 +26,6 @@ More info about the wrapper is available in the projects GitHub repository.
|
|||
</metadata>
|
||||
<files>
|
||||
<file src="artifacts\WinSW.NET461.exe" target="lib\net461\WinSW.NET461.exe" />
|
||||
<file src="examples\sample-allOptions.xml" target="lib\net461\WinSW.NET461.xml" />
|
||||
<file src="samples\sample-complete.xml" target="lib\net461\WinSW.NET461.xml" />
|
||||
</files>
|
||||
</package>
|
||||
|
|
|
|||
|
|
@ -1,7 +0,0 @@
|
|||
# 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.
|
||||
|
||||
Use-cases:
|
||||
* Managing Logging levels of log4j
|
||||
* etc.
|
||||
|
|
@ -1,149 +0,0 @@
|
|||
## Puppet Module
|
||||
|
||||
WinSW can be managed using Puppet.
|
||||
|
||||
Please checkout the [Puppet Forge Page](http://forge.puppet.com/kenmaglio/winsw) for more information about specifics of this module.
|
||||
|
||||
# winsw
|
||||
|
||||
### Table of Contents
|
||||
|
||||
1. [Important](#important)
|
||||
1. [Description](#description)
|
||||
1. [Setup - The basics of getting started with winsw](#setup)
|
||||
* [Beginning with winsw](#beginning-with-winsw)
|
||||
1. [Usage - Configuration options and additional functionality](#usage)
|
||||
* [Additional Configurations](#additional-configuration-parameters)
|
||||
1. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
|
||||
1. [Limitations - OS compatibility, etc.](#limitations)
|
||||
1. [Development - Guide for contributing to the module](#development)
|
||||
|
||||
## Important
|
||||
|
||||
If you change the $service_id value, after you have installed the service, and you do not ensure abscent first, you will cause errors.
|
||||
The reason is because the code which tried to uninstall, will already have been effected.
|
||||
|
||||
Tested on Windows 10 and Windows Server 2012 R2.
|
||||
There shouldn't be any reason this wouldn't work on
|
||||
|
||||
## Description
|
||||
|
||||
This module encapsulates functionality of the WinSW service application wrapper.
|
||||
The development of that project is accredited: [https://github.com/kohsuke/winsw](https://github.com/kohsuke/winsw)
|
||||
|
||||
This module attempts to allow any executable with any arguments to be wrapped in a Windows Service.
|
||||
This will require files to be placed on the system in a managed path: EXE, XML, EXE.Config
|
||||
|
||||
### Derived Types:
|
||||
* install
|
||||
* service
|
||||
|
||||
Install will create the folders in $install_path, drop the files in that folder named $serviceid[.exe|.xml].
|
||||
Then after those are successfull, the defined type will install the service into the Service Manager.
|
||||
|
||||
Service will ensure the service is running.
|
||||
|
||||
### Beginning with winsw
|
||||
|
||||
By default, classifying a node with this class will not get you very far.
|
||||
It will test that the module will work and will run an instance of powershell.exe as a service.
|
||||
|
||||
You can take two approaches:
|
||||
|
||||
1. Use the Defined Types under Usage in your own module. They will automatically be created once you add this module ot your puppet file.
|
||||
1. You can build your own class that manages multiple services this way, if you so choose.
|
||||
1. You can classify a node with the winsw class, and use hiera to override the local variables.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage Pattern for Installing and Configuring
|
||||
Title = name of executable / service
|
||||
|
||||
<pre><code>
|
||||
winsw::install { 'MyService':
|
||||
ensure => present,
|
||||
service_name => $service_name,
|
||||
service_executable => $service_executable,
|
||||
service_argument_string => $service_argument_string,
|
||||
} ->
|
||||
winsw::service { 'MyService':
|
||||
ensure => running,
|
||||
}
|
||||
</code></pre>
|
||||
|
||||
Optional Parameters
|
||||
<pre><code>
|
||||
winsw_binary_version => $winsw_binary_version,
|
||||
install_path => $install_path,
|
||||
service_description => $service_description,
|
||||
service_env_variables => $service_env_variables,
|
||||
service_logmode => $service_logmode,
|
||||
</code></pre>
|
||||
|
||||
Usage Pattern for Uninstalling
|
||||
<pre><code>
|
||||
winsw::install { 'MyService':
|
||||
ensure => absent,
|
||||
}
|
||||
</code></pre>
|
||||
|
||||
### Additional Configuration Parameters
|
||||
|
||||
|
||||
To Specify Service Account to run service as
|
||||
<pre><code>
|
||||
service_user => 'your_serviceaccount',
|
||||
service_pass => 'your_serviceaccount_password',
|
||||
service_domain => 'your_serviceaccount_domain'
|
||||
</code></pre>
|
||||
|
||||
To Run Interactively (not service account cannot be used - only local system)
|
||||
<pre><code>
|
||||
service_interactive => $true
|
||||
</code></pre>
|
||||
|
||||
## Reference
|
||||
|
||||
The module includes embedded the winsw executable file, and provides a template for the configuration XML.
|
||||
It attepts to create whatever directories you need specified by $install_path
|
||||
Then drops the needed files in that path as $service_name(.exe|.xml)
|
||||
|
||||
Utilizing exec's against powershell this module will then manage the behavior flow of winsw commands.
|
||||
|
||||
## Known Side-Effects
|
||||
|
||||
On initial install, the output will show not only the Exec[install_serviceid], but also the Exec[rebuild_service_serviceid].
|
||||
This is expected as the config xml file is placed, which fires the notify on Exec[rebuild_service_serviceid].
|
||||
This notify is needed if a config xml file change happens. The service must be stopped, uninstalled, installed and started to take effect.
|
||||
|
||||
|
||||
## Limitations
|
||||
|
||||
Limitations for current release are really more around parameters which the native WinSW executable can take, which have not been implemented here yet.
|
||||
Right now only the basics to get an executable running, with arguments and environment variables are possible.
|
||||
|
||||
More will be added in later revisions.
|
||||
|
||||
If you need one specifically please open an issue here on github, and I will try to add that functionality quickly for you.
|
||||
|
||||
See: [https://github.com/kohsuke/winsw](https://github.com/kohsuke/winsw)
|
||||
|
||||
## Development
|
||||
|
||||
#### Please fork and submit pull requests
|
||||
|
||||
To setup local environment:
|
||||
<pre><code>
|
||||
puppet module install puppetlabs-powershell --version 2.1.0 --modulepath=[your path to modules here]
|
||||
puppet apply -v -e 'include winsw' --modulepath=[your path to modules here]
|
||||
</code></pre>
|
||||
You can include --noop if you don't want to apply, however service actions will fail as it won't actually install.
|
||||
|
||||
If you run an elevated command prompt, you can navigate to the service executable directory.
|
||||
Then you can use these to test states of your service and the module. (note MyService is your servie name)
|
||||
<pre><code>
|
||||
MyService.exe stop
|
||||
MyService.exe uninstall
|
||||
MyService.exe start
|
||||
MyService.exe install
|
||||
</code></pre>
|
||||
|
|
@ -3,9 +3,9 @@
|
|||
:movie_camera: You can find the code dive session recorded video [here](https://youtu.be/_adhRj19ESY).
|
||||
|
||||
```
|
||||
|_ doc
|
||||
|_ docs
|
||||
|_ eng
|
||||
|_ examples
|
||||
|_ samples
|
||||
|_ src
|
||||
|_ Core
|
||||
| |_ ServiceWrapper
|
||||
|
|
@ -18,9 +18,9 @@
|
|||
|_ Test/winswTest
|
||||
```
|
||||
|
||||
## :open_file_folder: examples
|
||||
## :open_file_folder: samples
|
||||
|
||||
This folder contains templates for configuration files. *sample-minimal.xml* contains a template for mandatory configurations and *sample-allOptions.xml* contains all possible configurations with documentation.
|
||||
This folder contains templates for configuration files. *sample-minimal.xml* contains a template for mandatory configurations and *sample-complete.xml* contains all possible configurations with documentation.
|
||||
|
||||
## :open_file_folder: Core
|
||||
|
||||
|
|
@ -0,0 +1,7 @@
|
|||
# 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.
|
||||
|
|
@ -5,8 +5,8 @@ These extensions allow to alter the behavior of the Windows service in order to
|
|||
|
||||
## 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
|
||||
* [Shared Directory Mapper](shared-directory-mapper.md) - Allows mapping shared drives before starting the executable
|
||||
* [Runaway Process Killer](runaway-process-killer.md) - Termination of processes started by the previous runs of WinSW
|
||||
|
||||
## Developer guide
|
||||
|
||||
|
|
@ -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](../xml-config-file.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.
|
||||
|
|
@ -11,7 +11,7 @@ Since: WinSW 2.0.
|
|||
|
||||
## 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](../xml-config-file.md). Configuration sample:
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="utf-8" ?>
|
||||
|
|
@ -9,7 +9,7 @@ Since: WinSW 2.0.
|
|||
|
||||
## Usage
|
||||
|
||||
The extension can be configured via the [XML configuration file](../xmlConfigFile.md).
|
||||
The extension can be configured via the [XML configuration file](../xml-config-file.md).
|
||||
Configuration sample:
|
||||
|
||||
```xml
|
||||
|
|
@ -7,7 +7,7 @@ This page provides WinSW installation guidelines for different cases.
|
|||
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](xmlConfigFile.md) for more details)
|
||||
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.
|
||||
|
|
@ -33,7 +33,7 @@ The example below is a primitive example being used in the Jenkins project:
|
|||
</service>
|
||||
```
|
||||
|
||||
The full specification of the configuration file is available [here](xmlConfigFile.md).
|
||||
The full specification of the configuration file is available [here](xml-config-file.md).
|
||||
|
||||
### Step 3. Service registration
|
||||
|
||||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
This page describes the configuration file, which controls the behavior of the Windows service.
|
||||
|
||||
You can find configuration file samples in the [examples](../examples) directory of the source code repository.
|
||||
You can find configuration file samples in the [samples](../samples) directory of the source code repository.
|
||||
Actual samples are being also published as a part of releases on GitHub and NuGet.
|
||||
|
||||
## File structure
|
||||
|
|
@ -90,7 +90,7 @@ Multiple elements can be used to specify multiple dependencies.
|
|||
|
||||
Optionally set a different logging directory with `<logpath>` and startup `mode`: append (default), reset (clear log), ignore, roll (move to `\*.old`).
|
||||
|
||||
See the [Logging and error reporting](loggingAndErrorReporting.md) page for more info.
|
||||
See the [Logging and error reporting](logging-and-error-reporting.md) page for more info.
|
||||
|
||||
### Arguments
|
||||
|
||||
|
|
@ -22,7 +22,7 @@
|
|||
This configuration file should be placed near the WinSW executable, the name should be the same.
|
||||
E.g. for myapp.exe the configuration file name should be myapp.xml
|
||||
|
||||
You can find more information about configuration options here: https://github.com/kohsuke/winsw/blob/master/doc/xmlConfigFile.md
|
||||
You can find more information about configuration options here: https://github.com/winsw/winsw/blob/master/docs/xml-config-file.md
|
||||
-->
|
||||
<service>
|
||||
|
||||
|
|
@ -230,7 +230,7 @@ SECTION:Logging
|
|||
Default mode: append
|
||||
|
||||
Each mode has different settings.
|
||||
See https://github.com/kohsuke/winsw/blob/master/doc/loggingAndErrorReporting.md for more details
|
||||
See https://github.com/winsw/winsw/blob/master/docs/logging-and-error-reporting.md for more details
|
||||
-->
|
||||
<log mode="append">
|
||||
<!--
|
||||
|
|
@ -292,7 +292,7 @@ SECTION: Other options
|
|||
<!--
|
||||
SECTION: Extensions
|
||||
This configuration section allows specifying custom extensions.
|
||||
More info is available here: https://github.com/kohsuke/winsw/blob/master/doc/extensions/extensions.md
|
||||
More info is available here: https://github.com/winsw/winsw/blob/master/docs/extensions/extensions.md
|
||||
-->
|
||||
|
||||
<!--
|
||||
|
|
@ -23,8 +23,8 @@
|
|||
This configuration file should be placed near the WinSW executable, the name should be the same.
|
||||
E.g. for myapp.exe the configuration file name should be myapp.xml
|
||||
|
||||
You can find more information about the configuration options here: https://github.com/kohsuke/winsw/blob/master/doc/xmlConfigFile.md
|
||||
Full example: https://github.com/kohsuke/winsw/blob/master/examples/sample-allOptions.xml
|
||||
You can find more information about the configuration options here: https://github.com/winsw/winsw/blob/master/docs/xml-config-file.md
|
||||
Full example: https://github.com/winsw/winsw/blob/master/samples/sample-complete.xml
|
||||
-->
|
||||
<service>
|
||||
|
||||
|
|
@ -17,7 +17,7 @@ namespace winswTests.Configuration
|
|||
[Test]
|
||||
public void AllOptionsConfigShouldDeclareDefaults()
|
||||
{
|
||||
ServiceDescriptor desc = Load("allOptions");
|
||||
ServiceDescriptor desc = Load("complete");
|
||||
|
||||
Assert.That(desc.Id, Is.EqualTo("myapp"));
|
||||
Assert.That(desc.Caption, Is.EqualTo("MyApp Service (powered by WinSW)"));
|
||||
|
|
@ -54,7 +54,7 @@ namespace winswTests.Configuration
|
|||
Assert.That(directory, Is.Not.Null);
|
||||
}
|
||||
|
||||
string path = Path.Combine(directory, $@"examples\sample-{exampleName}.xml");
|
||||
string path = Path.Combine(directory, $@"samples\sample-{exampleName}.xml");
|
||||
Assert.That(path, Does.Exist);
|
||||
|
||||
XmlDocument dom = new XmlDocument();
|
||||
|
|
|
|||
|
|
@ -68,7 +68,7 @@ $@"<service>
|
|||
Assert.Ignore();
|
||||
|
||||
var winswId = "myAppWithRunaway";
|
||||
var extensionId = "runawayProcessKiller";
|
||||
var extensionId = "runaway-process-killer";
|
||||
var tmpDir = FilesystemTestHelper.CreateTmpDirectory();
|
||||
|
||||
// Spawn the test process
|
||||
|
|
|
|||
|
|
@ -20,8 +20,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RunawayProcessKiller", "Plu
|
|||
EndProject
|
||||
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{AA414F46-B863-473A-A0E0-C2971B3396AE}"
|
||||
ProjectSection(SolutionItems) = preProject
|
||||
..\examples\sample-allOptions.xml = ..\examples\sample-allOptions.xml
|
||||
..\examples\sample-minimal.xml = ..\examples\sample-minimal.xml
|
||||
..\samples\sample-complete.xml = ..\samples\sample-complete.xml
|
||||
..\samples\sample-minimal.xml = ..\samples\sample-minimal.xml
|
||||
EndProjectSection
|
||||
EndProject
|
||||
Global
|
||||
|
|
|
|||
Loading…
Reference in New Issue