mirror of https://github.com/winsw/winsw
78 lines
3.4 KiB
Markdown
78 lines
3.4 KiB
Markdown
|
WinSW Installation Guide
|
||
|
|
======
|
||
|
|
|
||
|
|
This page provides WinSW installation guidelines for different cases.
|
||
|
|
|
||
|
|
### Basic setup
|
||
|
|
|
||
|
|
You write the configuration file that defines your service.
|
||
|
|
The example below is a primitive example being used in the Jenkins project:
|
||
|
|
|
||
|
|
```
|
||
|
|
<service>
|
||
|
|
<id>jenkins</id>
|
||
|
|
<name>Jenkins</name>
|
||
|
|
<description>This service runs Jenkins continuous integration system.</description>
|
||
|
|
<env name="JENKINS_HOME" value="%BASE%"/>
|
||
|
|
<executable>java</executable>
|
||
|
|
<arguments>-Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080</arguments>
|
||
|
|
<logmode>rotate</logmode>
|
||
|
|
</service>
|
||
|
|
```
|
||
|
|
|
||
|
|
You'll rename `winsw.exe` into something like `jenkins.exe`, then you put this XML file as `jenkins.xml`.
|
||
|
|
The executable locates the configuration file via this file name convention.
|
||
|
|
You can then install the service like:
|
||
|
|
|
||
|
|
```
|
||
|
|
jenkins.exe install
|
||
|
|
```
|
||
|
|
|
||
|
|
... and you can use the exit code from these processes to determine whether the operation was successful.
|
||
|
|
There are other commands to perform other operations, like `uninstall`, `start`, `stop`, and so on.
|
||
|
|
|
||
|
|
Once the service is installed, you can start it from Windows service manager. Windows will start `jenkins.exe`,
|
||
|
|
then `jenkins.exe` will launch the executable specified in the configuration file (Java in this case).
|
||
|
|
If this process dies, winsw will exit itself, and the service will be considered stopped.
|
||
|
|
|
||
|
|
### Making WinSW compatible with .NET runtime 4.0+
|
||
|
|
|
||
|
|
<!--TODO: modify the text. Newer => Modern-->
|
||
|
|
Newer versions of Windows (confirmed on Windows Server 2012, possibly with Windows 8, too) do not ship with .NET runtime `2.0`, which is what `winsw.exe` is built against.
|
||
|
|
This is because unlike Java, where a newer runtime can host apps developed against earlier runtime, .NET apps need version specific runtimes.
|
||
|
|
|
||
|
|
One way to deal with this is to ensure that `.NET 2.0` runtime is installed through your installer, but another way is to declare that `winsw.exe` can be hosted on `.NET 4.0` runtime by creating an app config file `winsw.exe.config`.
|
||
|
|
|
||
|
|
```
|
||
|
|
<configuration>
|
||
|
|
<startup>
|
||
|
|
<supportedRuntime version="v2.0.50727" />
|
||
|
|
<supportedRuntime version="v4.0" />
|
||
|
|
</startup>
|
||
|
|
</configuration>
|
||
|
|
```
|
||
|
|
|
||
|
|
The way the runtime finds this file is by naming convention, so don't forget to rename a file based on your actual executable name.
|
||
|
|
See [this post](http://www.davidmoore.info/2010/12/17/running-net-2-runtime-applications-under-the-net-4-runtime/) for more about this.
|
||
|
|
<!--TODO: Modify the text-->
|
||
|
|
To our knowledge, none of the other flags are needed.
|
||
|
|
|
||
|
|
### 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 (see [more discussions](http://msdn.microsoft.com/en-us/library/bb629393.aspx)).
|
||
|
|
This adds some delay to the launch of the service, and more importantly, it prevents winsw from running in a server that has no internet connection.
|
||
|
|
This is because a part of the signature verification involves checking certificate revocation list.
|
||
|
|
|
||
|
|
To prevent this problem, create `myapp.exe.config` in the same directory as `myapp.exe` (renamed `winsw.exe`) and put the following in it:
|
||
|
|
|
||
|
|
```
|
||
|
|
<configuration>
|
||
|
|
<runtime>
|
||
|
|
<generatePublisherEvidence enabled="false"/>
|
||
|
|
</runtime>
|
||
|
|
</configuration>
|
||
|
|
```
|
||
|
|
|
||
|
|
See [KB 936707](http://support.microsoft.com/kb/936707) for more details.
|