winsw/doc/installation.md

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+

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 for more about this. 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). 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 for more details.